PHP: rfc:class-naming-acronyms

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Casing of acronyms in class and method names ======
  * Version: 1.0
  * Date: 2024-04-05
  * Author: Tim Düsterhus, timwolla@php.net
  * Status: Accepted
  * Implementation: https://github.com/php/php-src/pull/14169, https://github.com/php/policies/pull/7
  * First Published at: http://wiki.php.net/rfc/class-naming-acronyms

===== Introduction =====

The results of the [[class-naming|Class Naming RFC]] decided that class names should be written in PascalCase (“Upper Camel Case”), with the exception of acronyms, which should be included in UPPERCASE. This RFC proposes to revisit the prior decision, instead treating acronyms like regular words, making classnames consistent PascalCase.

==== Reasoning ====

=== It is not consistently applied ===

As an example ext/json has <php>JsonException</php> which should've been <php>JSONException</php> according to the previous RFC’s results. In fact [[json_throw_on_error|JsonException’s RFC]] was created just 3 months (!) after the class naming RFC in September 2017.

Another example is ext/curl which has both <php>CurlHandle</php> and <php>CURLFile</php>. <php>CURLFile</php> predates the RFC, but there's also <php>CURLStringFile</php> which was added in PHP 8.1 and likely followed <php>CURLFile</php>’s naming for consistency, but violating the RFC and being inconsistent with <php>CurlHandle</php>.

ext/random’s <php>Random\Engine\PcgOneseq128XslRr64</php> would've needed to be called <php>Random\Engine\PCGOneseq128XSLRR64</php> according to the class naming RFC.

The [[pdo_driver_specific_subclasses|PDO driver specific sub-classes]] RFC voted (and accepted) for PHP 8.3 and implemented in PHP 8.4 uses Pdo<Driver>, e.g. PdoOdbc instead of PDOODBC.

=== It decreases readability ===

It is well-established in accessibility circles that ALL CAPS text is harder to read than Mixed Case, as mixed case provides greater vertical variation between letters, making it easier to read, especially for people with various reading disorders.

Most accessibility organizations recommend against ALL CAPS.  For example:

  * [[https://w3c.github.io/low-vision-a11y-tf/requirements.html#capitalization|W3C]]
  * [[https://accessibility.huit.harvard.edu/design-readability|Harvard University]]
  * [[https://www.a11yproject.com/posts/how-to-accessible-heading-structure/#all-caps|The A11y Project]]

That issue is amplified if multiple acronyms follow each other. One example is the <php>PCGOneseq128XSLRR64</php> mentioned above: It’s not clear that ''XSL'' (XorShiftLow) and ''RR'' (RandomlyRotate) are two different acronyms.

Likewise <php>PDOODBC</php> is much harder to parse than <php>PdoOdbc</php>.

Another example might be JavaScript’s <php>XMLHttpRequest</php> which incidentally mixes both variants. According to the class naming RFC it would need to be called <php>XMLHTTPRequest</php>, resulting in 8 consecutive uppercase characters.

=== The userland convention is mostly MixedCase ===

Although there is no formal standard in userland for handling initialisms, the most widely used convention is to only capitalize the first letter.  For example:

  * 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.9.x/src/Schema/Visitor and https://github.com/doctrine/dbal/blob/3.9.x/src/Tools/DsnParser.php

Although this RFC has no direct impact on userland code, normalizing conventions between Internals and userland has many benefits.  The PER-CS working group, part of the PHP-FIG, has been asked to adopt a standard for initialisms and would likely follow suit with this RFC if passed.

===== Proposal =====

==== Update to the Policy ====

The class naming policy should be updated to the following, with changes highlighted:

Method names follow the studlyCaps (also referred to as bumpy case or camel caps) naming convention, with care taken to minimize the letter count. The initial letter of the name is lowercase, and each letter that starts a new word is capitalized.

Class names should be descriptive nouns in PascalCase and as short as possible. Each word in the class name should start with a capital letter, without underscore delimiters. The class name should be prefixed with the name of the "parent set" (e.g. the name of the extension) if no namespaces are used.

Abbreviations and acronyms as well as initialisms should be avoided wherever possible, unless they are much more widely used than the long form (e.g. HTTP or URL). <del>Abbreviations start with a capital letter followed by lowercase letters, whereas acronyms and initialisms are written according to their standard notation.</del> **Abbreviations, acronyms, and initialisms should be treated like regular words, thus they should be written with an uppercase first character, followed by lowercase characters.** <del>Usage of acronyms and initialisms is not allowed if they are not widely adopted and recognized as such.</del>

**Diverging from this policy is allowed to keep internal consistency within a single extension, if the name follows an established, language-agnostic standard, or for other reasons, if those reasons are properly justified and voted on as part of the RFC process.**

=== Examples ===

Good method names:

<code>
connect()
getData()
buildSomeWidget()
performHttpRequest()
</code>

Bad method names:

<code>
get_Data()
buildsomewidget()
getI()
performHTTPRequest()
</code>

Good class names:

<code>
Curl
CurlResponse
HttpStatusCode
Url
BtreeMap // B-tree Map
UserId // User Identifier
Char // Character
Intl // Internationalization
Ssl\Certificate
Ssl\Crl // Certificate Revocation List
Ssl\CrlUrl
</code>

Bad class names:

<code>
curl
curl_response
HTTPStatusCode
URL
BTreeMap
UserID // User Identifier
CHAR
INTL
SSL\Certificate
SSL\CRL
SSL\CRLURL
</code>

==== Adjusting class & method names added in PHP 8.4 ====

The [[domdocument_html5_parser|DOM HTML5 parsing and serialization RFC]] introduced new class names and method names that violate the updated naming policy, should this RFC be accepted. As part of this RFC, the following changes will be made:

  * The ''DOM'' namespace will be renamed to ''Dom'', affecting everything contained within it.
  * DOM\DTDNamedNodeMap -> Dom\DtdNamedNodeMap
  * DOM\HTMLCollection -> Dom\HTMLCollection (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)
  * DOM\CDATASection -> Dom\CDATASection (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)
  * DOM\HTMLDocument -> Dom\HTMLDocument (Justification: Consistency with XMLDocument)
  * DOM\XMLDocument -> Dom\XMLDocument (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)
  * DOM\XPath -> Dom\XPath (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the XPath interfaces that use this casing)
  * DOM\Implementation::createHTMLDocument() -> Dom\Implementation::createHtmlDocument()
  * DOM\Node::lookupNamespaceURI() -> Dom\Node::lookupNamespaceURI() (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)
  * DOM\*::*NS() -> Dom\*::*NS() (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] generally specifies the NS suffix in this casing)
  * DOM\DocumentFragment::appendXML() -> Dom\DocumentFragment::appendXml()
  * DOM\Document::createCDATASection() -> Dom\Document::createCDATASection() (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)
  * DOM\Document::relaxNGValidate() -> Dom\Document::relaxNgValidate()
  * DOM\Document::relaxNGValidateSource() -> Dom\Document::relaxNgValidateSource()
  * DOM\HTMLDocument::saveXML() -> Dom\HTMLDocument::saveXml()
  * DOM\HTMLDocument::saveXMLFile() -> Dom\HTMLDocument::saveXmlFile()
  * DOM\HTMLDocument::saveHTML() -> Dom\HTMLDocument::saveHtml()
  * DOM\HTMLDocument::saveHTMLFile() -> Dom\HTMLDocument::saveHtmlFile()
  * DOM\XMLDocument::saveXML() -> Dom\XMLDocument::saveXml()
  * DOM\XMLDocument::saveXMLFile() -> Dom\XMLDocument::saveXmlFile()

For the [[improve_callbacks_dom_and_xsl|Improve callbacks in ext/dom and ext/xsl RFC]] the following changes will be made:

  * \DOMXPath::registerPhpFunctionNS() -> \DOMXPath::registerPhpFunctionNS() (Justification: Consistency with the *NS() methods in ext/dom)
  * \DOM\XPath::registerPhpFunctionNS() -> \Dom\XPath::registerPhpFunctionNS() (Justification: see above)
  * \XSLTProcessor::registerPHPFunctionNS() -> \XSLTProcessor::registerPHPFunctionNS() (Justification: Consistency with \XSLTProcessor::registerPHPFunctions(), which unfortunately is inconsistent with \DOMXPath).

===== Backward Incompatible Changes =====

Existing class and method names in released versions are not affected, thus there are not backwards incompatible changes. This is a policy RFC.

===== Proposed PHP Version(s) =====

Next PHP 8.x (PHP 8.4).

===== RFC Impact =====

==== To SAPIs ====

SAPIs that expose classes should take the RFC results into account.

==== To Existing Extensions ====

Extensions should take the RFC results into account.

==== To Opcache ====

None.

==== New Constants ====

None.

==== php.ini Defaults ====

None.

===== Open Issues =====

None.

===== Unaffected PHP Functionality =====

Everything that is not a class name of an internal class. Everything that is already in PHP.

===== Future Scope =====

None.

===== Proposed Voting Choices =====

<doodle title="Adopt the updated class naming policy and adjust the new names introduced in PHP 8.4?" auth="timwolla" voteType="single" closed="yes" closeon="2024-05-06T14:00:00Z">
   * yes
   * no
</doodle>

===== Patches and Tests =====

None, yet. This RFC will result in changes to:

  * https://github.com/php/php-src/blob/536305436f44e91731bc5c86e06f137e44a01109/CODING_STANDARDS.md#L173-L211
  * https://github.com/php/policies/blob/main/coding-standards-and-naming.rst

===== Implementation =====

  * https://github.com/php/php-src/pull/14169
  * https://github.com/php/policies/pull/7

===== References =====

  * [[class-naming|Class Naming RFC]]
  * Prior mailing list discussion: https://externals.io/message/120959#120959
  * Discussion in PHP-FIG for PER-CS: https://github.com/php-fig/per-coding-style/issues/83

===== Rejected Features =====

n/a
Page Tools
