# Casing of acronyms in class and method names

- Thread: https://externals.io/message/120959
- Original archive: https://news-web.php.net/php.internals/120959
- Started by tim@bastelstu.be on 2023-08-30T11:43:59+00:00
- Messages: 8
- RFC: Casing of acronyms in class and method names (Accepted) — https://externals.io/rfc/class-naming-acronyms.md
- RFC: Class Naming (Accepted) — https://externals.io/rfc/class-naming.md
- RFC: DOM HTML5 parsing and serialization (Implemented (PHP 8.4)) — https://externals.io/rfc/domdocument_html5_parser.md
- RFC: PDO driver specific sub-classes (Implemented (PHP 8.4)) — https://externals.io/rfc/pdo_driver_specific_subclasses.md
- RFC: JSON_THROW_ON_ERROR (Implemented (PHP 7.3)) — https://externals.io/rfc/json_throw_on_error.md
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #120959 — tim@bastelstu.be — 2023-08-30T11:43:59+00:00

URL: https://externals.io/message/120959#120959

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.

--------------------

1. 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

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.

3. 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

---

## #120960 — Lynn — 2023-08-30T11:58:18+00:00

URL: https://externals.io/message/120959#120960 · In reply to: #120959

> 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.

---

## #120967 — Niels Dossche — 2023-08-31T18:34:20+00:00

URL: https://externals.io/message/120959#120967 · In reply to: #120959

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.
> 
> --------------------
> 
> 1. 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.

> 
> 2. It decreases readability.
> 
> [...]

Agreed.

> 
> 3. 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

---

## #121034 — Ben Ramsey — 2023-09-10T23:57:30+00:00

URL: https://externals.io/message/120959#121034 · In reply to: #120967

> Hi Tim
> 
> 
> > […]
> 
> 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

---

## #121035 — Juliette Reinders Folmer — 2023-09-11T01:59:28+00:00

URL: https://externals.io/message/120959#121035 · In reply to: #120967

> 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

---

## #121052 — Ben Ramsey — 2023-09-13T15:48:16+00:00

URL: https://externals.io/message/120959#121052 · In reply to: #121035

> 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

---

## #121057 — tim@bastelstu.be — 2023-09-13T19:44:33+00:00

URL: https://externals.io/message/120959#121057 · In reply to: #120967

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

---

## #121058 — Juliette Reinders Folmer — 2023-09-13T20:12:27+00:00

URL: https://externals.io/message/120959#121058 · In reply to: #121035

> 
> > […]
>
>
> 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