Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:111840
MIME-Version: 1.0
Date: Fri, 4 Sep 2020 15:49:43 +0200
Message-ID: <CABphOUfYdVTB5DpdceeLqZoQEz2rN+7EEhN1=emAbvsSaOHCGw@mail.gmail.com>
To: internals@lists.php.net
Content-Type: multipart/alternative; boundary="000000000000bcb55805ae7d24a3"
Subject: Use PSR coding guidelines in php.net docs (instead of PEAR-CS)
From: t.motylewski@gmail.com (Tymoteusz Motylewski)

--000000000000bcb55805ae7d24a3
Content-Type: text/plain; charset="UTF-8"

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

--000000000000bcb55805ae7d24a3--