2006-07-27 20:59:29 +00:00
|
|
|
<?xml version="1.0" encoding="utf-8"?>
|
2009-07-11 05:16:31 +00:00
|
|
|
<!-- $Revision$ -->
|
2007-06-20 22:25:43 +00:00
|
|
|
<appendix xml:id="userlandnaming" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
2006-07-27 20:59:29 +00:00
|
|
|
<title>Userland Naming Guide</title>
|
|
|
|
<para>
|
|
|
|
The following is a guide for how to best choose names for identifiers
|
2006-08-12 20:14:32 +00:00
|
|
|
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.
|
2006-07-27 20:59:29 +00:00
|
|
|
</para>
|
|
|
|
|
2007-06-20 22:25:43 +00:00
|
|
|
<section xml:id="userlandnaming.globalnamespace">
|
2006-07-27 20:59:29 +00:00
|
|
|
<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>
|
|
|
|
|
2007-06-20 22:25:43 +00:00
|
|
|
<section xml:id="userlandnaming.rules">
|
2006-07-27 20:59:29 +00:00
|
|
|
<title>Rules</title>
|
|
|
|
<para>
|
2006-08-12 20:14:32 +00:00
|
|
|
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
|
2007-06-20 22:25:43 +00:00
|
|
|
<link xlink:href="&url.userlandnaming.cs;">CODING STANDARDS</link>:
|
2006-07-27 20:59:29 +00:00
|
|
|
</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>
|
2010-10-25 19:38:17 +00:00
|
|
|
Function names use underscores between words, while class names use
|
|
|
|
both the <literal>camelCase</literal> and <literal>PascalCase</literal>
|
|
|
|
rules.
|
2006-07-27 20:59:29 +00:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
PHP will prefix any global symbols of an extension with the name of
|
2006-08-12 20:14:32 +00:00
|
|
|
the extension. (In the past, there have been numerous
|
|
|
|
exceptions to this rule.) Examples:
|
2006-07-27 20:59:29 +00:00
|
|
|
</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>
|
2006-08-12 20:14:32 +00:00
|
|
|
Iterators and Exceptions are however simply postfixed with
|
|
|
|
"<literal>Iterator</literal>" and "<literal>Exception</literal>."
|
|
|
|
Examples:
|
2006-07-27 20:59:29 +00:00
|
|
|
</para>
|
|
|
|
<itemizedlist>
|
2008-08-23 15:55:58 +00:00
|
|
|
<listitem><para><classname>ArrayIterator</classname></para></listitem>
|
2008-09-11 12:09:37 +00:00
|
|
|
<listitem><para><classname>LogicException</classname></para></listitem>
|
2006-07-27 20:59:29 +00:00
|
|
|
</itemizedlist>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2006-08-12 20:14:32 +00:00
|
|
|
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:
|
2006-07-27 20:59:29 +00:00
|
|
|
</para>
|
|
|
|
<itemizedlist>
|
2012-01-12 14:14:28 +00:00
|
|
|
<listitem><para><link linkend="object.get">__get()</link></para></listitem>
|
2006-07-27 20:59:29 +00:00
|
|
|
<listitem><para><function>__autoload</function></para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</section>
|
|
|
|
|
2007-06-20 22:25:43 +00:00
|
|
|
<section xml:id="userlandnaming.tips">
|
2006-07-27 20:59:29 +00:00
|
|
|
<title>Tips</title>
|
|
|
|
<para>
|
2016-07-15 18:24:17 +00:00
|
|
|
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.
|
2006-07-27 20:59:29 +00:00
|
|
|
</para>
|
2016-07-15 18:24:17 +00:00
|
|
|
<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
|
2006-07-27 20:59:29 +00:00
|
|
|
|
2016-07-15 18:24:17 +00:00
|
|
|
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>
|
2016-10-28 15:32:08 +00:00
|
|
|
variables defined inside functions and methods are not in the global scope
|
2016-07-15 18:24:17 +00:00
|
|
|
and as such cannot conflict with other variables defined in the global scope.
|
|
|
|
</para>
|
|
|
|
</note>
|
2006-07-27 20:59:29 +00:00
|
|
|
</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
|
2009-09-25 07:04:39 +00:00
|
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
2006-07-27 20:59:29 +00:00
|
|
|
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
|
|
|
|
-->
|