Re: Use PSR coding guidelines in php.net docs (instead of PEAR-CS)

On Fri, 4 Sep 2020 at 16:49, Tymoteusz Motylewski <[email protected]>
wrote:

> Hi,
> Right now (as stated here: http://doc.php.net/tutorial/style.php) the
> code style used in PHP documentation is PEAR-CS
> https://pear.php.net/manual/en/coding-standards.php
>
> The problem is that:
> - PEAR-CS does not cover new PHP versions (e.g. namespaces are missing)
> - it has a very little adoption
> - it's not maintained
> - the whole PEAR is becoming obsolete
>
> I suggest that PSR-12 should become the coding standard for PHP docs.
>
> I've created a ticket https://bugs.php.net/bug.php?id=80060
> and got redirected to mailing list
>
> "The PSRs are unofficial community-written guidelines for interoperability
> between frameworks and projects. If PHP were to follow their guidelines
> then that could be interpreted as an endorsement - reasoning that extends
> to other areas, such as why php.net does not employ a popular framework."
>
> I would understand the concern if we were talking about certain commercial
> product, tool or framework.
> Here we're talking about a standard which:
> - has a broad acceptance in the PHP industry
> - doesn't have an alternative thus became the one standard in the industry
> - its adopted by many tools and framework from the PHP community
>
> > "If PHP were to follow their guidelines then that could be interpreted
> as an endorsement "
>
> I agree, and I would love PHP to either set standards, or to endorse
> existing standards. Because right now you can read this argument that PHP
> is endorsing obsolete PEAR-CS, which I hope is not true ;)
>

The PHP documentation doesn't endorse any coding style as the examples
aren't very consistent, and I'd argue most of the examples follow PSR-2
more or less.
For the sake of argument, let's say PSR-2 is the current official
coding-standard, should we still "upgrade" to PSR-12 although it is
incompatible with PSR-2?
If so, which tooling is available or need to be created such that:
 - Coding style is enforced
 - Automatic fixes, or pre-commit hooks which denies the commit
Which works on the current PHP Documentation infrastructure (SVN) and can
deal with Docbooks the format in which the PHP doc is written.

Moreover, those rather superficial changes put a lot of strain on
translations because now a bunch of legit pages which need to be updated
are buried under the tons of pages which need coding style updates. And
automatic fixes and revision updates for translations is not something
doable in the current state of affairs.

And what happens if the FIG implodes on itself and another body creates a
new coding style taking into account features which might only exist 5
years from now? Should we then change again?


> In general I would like to see more PSR being mentioned in PHP docs, e.g.
> PSR-4 in https://www.php.net/manual/en/language.oop5.autoload.php
>

PSRs are something completely independent from PHP, sure it is ubiquitous
but one could have said the same about PSR-0 before.
Therefore "trends" (using this word for lack of something better I can
think of) shouldn't be mentioned in the documentation IMHO.
Otherwise one can say we should mention frameworks such as Symfony, Laminas
(previous Zend), Yii, Laravel, etc.


> In comparison to other languages it's hard to learn PHP from the official
> docs, as no tooling or best practices are outlined e.g. I did not find any
> mention of composer in the docs.
>

The PHP documentation is a language reference and extension reference akin
to how Python does it (to name one example).
The PHP documentation has already a tutorial but it might be severely out
of date, see: https://www.php.net/manual/en/tutorial.php


> I would like to hear your opinion about this topic.
> Thanks
> Tymoteusz
>

As currently presented, it seems that your complaint is about the wording
on one page meant to help people contribute to the PHP documentation.
And as such I find this proposal lacking any substance.

Best regards

George P. Banyard