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

5 years ago by Tymoteusz Motylewski — view source — reply

unread

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 ;)

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

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.

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

5 years ago by G. P. B. — view source — reply

unread

On Fri, 4 Sep 2020 at 15:50, Tymoteusz Motylewski t.motylewski@gmail.com
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 ;)

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

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.

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

This is the wrong list to have these discussions, please post on the PHP
Documentation list instead.

Best regards

George P. Banyard