Hi
after suggesting the use of ucfirst(strtolower(...)) casing for acronyms
within a classname of a draft RFC, I was made aware of previous class
naming RFC (June 2017) that required the use of PascalCase for class
names, with the exception of acronyms which must be completely uppercased:
https://wiki.php.net/rfc/class-naming
I'd like to propose to revisit this earlier decision for the following
reasons. Before writing an RFC I'd like have some pre-discussion to
gauge opinions.
- It is not consistently applied:
a)
As an example ext/json has 'JsonException' which should've been
JSONException according to the RFC's results. In fact JsonException's
RFC was created just 3 months (!) after the class naming RFC in
September 2017:
https://wiki.php.net/rfc/json_throw_on_error
b)
Another example is ext/curl which has both 'CurlHandle' and 'CURLFile'.
CURLFile predates the RFC, but there's also CURLStringFile which was
added in PHP 8.1 and likely followed CURLFile's naming for consistency,
but violating the RFC and being inconsistent with CurlHandle.
c)
ext/random's Random\Engine\PcgOneseq128XslRr64 would've needed to be
called Random\Engine\PCGOneseq128XSLRR64 according to the class naming RFC.
d)
The accepted, but not yet implemented, "PDO driver specific sub-classes"
RFC uses Pdo<Driver>, e.g. PdoOdbc instead of PDOODBC:
https://wiki.php.net/rfc/pdo_driver_specific_subclasses
- It decreases readability.
Especially if multiple acronyms follow each other. One example is the
PCGOneseq128XSLRR64 mentioned above: It's not clear that XSL
(XorShiftLow) and RR (RandomlyRotate) are two different acronyms.
Likewise PDOODBC is much harder to parse than PdoOdbc.
Another example might be JavaScript's XMLHttpRequest which incidentally
mixes both variants. According to the class naming RFC it would need to
be called XMLHTTPRequest, resulting in 8 consecutive uppercase characters.
- Several commonly used userland libraries make a different choice.
- Symfony's HttpFoundation:
https://github.com/symfony/symfony/tree/6.4/src/Symfony/Component/HttpFoundation - Symfony's CssSelector:
https://github.com/symfony/symfony/tree/6.4/src/Symfony/Component/CssSelector - Laravel's HtmlString:
https://github.com/laravel/framework/blob/10.x/src/Illuminate/Support/HtmlString.php - PSR-7: https://www.php-fig.org/psr/psr-7/
- PSR-18: https://www.php-fig.org/psr/psr-18/
- ramsey/uuid: https://github.com/ramsey/uuid/tree/4.x/src
- Flysystem is a little inconsistent, but has 'Ftp':
https://github.com/thephpleague/flysystem/tree/3.x/src/Ftp - PHPUnit is a little inconsistent, but has 'Xml' and 'Json':
https://github.com/sebastianbergmann/phpunit/tree/main/src/Util - Doctrine is also a little inconsistent, but has 'Dsn' and 'Sql' (but
also 'SQL'):
https://github.com/doctrine/dbal/tree/3.6.x/src/Schema/Visitor and
https://github.com/doctrine/dbal/blob/3.6.x/src/Tools/DsnParser.php
Best regards
Tim Düsterhus
Hi
after suggesting the use of ucfirst(strtolower(...)) casing for acronyms
within a classname of a draft RFC, I was made aware of previous class
naming RFC (June 2017) that required the use of PascalCase for class
names, with the exception of acronyms which must be completely uppercased:[...]
2. It decreases readability.Especially if multiple acronyms follow each other. One example is the
PCGOneseq128XSLRR64 mentioned above: It's not clear that XSL
(XorShiftLow) and RR (RandomlyRotate) are two different acronyms.Likewise PDOODBC is much harder to parse than PdoOdbc.
Another example might be JavaScript's XMLHttpRequest which incidentally
mixes both variants. According to the class naming RFC it would need to
be called XMLHTTPRequest, resulting in 8 consecutive uppercase characters.
Thanks for bringing this up as readability is indeed an issue for me with
all caps acronyms. I would much prefer Acronyms to be treated as words as
this is how most people seem to use them anyway.
Hi Tim
Hi
after suggesting the use of ucfirst(strtolower(...)) casing for acronyms within a classname of a draft RFC, I was made aware of previous class naming RFC (June 2017) that required the use of PascalCase for class names, with the exception of acronyms which must be completely uppercased:
https://wiki.php.net/rfc/class-naming
I'd like to propose to revisit this earlier decision for the following reasons. Before writing an RFC I'd like have some pre-discussion to gauge opinions.
- It is not consistently applied:
[...]
I think it's a good idea to change the rules to reality as much as possible.
Especially given that recent additions seem to follow what you're proposing.
- It decreases readability.
[...]
Agreed.
- Several commonly used userland libraries make a different choice.
- Symfony's HttpFoundation: https://github.com/symfony/symfony/tree/6.4/src/Symfony/Component/HttpFoundation
- Symfony's CssSelector: https://github.com/symfony/symfony/tree/6.4/src/Symfony/Component/CssSelector
- Laravel's HtmlString: https://github.com/laravel/framework/blob/10.x/src/Illuminate/Support/HtmlString.php
- PSR-7: https://www.php-fig.org/psr/psr-7/
- PSR-18: https://www.php-fig.org/psr/psr-18/
- ramsey/uuid: https://github.com/ramsey/uuid/tree/4.x/src
- Flysystem is a little inconsistent, but has 'Ftp': https://github.com/thephpleague/flysystem/tree/3.x/src/Ftp
- PHPUnit is a little inconsistent, but has 'Xml' and 'Json': https://github.com/sebastianbergmann/phpunit/tree/main/src/Util
- Doctrine is also a little inconsistent, but has 'Dsn' and 'Sql' (but also 'SQL'): https://github.com/doctrine/dbal/tree/3.6.x/src/Schema/Visitor and https://github.com/doctrine/dbal/blob/3.6.x/src/Tools/DsnParser.php
Best regards
Tim Düsterhus
Kind regards
Niels
Hi Tim
Hi
after suggesting the use of ucfirst(strtolower(...)) casing for acronyms within a classname of a draft RFC, I was made aware of previous class naming RFC (June 2017) that required the use of PascalCase for class names, with the exception of acronyms which must be completely uppercased:
https://wiki.php.net/rfc/class-naming
I'd like to propose to revisit this earlier decision for the following reasons. Before writing an RFC I'd like have some pre-discussion to gauge opinions.
- It is not consistently applied:
[...]I think it's a good idea to change the rules to reality as much as possible.
Especially given that recent additions seem to follow what you're proposing.
I agree. Using uppercase for the first letter in an acronym and
lowercase for subsequent letters appears to be prevalent in many
userland libraries, so it seems to be what users expect.
Since class names in PHP aren't case-sensitive, there should be no BC
concerns for changing existing classes to fit this new casing (for
Reflection, debug, and documentation purposes). That is, if we wanted to
also update all existing class names in PHP that contain acronyms (e.g.,
DOMDocument -> DomDocument, SimpleXMLElement -> SimpleXmlElement, etc.).
--
Cheers,
Ben
I agree. Using uppercase for the first letter in an acronym and
lowercase for subsequent letters appears to be prevalent in many
userland libraries, so it seems to be what users expect.Since class names in PHP aren't case-sensitive, there should be no BC
concerns for changing existing classes to fit this new casing (for
Reflection, debug, and documentation purposes). That is, if we wanted
to also update all existing class names in PHP that contain acronyms
(e.g., DOMDocument -> DomDocument, SimpleXMLElement ->
SimpleXmlElement, etc.).
This prevalence may stem from various CS checks enforcing/suggesting the
naming like that based on their implementation/interpretation of
CamelCaps name checks, often related to PSR4.
Along the same lines, I'm aware of CS-like tools enforcing the use of
PHP native class names to be in the case as defined in PHP (mostly to
prevent confusion when people search for more info on the class and
such, even though it doesn't matter for the actual use).
With the above in mind, I wonder how much confusion/code churn renaming
existing classes will cause and if that's worth it, especially as the
suggested case for the PHP native class will likely be determined by the
version on which the tooling is being run. I.e. tool being run on PHP
8.2 suggest DOMDocument, tool being run on PHP 8.4 would flag
DOMDocument and suggest DomDocument...
Smile,
Juliette
With the above in mind, I wonder how much confusion/code churn renaming
existing classes will cause and if that's worth it, especially as the
suggested case for the PHP native class will likely be determined by the
version on which the tooling is being run. I.e. tool being run on PHP
8.2 suggest DOMDocument, tool being run on PHP 8.4 would flag
DOMDocument and suggest DomDocument...
Since the names are case-insensitive, if the tools continue to enforce,
for example, DOMDocument instead of DomDocument, would that cause
problems if Reflection, var_dump, etc. began reporting the class name as
DomDocument?
In other words, if the tools did not change, would there be any churn?
Cheers,
Ben
With the above in mind, I wonder how much confusion/code churn
renaming existing classes will cause and if that's worth it,
especially as the suggested case for the PHP native class will likely
be determined by the version on which the tooling is being run. I.e.
tool being run on PHP 8.2 suggest DOMDocument, tool being run on PHP
8.4 would flag DOMDocument and suggest DomDocument...Since the names are case-insensitive, if the tools continue to
enforce, for example, DOMDocument instead of DomDocument, would that
cause problems if Reflection, var_dump, etc. began reporting the class
name as DomDocument?In other words, if the tools did not change, would there be any churn?
Tools wouldn't need to change to change their messaging on this.
In my experience, the case of the class as defined by PHP would be
retrieved from PHP itself, so without the tooling changing, if PHP
changes the case, the tooling will demand the new casing of the class
names if run on a PHP version using the new casing. (and the old casing
when run on an older PHP version)
Might be clearer via the below pseudo-code of typical logic used in
tooling for checks like this:
$declared_classes = [];
if (empty($declared_classes)) {
$declared_classes = get_declared_classes();
$declared_classes = array_combine($declared_classes,
$declared_classes);
$declared_classes = array_change_key_case($declared_classes,
CASE_LOWER);
}
....
$seenClassLc = strtolower($seenClass);
if (isset($declared_classes[$seenClassLc]) && $seenClass !==
$declared_classes[$seenClassLc]) {
// Throw error about the incorrect case being used.
}
Hope this clarifies my earlier comment.
And yes, I suspect changing the case will cause issues when name based
comparisons are done in code as while tooling will use code like the
above, in application code, names are often not compared in a
case-insensitive manner.
Smile,
Juliette
Hi
Since class names in PHP aren't case-sensitive, there should be no BC
concerns for changing existing classes to fit this new casing (for
Reflection, debug, and documentation purposes). That is, if we wanted to
also update all existing class names in PHP that contain acronyms (e.g.,
DOMDocument -> DomDocument, SimpleXMLElement -> SimpleXmlElement, etc.).
Userland string comparisons against the classname would break. In the
simplest case the following:
if (get_class($someObject) === 'DOMDocument') {
// do something
}
It most certainly isn't great code, but I don't find it completely
unreasonable. Especially if the code dates back from before ::class
was added.
Best regards
Tim Düsterhus