php-fig
How should abbreviations and acronyms be written?
We have a recommendation to use StudlyCaps (PascalCase) naming in the PER:
PER
The term "StudlyCaps" in PSR-1 MUST be interpreted as PascalCase where the first letter of each word is capitalized including the very first letter. -- https://www.php-fig.org/per/coding-style/#2-general
Class names
Class names MUST be declared in StudlyCaps -- https://www.php-fig.org/psr/psr-1/#3-namespace-and-class-names
Method names
Method names MUST be declared in camelCase(). -- https://www.php-fig.org/psr/psr-1/#43-methods
But how should we write abbreviations and acronyms?
I suggest following camel case, e.g., loadHttpUrl as recommended in the "Google TypeScript Style Guide".
Google TypeScript Style Guide:
5.1.3 Camel case Treat abbreviations like acronyms in names as whole words, i.e. use loadHttpUrl, not loadHTTPURL, unless required by a platform name (e.g. XMLHttpRequest). -- https://google.github.io/styleguide/tsguide.html#camel-case
At present there is no standard, I believe. I've seen people say Internals has one for PHP, but it's not followed consistently. (I forget off hand which way it goes, honestly.)
Were we to adopt anything, it should follow what Internals does. That means knowing what Internals wants to do. 😄
About a class naming convention.
My preference would be to recommend using underscore to separate all-caps-word-groups (such as: abbreviations, acronyms) .
Readability : using underscore as a separator for all-caps-word-groups used in class names , gives me a quicker distinction of the all-caps-word-groups used when reading the text .
Variety : using underscore as a separator for all-caps-word-groups in class names , allows using combined all-caps-word-groups with other (combined) all-caps-word-groups .
To my knowledge , an underscore in class names in code written for PHP 5.3 and after does not have additional meaning ( while before 5.3 does : https://www.php-fig.org/psr/psr-1/#3-namespace-and-class-names ) .
Examples
Some (hypothetical) class name examples with all-caps-word-groups . Where a all-caps-word-group is one or more all-caps-words .
XML HTTP Request
An XML HTTP Request - extensible markup language - hyper text transfer protocol - request .
With lowercasing it could be made clear :
XmlhttpRequest , XmlHttpRequest .
With underscore as separator it could be made clear :
XMLHTTP_Request , XML_HTTPRequest , XML_HTTP_Request .
With the combination it could be made clear :
XmlHttp_Request , Xml_HttpRequest , Xml_Http_Request .
{SMS ,SM S}API Input
A
SMS API Input - short message service - application programming interface - input , or
SM SAPI Input - short message - server application programming interface - input .
With underscore as abbreviation separator it could be made clear :
SMS_API_Input , SMS_APIInput , SM_SAPI_Input , SM_SAPIInput
(not so with : SMSAPIInput , SMSAPI_Input ) .
With lowercasing it could be made clear :
SmsApiInput , SmSapiInput
( not so with : SmsapiInput ) .
X{, }S{, }L{, }T Processor
A
XSLT Processor - extensible stylesheet language transformations - processor , or
XSL T Processor - extensible stylesheet language - tokenization - processor , or
XS LT Processor - external service - language transformations - processor , or
XS L T Processor - external service - language - t... - processor ,
et cetera.
With underscore as separator it could be made clear :
XSL_T_Processor , XS_LT_Processor or XSLT_Processor .
With lowercasing it could be made clear :
XslTProcessor , XsLtProcessor , XsltProcessor .
Current PHP (inconsistencies)
Regarding the "standard [..] for PHP [..] not followed consistently" these pages https://www.php.net/manual/en/reserved.interfaces.php , https://www.php.net/manual/en/reserved.classes.php , https://www.php.net/manual/en/refs.xml.php show some inconsistent naming of classes.
Some examples of names that stick out : stdClass (first letter in lowercase) , php_user_filter (use of snake_case / lowercase & underscore) , Spl* , Intl* , LibXMLError vs. DOM* , {Simple,}XML* etc. (capitalized vs. non-capitalized)
At present there is no standard, I believe. I've seen people say Internals has one for PHP, but it's not followed consistently. (I forget off hand which way it goes, honestly.)
Were we to adopt anything, it should follow what Internals does. That means knowing what Internals wants to do. 😄
Is it (PER-working group) policy to follow any standard used by PHP Internals ?
We have no official stance, as a WG or as FIG, on following Internals conventions. Though Internals conventions are indeed one factor we should consider among many.
Update: Internals adopted a standard for new classes in 2017, that uses PascalCase except for Acronyms. https://wiki.php.net/rfc/class-naming
So HTTPStatusCode, URL, BTreeMap, etc.
It would be logical to follow suit for user-space.
Combinations of Acronyms/Initialisms, such as HTTPXMLRequest seem to be omitted from that RFC.
Neither is such a thing mentioned in https://github.com/php/php-src/pull/2552#issue-233365020 its file changes.
What that change does mention is the following.
Abbreviations start with a capital letter followed by lowercase letters, whereas acronyms and initialisms are written according to their standard notation. Usage of acronyms and initialisms is not allowed if they are not widely adopted and recognized as such.
Were this to be added to the PER, I would classify such conventions as 'highly recommended', so as SHOULD level requirements. I would not make it MUST level requirements, as there are a lot of edge cases or alignment with other systems (the XMLHttpRequest example for instance).
For FIGs own artifacts, there is also the bylaws to consider: https://www.php-fig.org/bylaws/psr-naming-conventions/ I can imagine that needs an update anyway to refer to the PER instead of PSR-12 and could than also require a more strict naming convention.
