sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Initial version of namespace docs (Stanislav)

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@246256 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Etienne Kneuss 2007-11-15 18:42:22 +00:00
parent dbd16c35ed
commit ed7cb9044a
1 changed files with 437 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

437
language/namespaces.xml Normal file
View file

@ -0,0 +1,437 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision: 1.1 $ -->
<chapter xml:id="language.namespaces" xmlns="http://docbook.org/ns/docbook"
version="1.1">
<title>Namespaces</title>
<sect1 xml:id="language.namespaces.rationale">
<title>Namespaces overview</title>
<simpara>
Namespaces in PHP are designed to solve scoping problem in large PHP
libraries. In PHP, all class definitions are global. Thus, when a library
author creates various utility or public API classes for the library, he must
be aware of the possibility that other libraries with similar functionality
would exist and thus choose unique names so that these libraries could be
used together. Usually it is solved by prefixing the class names with an
unique string - e.g., database classes would have prefix
<classname>My_Library_DB</classname>, etc. As the library grows, prefixes add up,
leading to the very long names.
</simpara>
<simpara>
The namespaces allow the developer to manage naming scopes without using the
long names each time the class is referred to, and solve the problem of
shared globals space without making code unreadable.
</simpara>
<simpara>
Namespaces are available in PHP as of PHP 5.3.0. This section is experimental
and subject to changes.
</simpara>
</sect1>
<sect1 xml:id="language.namespaces.definition">
<title>Namespace definition</title>
<para>
The namespace is declared using <literal>namespace</literal>
keyword, which should be at the very beginning of the file. Example:
<example>
<title>Defining namespace</title>
<programlisting role="php">
<![CDATA[
<?php
namespace MyProject::DB;
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
?>
]]>
</programlisting>
</example>
Same namespace name can be used in multiple files.
</para>
<para>
Namespace can contain class, constant and function definitions, but no free code.
</para>
<para>
Namespace definition does the following:
<itemizedlist>
<listitem>
<simpara>
Inside namespace, all class, function and constant names in definitions are
automatically prefixed with namespace name. The class name is always the
full name, i.e. in the example above the class is called
<classname>MyProject::DB::Connection</classname>.
</simpara>
</listitem>
<listitem>
<simpara>
Constant definitions create constant which is composed of namespace name and constant name.
Like class constants, namespace constant can only contains static values.
</simpara>
</listitem>
<listitem>
<para>
Unqualified class name (i.e., name not containing <literal>::</literal>)
is resolved at runtime following this procedure:
<orderedlist>
<listitem>
<simpara>
Class is looked up inside the current namespace (i.e. prefixing the
name with the current namespace name) without attempting to
<link linkend="language.oop5.autoload">autoload</link>.
</simpara>
</listitem>
<listitem>
<simpara>
Class is looked up inside the global namespace without attempting to
autoload.
</simpara>
</listitem>
<listitem>
<simpara>
Autoloading for name in current namespace is attempted.
</simpara>
</listitem>
<listitem>
<simpara>If previous failed, lookup fails.</simpara>
</listitem>
</orderedlist>
</para>
</listitem>
<listitem>
<para>
Unqualified function name (i.e., name not containing
<literal>::</literal>) is looked up at runtime first in the current namespace
and then in the global space.
</para>
</listitem>
<listitem>
<para>
Unqualified constant names are looked up first at current namespace and then
among globally defined constants.
</para>
</listitem>
</itemizedlist>
See also the full <link linkend="language.namespaces.rules">name resolution rules</link>.
</para>
</sect1>
<sect1 xml:id="language.namespaces.using">
<title>Using namespaces</title>
<para>
Every class and function in a namespace can be referred to by the full name -
e.g. <classname>MyProject::DB::Connection</classname> or
<classname>MyProject::DB::connect</classname> - at any time.
<example>
<title>Using namespaced name</title>
<programlisting role="php">
<![CDATA[
<?php
require 'MyProject/Db/Connection.php';
$x = new MyProject::DB::Connection;
MyProject::DB::connect();
?>
]]>
</programlisting>
</example>
</para>
<para>
Namespaces can be imported into current context (global or namespace) using
the <literal>use</literal> operator. The syntax for the operator is:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
/* ... */
use Some::Name as Othername;
// The simplified form of use:
use Foo::Bar;
// which is the same as :
use Foo::Bar as Bar;
?>
]]>
</programlisting>
</informalexample>
The imported name works as follows: every time that the compiler encounters
the local name <literal>Othername</literal> (as stand-alone name or as
prefix to the longer name separated by <literal>::</literal>) the imported
name <literal>Some::Name</literal> is substituted instead.
</para>
<para>
<literal>use</literal> can be used only in global scope, not inside
function or class. Imported names have effect from the point of import to
the end of the current file. It is recommended to put imports at the
beginning of the file to avoid confusion.
</para>
<para>
<example>
<title>Importing and accessing namespace</title>
<programlisting role="php">
<![CDATA[
<?php
require 'MyProject/Db/Connection.php';
use MyProject::DB;
use MyProject::DB::Connection as DbConnection;
$x = new MyProject::DB::Connection();
$y = new DB::connection();
$z = new DbConnection();
DB::connect();
?>
]]>
</programlisting>
</example>
</para>
<para>
<note>
<simpara>
The import operation is compile-time only, all local names are converted to
their full equivalents by the compiler. Note that it won't translate names
in strings, so callbacks can't rely on import rules.
</simpara>
</note>
</para>
</sect1>
<sect1 xml:id="language.namespaces.global">
<title>Global space</title>
<para>
Without any namespace definition, all class and function definitions are
placed into the global space - as it was in PHP before namespaces were
supported. Prefixing a name with <literal>::</literal> will specify that
the name is required from the global space even in the context of the
namespace.
<example>
<title>Using global space specification</title>
<programlisting role="php">
<![CDATA[
<?php
namespace A::B::C;
/* This function is A::B::C::fopen */
function fopen() {
/* ... */
$f = ::fopen(...); // call global fopen
return $f;
}
?>
]]>
</programlisting>
</example>
</para>
</sect1>
<sect1 xml:id="language.namespaces.constant">
<title>__NAMESPACE__</title>
<para>
The compile-time constant <constant>__NAMESPACE__</constant> is defined to
the name of the current namespace. Outside namespace this constant has the
value of empty string. This constant is useful when one needs to compose
full name for local namespaced names.
<example>
<title>Using __NAMESPACE__</title>
<programlisting role="php">
<![CDATA[
<?php
namespace A::B::C;
function foo() {
// do stuff
}
set_error_handler(__NAMESPACE__ . "::foo");
?>
]]>
</programlisting>
</example>
</para>
</sect1>
<sect1 xml:id="language.namespaces.rules">
<title>Name resolution rules</title>
<para>
Names are resolved following these resolution rules:
<orderedlist>
<listitem>
<simpara>
All qualified names are translated during compilation according to current
import rules. In example, if the namespace A::B::C is imported, a call to
<code>C::D::e()</code> is translated to <code>A::B::C::D::e()</code>.
</simpara>
</listitem>
<listitem>
<simpara>
Unqualified class names are translated during compilation according to current
import rules (full name substituted for short imported name). In example, if
the namespace <literal>A::B::C</literal> is imported, <code>new C()</code> is
translated to <code>new A::B::C()</code>.
</simpara>
</listitem>
<listitem>
<simpara>
Inside namespace, calls to unqualified functions that are defined in the
current namespace (and are known at the time the call is parsed) are
interpreted as calls to these namespace functions, at compile time.
</simpara>
</listitem>
<listitem>
<simpara>
Inside namespace (say A::B), calls to unqualified functions that are not
defined in current namespace are resolved at run-time. Here is how a
call to function <literal>foo()</literal> is resolved:
</simpara>
<orderedlist>
<listitem>
<simpara>
It looks for a function from the current namespace :
<literal>A::B::foo()</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
It tries to find and call the <emphasis>internal</emphasis> function
<literal>foo()</literal>.
</simpara>
</listitem>
</orderedlist>
<simpara>
To call a user defined function in the global namespace,
<literal>::foo()</literal> has to be used.
</simpara>
</listitem>
<listitem>
<simpara>
Inside namespace (say A::B), calls to unqualified class names are
resolved at run-time. Here is how a call to
<code>new C()</code> is resolved:
</simpara>
<orderedlist>
<listitem>
<simpara>
It looks for a class from the current namespace :
<literal>A::B::C()</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
It tries to find and call the <emphasis>internal</emphasis> class
<literal>C()</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
It attemts to autoload <literal>A::B::C()</literal>.
<literal>C()</literal>.
</simpara>
</listitem>
</orderedlist>
<simpara>
To reference a user defined class in the global namespace,
<code>new ::C()</code> has to be used.
</simpara>
</listitem>
<listitem>
<simpara>
Calls to qualified functions are resolved at run-time. Here is how a call
to <literal>A::B::foo()</literal> is resolved:
</simpara>
<orderedlist>
<listitem>
<simpara>
It looks for a function <literal>foo()</literal> in the namespace
<literal>A::B</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
It looks for a class <literal>A::B</literal> and call its static
method <literal>foo()</literal>. It will autoload the class if
necessary.
</simpara>
</listitem>
</orderedlist>
</listitem>
<listitem>
<simpara>
Qualified class names are resolved in compile-time as class from corresponding
namespace. For example, <code>new A::B::C()</code> refers to class
<classname>C</classname> from namespace <literal>>A::B</literal>.
</simpara>
</listitem>
</orderedlist>
</para>
<example>
<title>Name resolutions illustrated</title>
<programlisting role="php">
<![CDATA[
<?php
namespace A;
// function calls
foo(); // first tries to call "foo" defined in namespace "A"
// then calls internal function "foo"
::foo(); // calls function "foo" defined in global scope
// class references
new B(); // first tries to create object of class "B" defined in namespace "A"
// then creates object of internal class "B"
new ::B(); // creates object of class "B" defined in global scope
// static methods/namespace functions from another namespace
B::foo(); // first tries to call function "foo" from namespace "A::B"
// then calls method "foo" of internal class "B"
::B::foo(); // first tries to call function "foo" from namespace "B"
// then calls method "foo" of class "B" from global scope
// static methods/namespace functions of current namespace
A::foo(); // first tries to call function "foo" from namespace "A::A"
// then tries to call method "foo" of class "A" from namespace "A"
// then tries to call function "foo" from namespace "A"
// then calls method "foo" of internal class "A"
::A::foo(); // first tries to call function "foo" from namespace "A"
// then calls method "foo" of class "A" from global scope
?>
]]>
</programlisting>
</example>
</sect1>
</chapter>
<!-- 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:"../../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
-->