[RFC] [Discussion] Using and Mentioning Third-party Packages in PHP Documentation and Web Projects

On Mon, Aug 26, 2024, at 10:54 AM, Deleu wrote:

Good idea, I have tweaked that text as suggested. Thanks. Jim

On Mon, Aug 26, 2024, at 1:06 PM, Bob Weinand wrote:

There's two separate questions here, I think, which should probably be addressed separately. One is whether PHP.net code can *use* third party libraries (and be open about it). Eg, would it be OK if Phd (the documentation compiler) used Composer for autoloading? Used symfony/serializer or crell/serde in some way? Used ramsey/uuid as an internal implementation detail? Right now, the answer is de facto no, with some unclear exceptions. I very firmly believe the answer should be a strong YES, or at least a "mostly", because doing otherwise hamstrings our ability to actually do the much-needed work of keeping the infra going. The other is whether the documentation should recognize the rest of the ecosystem, or be "just" "things in the php org on Github." I can definitely see the potential for scope creep here, and we should be mindful of that, but at the same time, having an official first-party "where to start with the ecosystem" place is extremely valuable! Sending someone into PHP without recognizing the existence of Composer, which has basically no competition, is doing them a gross disservice. Telling them about PHPUnit, which is overwhelmingly the most popular testing system but there are others (mostly built on top of it), I would lean yes but I can see the argument against. Recommending a template engine and listing just Twig and Blade but not Latte, for example, I can totally see where that becomes an issue and why we wouldn't want to do that. My recommendation on the GitHub thread was, and still is, to make it a one-off vote in each case. We had a one-off vote to recognize the Foundation on php.net and direct people to it. I'd favor a one-off vote to allow talking about Composer/Packagist in the docs, and I would vote yes on it. I'd probably vote no for a one-off vote to mention Twig. PHP.net is the starting point for people in the PHP ecosystem, good or bad. We don't need to take ownership of the whole ecosystem or documentation therein, but at least providing jumping off points to obvious sources (Composer/Packagist, phptherightway.com, etc.) would be doing a good service for our users. --Larry Garfield

On Mon, Aug 26, 2024 at 3:12 PM Bob Weinand <bobwei9@hotmail.com> wrote:

Since your message was somewhat ambiguous to me, I would like to take this opportunity to request clarification from Jim. I read this RFC as an opportunity to allow community-driven PHP projects to be embraced when it suits PHP's internals needs. For instance, I remember a few years ago a conversation about rebuilding the php.net website. The current "unwritten" rule was used to impose that a new PHP website could not use any existing PHP Framework as to not "endorse" any particular project. Same thing goes for the RFC Voting process, PSRs, Composer, etc. In a way, I agree with Bob's take that the php.net documentation should not be used to *document* 3rd-party tooling, but my interpretation of the RFC has nothing to do with documenting 3rd-party tools but instead its about mentioning or even relying on them. Current discussion about Generics going on talks a lot about phpstan and psalm and whatever comes out of the work put into Generics, I would definitely be in favour of PHP docs mentioning how Generics is already present today with those tools. Current work-in-progress from the Foundation in regards to revamping pecl involves (as far as I know) providing PHP Extensions via Composer which would be something that said "unwritten" rule could be mentioned for opposing such approach. There's also PHP community members that would be willing to work on a new RFC automation tool to improve on the process that has recently been mentioned as "suboptimal" [1]. Such community members would certainly opt to build this upon Symfony, Laravel, Slim or anything more convenient than vanilla PHP and such "unwritten" rule keeps us chained to suboptimal infrastructure. [1] https://externals.io/message/124843#124860

On Mon, 26 Aug 2024, Bob Weinand wrote:

I think this is short-sighted. Currently, our main website, php.net, does not have useful installation instructions. We have a "Download" tab, which points to tarballs. Who still installs tarballs like this? Nobody does. It's either distribution packages, or installers such as XAMPP, or MAMP, or whatever. We are doing our (potential) users a disservice by not explaining the reasonable ways of installing PHP. We should replace our "Download" page with something that people would actually benefit from. Just like our home page is just boring release announcements. This should have much more interesting stuff such as how, and when, to use the great new features that we have been adding in the last decade.

I also think we are not doing PHP a favour by refusing to mention the main way how developers now install libraries: Composer. It doesn't have to be a comprehensive guide, but it is ludicrous to not even have a page in our documentation that describes how modern PHP applications get (and should) get bootstrapped. We will have the same argument eith PIE (working title) soon too. Should we promote a specific framework? No, probably not. Should we endeavour to rewrite all of our internal stuff in Symfony, or Laravel, or Nette, or Zend Framework. Also very much not. But not even have a *link* to Composer and how it used for modern PHP development is just plain stupid, like having a most light hint at how you effectively debug PHP code. Our users *want* to know how to do things properly, and the documentation needs to reflect that.

Where PHP originally had the arguably the best documentation, this has slipped. Our langauge sections in the manual are dry, and only explain what the language syntax are. It doesn't describe how these features are useful, when you might want to use them, what related development patterns and practises are. This *absolutely* belongs in our documentation.

Why not? It's how modern PHP development works. We don't have to go into the intricacies on how PSRs get developed, but not even mentioning best practises doesn't seem particularly useful.

And that is how you will find that the "new" languages will "win". If we don't promote how modern PHP Development works, then there will be more "PHP, a fractal of bad design" articles to come for decades. We *must* do better than this. It probably doesn't all need to be in the documentation (doc-en), but it absolutely belongs on our website. cheers, Derick

Hey all Am 26.08.24 um 20:06 schrieb Bob Weinand:

I see this a bid differently to be honest. While I understand that using third party packages in our internal tools might make things easier in the short term it will cause a lot or additional work in the long term. Currently we have a lot of small scripts that do one thing. And they do it for a long time with very little maintenance effort. Blowing these scripts up with third-party libraries will mean that we will have to put in much more maintenance effort for either keeping the dependencies up to date or mostly rewriting the script the moment a change needs to happen as the libraries will be outdated. There are though some actual console applications like Pdt where it might be valid to use third party dependencies. But also here I'd ask whether the maintainability will be increased. A totally different question though is whether we actually need to maintain a special tool for building the docs or whether we can use a pre-existing tool for that. I am mainly thinking about either phpDocumentor or a default docbook renderer. But that is a totally differnt topic IMO. So I'd see this exactly the other way around: usage for infra needs very careful consideration to not increase the maintenance-burden on those that actually 'do' the maintenance. But mentioning - and encouraging - best practices for developing PHP-Applications is something that the PHP-Project should actively provide.

If I go to PHP.net, I want to learn about PHP. As an end user I don't really care whether it's the runtime internals or the ecosystem. It is a manual for PHP. And as such it should provide me with what we consider Best Practices. My 0.02€ from having done some maintenance on php.net. Cheers Andreas

On Monday, 26 August 2024 at 20:06, Bob Weinand <bobwei9@hotmail.com> wrote: > I do in particular reject the notion that we should document third-party projects (usage for our infra is fine). > > The point of the PHP documentation is to describe the PHP runtime and PECL extensions, which are both officially distributed through php.net. > > Anything not related to these does not belong into the manual, much less into core documentation (like language/oop5 autoload.xml, to take the example from https://github.com/php/doc-en/pull/3677/files). > > Changing this current unwritten rule is an invitation to implicitly promote specific projects. The question is really where does it end? Would we for example also mention PSRs as "widely followed guidelines for interoperability" or something? It's a strong invitation for some scope creep. > > As such I strongly condemn the idea of inclusion of this guideline. > > There are, ultimately, enough ways for people to learn about the PHP ecosystem, the php.net documentation is none of them. If I go to php.net, it's because I want to learn about the runtime, not its ecosystem. As someone that has maintained the docs for a few years, there are a couple of misconceptions here. We ***already*** promote some projects in favour of others, namely in the installation sections. We promote some cloud vendors, but not all. [1] We promote some installation methods, but not all, and when one project wrote docs to be included it has remained in limbo for 2 years. [2] Moreover, we promote some conferences, but not others (and this is mainly due to if people figure out how to submit a PR on web-php). We even have a calendar of meetups, which is all likely hood is severely out of date: https://www.php.net/cal.php > Moreover, PECL extensions are part of the PHP ecosystem and not the runtime, so why do *some* PECL extension have the right to live on the php.net website, but not others? And frankly, I would prefer that we would get rid of PECL extension from the php.net documentation, as most of them are in a terrrible state with no way for us to easily improve on them, except that it is somehow the responsability of the doc team to do it. As such the statement that the php.net website and it's documentation is not for people to learn about the PHP ecosystem seems blatently false. Because it is, and has been for a very long time. Thus, in my opinion, your current position is non-sensical. Either the php.net website should not endorse *any* external project, which mean no mention of Apache, Cloud vendors, PECL extensions, NGNIX, XAMPP, WampServer, etc. Or we continue to do this, and provide clear guidelines and procedures on how a project can be added onto the php.net documentation. Composer is a de-facto standard of the PHP ecosystem, more than the V8js, Seaslog, or Recode PECL extensions. The fact we don't even _mention_ Composer, or another place where one can learn about the PHP ecosystem on the php.net website is frankly outrageous. The Python.org website mentions Pypi, various IDEs, and even books that people can use to learn Python. Heck, it even has a community Job board. The go.dev mainpage even promotes companies that use Go. Similarly rust-lang.org promotes companies that use Rust in production and IDEs that have first class support for writing Rust. ruby-lang.org has a community tab, but even the documentation tab promotes external tutorials. Similarly elixir-lang.org does the same and promotes companies, and books. I'm pretty sure if I continue looking at the websites for various programming languages I can find more and more examples. And the reson for this, is people new to the language don't know where to go looking and which resources are somewhat reasonable. Having the php.net website point to various curated tutorials, industry standard packages and tools, seems fairly natural. And not doing this clearly makes us an outlier rather than the norm. This is not to say we should mention everything under the sun on the website, but this is where designing a process on how to decide on this comes into place. Best regards, Gina P. Banyard [1] https://www.php.net/manual/en/install.cloud.php [2] https://github.com/php/doc-en/pull/1674

Hi Am 2024-09-25 01:45, schrieb Jim Winstead:

Thank you. I've used your reminder as the opportunity to catch up with this thread after my vacation. I'm likely going to vote “no” on your RFC, because I do not believe that your proposed statement of principle makes the situation any *less* vague. It just makes the situation vague in a different way, because there are no guidelines regarding what is acceptable and what is not, as also mentioned by others in this RFC's discussion thread. Best regards Tim Düsterhus