[doc-en] master: userlandnaming.xml Explain the identifier, symbol; personalization (#4032)

Author: Mikhail Alferov (mmalferov) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-03T12:19:34+02:00 Commit: https://github.com/php/doc-en/commit/077012fff21b527d01ffde600ad3282098aa1c91 Raw diff: https://github.com/php/doc-en/commit/077012fff21b527d01ffde600ad3282098aa1c91.diff userlandnaming.xml Explain the identifier, symbol; personalization (#4032) * userlandnaming.xml Explain the identifier, symbol; personalization I'm sure I've made some mistakes in my wording and I hope I'll be corrected, but I think the reader would like a little more clarity for the terms in this section. * Update appendices/userlandnaming.xml Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> * Update appendices/userlandnaming.xml Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> * Update appendices/userlandnaming.xml Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> * Userland Naming Guide: keep the terminology accurate An identifier is a lexical token, not a part of one, and the manual uses "symbol" for variable names, so the added gloss said something the rest of the manual contradicts. A namespace has no symbol table either: the symbol table holds variables, one per scope, while functions and classes live in their own tables. The opening paragraph is back to the wording that was correct, and the link to the refcounting page goes with it. Three long-standing mistakes go too. Class names use PascalCase and method names camelCase, which is what the coding standards say. The magic method example was __autoload, removed in PHP 8.0. And the extension prefix examples were mysql_query, whose extension went away in PHP 7, and curl_close, deprecated in 8.5. The rest is what the pull request was for: traits and enumerations do go into the global namespace and were missing, the second person is gone from the whole file rather than one sentence of it, and the paragraphs touched here become simparas. --------- Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> Changed paths: M appendices/userlandnaming.xml Diff: diff --git a/appendices/userlandnaming.xml b/appendices/userlandnaming.xml index 95fe76f8e3b8..649c5dfa2117 100644 --- a/appendices/userlandnaming.xml +++ b/appendices/userlandnaming.xml @@ -2,13 +2,12 @@ <!-- $Revision$ --> <appendix xml:id="userlandnaming" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Userland Naming Guide</title> - <para> - The following is a guide for how to best choose names for identifiers - in userland PHP code. When choosing names for any code that creates symbols - in the global namespace, it is important to take into account the following - guidelines to prevent future versions of PHP from clashing with your - symbols. - </para> + <simpara> + The following is a guide for how to best choose names for identifiers in + userland PHP code. When choosing names for any code that creates symbols in + the global namespace, it is important to take into account the following + guidelines to prevent future versions of PHP from clashing with user symbols. + </simpara> <section xml:id="userlandnaming.globalnamespace"> <title>Global Namespace</title> @@ -17,24 +16,26 @@ </para> <itemizedlist> - <listitem><para>functions</para></listitem> - <listitem><para>classes</para></listitem> - <listitem><para>interfaces</para></listitem> - <listitem><para>constants (not class constants)</para></listitem> + <listitem><simpara>functions</simpara></listitem> + <listitem><simpara>classes</simpara></listitem> + <listitem><simpara>interfaces</simpara></listitem> + <listitem><simpara>traits</simpara></listitem> + <listitem><simpara>enumerations</simpara></listitem> + <listitem><simpara>constants (not class constants)</simpara></listitem> <listitem> - <para>variables defined outside of functions/methods</para> + <simpara>variables defined outside of functions and methods</simpara> </listitem> </itemizedlist> </section> <section xml:id="userlandnaming.rules"> <title>Rules</title> - <para> + <simpara> The following list gives an overview of which rights the PHP project reserves for itself, when choosing names for new internal identifiers. The definitive guide is the official - <link xlink:href="&url.userlandnaming.cs;">CODING STANDARDS</link>: - </para> + <link xlink:href="&url.userlandnaming.cs;">PHP coding standards</link>: + </simpara> <itemizedlist> <listitem> @@ -44,22 +45,22 @@ </para> </listitem> <listitem> - <para> - Function names use underscores between words, while class names use - both the <literal>camelCase</literal> and <literal>PascalCase</literal> - rules. - </para> + <simpara> + Function names use underscores between words, class names use + <literal>PascalCase</literal>, and method names use + <literal>camelCase</literal>. + </simpara> </listitem> <listitem> - <para> + <simpara> PHP will prefix any global symbols of an extension with the name of - the extension. (In the past, there have been numerous - exceptions to this rule.) Examples: - </para> + the extension. (In the past, there have been numerous exceptions to + this rule, so some existing names are not prefixed.) Examples: + </simpara> <itemizedlist> - <listitem><para><function>curl_close</function></para></listitem> - <listitem><para><function>mysql_query</function></para></listitem> + <listitem><simpara><function>curl_exec</function></simpara></listitem> + <listitem><simpara><function>mysqli_query</function></simpara></listitem> <listitem><para>PREG_SPLIT_DELIM_CAPTURE</para></listitem> <listitem><para>new DOMDocument()</para></listitem> <listitem> @@ -82,15 +83,19 @@ </itemizedlist> </listitem> <listitem> - <para> + <simpara> PHP reserves all symbols starting with <literal>__</literal> - as magical. It is recommended that you do not create symbols starting - with <literal>__</literal> in PHP unless - you want to use documented magical functionality. Examples: - </para> + as magical. It is recommended not to create symbols starting with + <literal>__</literal> in PHP, unless the intent is to use documented + magical functionality. Examples: + </simpara> <itemizedlist> - <listitem><para><link linkend="object.get">__get()</link></para></listitem> - <listitem><para><function>__autoload</function></para></listitem> + <listitem> + <simpara><link linkend="object.get">__get()</link></simpara> + </listitem> + <listitem> + <simpara><link linkend="object.construct">__construct()</link></simpara> + </listitem> </itemizedlist> </listitem> </itemizedlist> @@ -98,12 +103,12 @@ <section xml:id="userlandnaming.tips"> <title>Tips</title> - <para> - In order to write future-proof code, it is recommended that you don't - place many variables, functions or classes in the global namespace. This will - prevent naming conflicts with 3rd party code as well as possible + <simpara> + In order to write future-proof code, it is recommended not to place many + variables, functions or classes in the global namespace. This will + prevent naming conflicts with third-party code as well as possible future additions to the language. - </para> + </simpara> <para> One common way to prevent naming conflicts of functions and classes is to add them to their own dedicated @@ -116,24 +121,27 @@ namespace MyProject; -function my_function() { +function my_function() +{ return true; } \MyProject\my_function(); + +?> ]]> </programlisting> </informalexample> - <para> - This still needs you to keep track of already used namespaces, but once you - have decided on a namespace you will be using you can add all functions and - classes to it without having to think about conflicts again. - </para> - <para> + <simpara> + Keeping track of the namespaces already in use is still necessary, but once + a namespace has been chosen, all functions and classes can be added to it + without having to think about conflicts again. + </simpara> + <simpara> It is considered best practice to limit the number of variables added to - the global scope in order to prevent naming conflicts with 3rd party + the global scope in order to prevent naming conflicts with third-party code. - </para> + </simpara> <note> <title>Variable scoping</title> <para>