Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:120959
Message-ID: <01e3ff17-5088-0431-6014-82ef4e4789b2@bastelstu.be>
Date: Wed, 30 Aug 2023 13:43:59 +0200
MIME-Version: 1.0
Content-Language: en-US
To: PHP internals <internals@lists.php.net>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Subject: Casing of acronyms in class and method names
From: tim@bastelstu.be (=?UTF-8?Q?Tim_D=c3=bcsterhus?=)

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