php-doc-en/appendices/userlandnaming.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $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>

 <section xml:id="userlandnaming.globalnamespace">
  <title>Global Namespace</title>
  <para>
   Here is an overview of code constructs that go into the global namespace:
  </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>
    <para>variables defined outside of functions/methods</para>
   </listitem>
  </itemizedlist>
 </section>

 <section xml:id="userlandnaming.rules">
  <title>Rules</title>
  <para>
   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>

  <itemizedlist>
   <listitem>
    <para>
     PHP owns the top-level namespace but tries to find decent descriptive
     names and avoid any obvious clashes.
    </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>
   </listitem>
   <listitem>
    <para>
     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>

    <itemizedlist>
     <listitem><para><function>curl_close</function></para></listitem>
     <listitem><para><function>mysql_query</function></para></listitem>
     <listitem><para>PREG_SPLIT_DELIM_CAPTURE</para></listitem>
     <listitem><para>new DOMDocument()</para></listitem>
     <listitem>
      <para>
       <function>strpos</function> (example of a past mistake)
      </para>
     </listitem>
     <listitem><para>new SplFileObject()</para></listitem>
    </itemizedlist>
   </listitem>
   <listitem>
    <para>
     Iterators and Exceptions are however simply postfixed with
     "<literal>Iterator</literal>" and "<literal>Exception</literal>."
     Examples:
    </para>
    <itemizedlist>
     <listitem><para><classname>ArrayIterator</classname></para></listitem>
     <listitem><para><classname>LogicException</classname></para></listitem>
    </itemizedlist>
   </listitem>
   <listitem>
    <para>
     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>
    <itemizedlist>
     <listitem><para><link linkend="object.get">__get()</link></para></listitem>
     <listitem><para><function>__autoload</function></para></listitem>
    </itemizedlist>
   </listitem>
  </itemizedlist>
 </section>

 <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
   future additions to the language.
  </para>
  <para>
   One common way to prevent naming conflicts of functions and classes is to
   add them to their own dedicated
   <link linkend="language.namespaces">namespace</link>.
  </para>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php

namespace MyProject;

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>
   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
   code.
  </para>
  <note>
   <title>Variable scoping</title>
   <para>
    Because of PHP's <link linkend="language.variables.scope">scoping rules</link>
    variables defined inside functions and methods are not in the global scope
    and as such cannot conflict with other variables defined in the global scope.
   </para>
  </note>
 </section>

</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->