language/namespaces.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 874f7c1266d4e4f2e1e6c79b5fb48b590caa1197 Maintainer: Altair Status: ready -->
<!-- CREDITS: mowangjuanzi, Luffy -->
<chapter xml:id="language.namespaces" xmlns="http://docbook.org/ns/docbook"
 version="1.1">
 <title>命名空间概述</title>
 <titleabbrev>概述</titleabbrev>

 <sect1 xml:id="language.namespaces.rationale">
  <title>命名空间概述</title>
  <?phpdoc print-version-for="namespaces"?>
  <simpara>
   什么是命名空间？从广义上来说，命名空间是一种封装事物的方法。在很多地方都可以见到这种抽象概念。例如，在操作系统中目录用来将相关文件分组，对于目录中的文件来说，它就扮演了命名空间的角色。具体举个例子，文件
   <literal>foo.txt</literal> 可以同时在目录 <literal>/home/greg</literal> 和
   <literal>/home/other</literal> 中存在，但在同一个目录中不能存在两个
   <literal>foo.txt</literal> 文件。另外，在目录 <literal>/home/greg</literal> 外访问
   <literal>foo.txt</literal> 文件时，我们必须将目录名以及目录分隔符放在文件名之前得到
   <literal>/home/greg/foo.txt</literal>。这个原理应用到程序设计领域就是命名空间的概念。
  </simpara>
  <simpara>
   在 PHP 中，命名空间用来解决在编写类库或应用程序时创建可重用的代码如类或函数时碰到的两类问题：
  </simpara>
  <para>
   <orderedlist>
    <listitem>
     <simpara>
      用户编写的代码与PHP内部的类/函数/常量或第三方类/函数/常量之间的名字冲突。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      为很长的标识符名称(通常是为了缓解第一类问题而定义的)创建一个别名（或简短）的名称，提高源代码的可读性。
     </simpara>
    </listitem>
   </orderedlist>
  </para>
  <simpara>
   PHP 命名空间提供了一种将相关的类、函数和常量组合到一起的途径。下面是一个说明 PHP
   命名空间语法的示例：
  </simpara>
  <example>
   <title>命名空间语法示例</title>
   <programlisting role="php">
   <![CDATA[
<?php
namespace my\name; // 参考 "定义命名空间" 小节

class MyClass {}
function myfunction() {}
const MYCONST = 1;

$a = new MyClass;
$c = new \my\name\MyClass; // 参考 "全局空间" 小节

$a = strlen('hi'); // 参考 "使用命名空间：后备全局函数/常量" 小节

$d = namespace\MYCONST; // 参考 "namespace操作符和__NAMESPACE__常量” 小节

$d = __NAMESPACE__ . '\MYCONST';
echo constant($d); // 参考 "命名空间和动态语言特征" 小节
?>
    ]]>
   </programlisting>
  </example>
  <note>
   <simpara>
    命名空间名称大小写不敏感。
   </simpara>
  </note>
  <note>
   <para>
    名为 <literal>PHP</literal> 的命名空间，以及以这些名字开头的命名空间
    （例如 <literal>PHP\Classes</literal>）被保留用作语言内核使用，
    而不应该在用户空间的代码中使用。
   </para>
  </note>
 </sect1>

 <sect1 xml:id="language.namespaces.definition">
  <title>定义命名空间</title>
  <titleabbrev>命名空间</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   虽然任意合法的 PHP 代码都可以包含在命名空间中，但只有以下类型的代码受命名空间的影响，它们是：类（包括抽象类和 trait）、接口、函数和常量。
  </para>
  <para>
   命名空间通过关键字 <literal>namespace</literal>
   来声明。如果一个文件中包含命名空间，它必须在其它所有代码之前声明命名空间，除了一个以外：<xref linkend="control-structures.declare" />关键字。
   <example>
    <title>声明单个命名空间</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace MyProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }

?>
]]>
    </programlisting>
   </example>
   <note>
    <simpara>
     完全限定名称（就是以反斜杠开头的名称）不能用于命名空间的声明。
     因为该结构会解析成相对命名空间表达式。
    </simpara>
   </note>
   在声明命名空间之前唯一合法的代码是用于定义源文件编码方式的 <literal>declare</literal>
   语句。另外，所有非 PHP
   代码包括空白符都不能出现在命名空间的声明之前：
   <example>
    <title>声明单个命名空间</title>
    <programlisting role="php">
     <![CDATA[
<html>
<?php
namespace MyProject; // 致命错误 -　命名空间必须是程序脚本的第一条语句
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   另外，与 PHP 其它的语言特征不同，同一个命名空间可以定义在多个文件中，即允许将同一个命名空间的内容分割存放在不同的文件中。
  </para>
 </sect1>
 <sect1 xml:id="language.namespaces.nested">
  <title>定义子命名空间</title>
  <titleabbrev>子命名空间</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   与目录和文件的关系很象，PHP
   命名空间也允许指定层次化的命名空间的名称。因此，命名空间的名字可以使用分层次的方式定义：
   <example>
    <title>声明分层次的单个命名空间</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace MyProject\Sub\Level;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }

?>
]]>
    </programlisting>
   </example>
   上面的例子创建了常量 <literal>MyProject\Sub\Level\CONNECT_OK</literal>，类
   <literal>MyProject\Sub\Level\Connection</literal> 和函数
   <literal>MyProject\Sub\Level\connect</literal>。
  </para>
 </sect1>
 <sect1 xml:id="language.namespaces.definitionmultiple">
  <title>在同一个文件中定义多个命名空间</title>
  <titleabbrev>在一个文件中定义多个命名空间</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   也可以在同一个文件中定义多个命名空间。在同一个文件中定义多个命名空间有两种语法形式。
  </para>
  <para>
   <example>
    <title>定义多个命名空间，简单组合语法</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace MyProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }

namespace AnotherProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
  不建议使用这种语法在单个文件中定义多个命名空间。建议使用下面的大括号形式的语法。
  </para>
  <para>
   <example>
    <title>定义多个命名空间，大括号语法</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace AnotherProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   在实际的编程实践中，非常不提倡在同一个文件中定义多个命名空间。这种方式的主要用于将多个 PHP
   脚本合并在同一个文件中。
  </para>
  <para>
   将全局的非命名空间中的代码与命名空间中的代码组合在一起，只能使用大括号形式的语法。全局代码必须用一个不带名称的 namespace
   语句加上大括号括起来，例如：
   <example>
    <title>定义多个命名空间和不包含在命名空间中的代码</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace { // 全局代码
session_start();
$a = MyProject\connect();
echo MyProject\Connection::start();
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   除了开始的 declare 语句外，命名空间的括号外不得有任何 PHP 代码。
   <example>
    <title>定义多个命名空间和不包含在命名空间中的代码</title>
    <programlisting role="php">
     <![CDATA[
<?php
declare(encoding='UTF-8');
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace { // 全局代码
session_start();
$a = MyProject\connect();
echo MyProject\Connection::start();
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </sect1>
 <sect1 xml:id="language.namespaces.basics">
  <title>使用命名空间：基础</title>
  <titleabbrev>基础</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   在讨论如何使用命名空间之前，必须了解 PHP
   是如何知道要使用哪一个命名空间中的元素的。可以将 PHP 
   命名空间与文件系统作一个简单的类比。在文件系统中访问一个文件有三种方式：
   <orderedlist>
    <listitem>
     <simpara>
     相对文件名形式如 <literal>foo.txt</literal>。它会被解析为
     <literal>currentdirectory/foo.txt</literal>，其中 <literal>currentdirectory</literal>
     表示当前目录。因此如果当前目录是
     <literal>/home/foo</literal>，则该文件名被解析为 <literal>/home/foo/foo.txt</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      相对路径名形式如 <literal>subdirectory/foo.txt</literal>。它会被解析为
      <literal>currentdirectory/subdirectory/foo.txt</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     绝对路径名形式如 <literal>/main/foo.txt</literal>。它会被解析为 <literal>/main/foo.txt</literal>。
     </simpara>
    </listitem>
   </orderedlist>
   PHP 命名空间中的元素使用同样的原理。例如，类名可以通过三种方式引用：
   <orderedlist>
    <listitem>
     <simpara>
     非限定名称，或不包含前缀的类名称，例如
     <literal>$a=new foo();</literal> 或
     <literal>foo::staticmethod();</literal>。如果当前命名空间是
     <literal>currentnamespace</literal>，foo 将被解析为
     <literal>currentnamespace\foo</literal>。如果使用 foo
     的代码是全局的，不包含在任何命名空间中的代码，则 foo
     会被解析为 <literal>foo</literal>。
     </simpara>
     <simpara>
     警告：如果命名空间中的函数或常量未定义，则该非限定的函数名称或常量名称会被解析为全局函数名称或常量名称。详情参见
     <link linkend="language.namespaces.fallback">使用命名空间：后备全局函数名称/常量名称</link>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     限定名称,或包含前缀的名称，例如
     <literal>$a = new subnamespace\foo();</literal> 或
     <literal>subnamespace\foo::staticmethod();</literal>。如果当前的命名空间是
     <literal>currentnamespace</literal>，则 foo 会被解析为
     <literal>currentnamespace\subnamespace\foo</literal>。如果使用
     foo 的代码是全局的，不包含在任何命名空间中的代码，foo
     会被解析为 <literal>subnamespace\foo</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     完全限定名称，或包含了全局前缀操作符的名称，例如，
     <literal>$a = new \currentnamespace\foo();</literal> 或
     <literal>\currentnamespace\foo::staticmethod();</literal>。在这种情况下，foo
     总是被解析为代码中的文字名(literal name)<literal>currentnamespace\foo</literal>。
     </simpara>
    </listitem>
   </orderedlist>
  </para>
  <para>
   下面是一个使用这三种方式的实例：
   <informalexample>
    <simpara>file1.php</simpara>
    <programlisting role="php">
     <![CDATA[
<?php
namespace Foo\Bar\subnamespace;

const FOO = 1;
function foo() {}
class foo
{
    static function staticmethod() {}
}
?>
     ]]>
    </programlisting>
    <simpara>file2.php</simpara>
    <programlisting role="php">
     <![CDATA[
<?php
namespace Foo\Bar;
include 'file1.php';

const FOO = 2;
function foo() {}
class foo
{
    static function staticmethod() {}
}

/* 非限定名称 */
foo(); // 解析为函数 Foo\Bar\foo 
foo::staticmethod(); // 解析为类 Foo\Bar\foo 的静态方法 staticmethod
echo FOO; // 解析为常量 Foo\Bar\FOO

/* 限定名称 */
subnamespace\foo(); // 解析为函数 Foo\Bar\subnamespace\foo
subnamespace\foo::staticmethod(); // 解析为类 Foo\Bar\subnamespace\foo,
                                  // 以及类的方法 staticmethod
echo subnamespace\FOO; // 解析为常量 Foo\Bar\subnamespace\FOO

/* 完全限定名称 */
\Foo\Bar\foo(); // 解析为函数 Foo\Bar\foo
\Foo\Bar\foo::staticmethod(); // 解析为类 Foo\Bar\foo, 以及类的方法 staticmethod
echo \Foo\Bar\FOO; // 解析为常量 Foo\Bar\FOO
?>
     ]]>
    </programlisting>
   </informalexample>
  </para>
  <para>
   注意访问任意全局类、函数或常量，都可以使用完全限定名称，例如
   <function>\strlen</function> 或 <classname>\Exception</classname> 或
   \<constant>INI_ALL</constant>。

   <example>
    <title>在命名空间内部访问全局类、函数和常量</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace Foo;

function strlen() {}
const INI_ALL = 3;
class Exception {}

$a = \strlen('hi'); // 调用全局函数strlen
$b = \INI_ALL; // 访问全局常量 INI_ALL
$c = new \Exception('error'); // 实例化全局类 Exception
?>
     ]]>
    </programlisting>
   </example>
  </para>
 </sect1>
 <sect1 xml:id="language.namespaces.dynamic">
  <title>命名空间和动态语言特征</title>
  <titleabbrev>命名空间和动态语言特征</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   PHP 命名空间的实现受到其语言自身的动态特征的影响。因此，如果要将下面的代码转换到命名空间中：
   <example>
    <title>动态访问元素</title>
    <simpara>example1.php:</simpara>
    <programlisting role="php">
     <![CDATA[
<?php
class classname
{
    function __construct()
    {
        echo __METHOD__,"\n";
    }
}
function funcname()
{
    echo __FUNCTION__,"\n";
}
const constname = "global";

$a = 'classname';
$obj = new $a; // 输出 classname::__construct
$b = 'funcname';
$b(); // 输出 funcname
echo constant('constname'), "\n"; // 输出 global
?>
    ]]>
    </programlisting>
   </example>
   必须使用完全限定名称（包括命名空间前缀的类名称）。注意因为在动态的类名称、函数名称或常量名称中，限定名称和完全限定名称没有区别，因此其前导的反斜杠是不必要的。
   <example>
    <title>动态访问命名空间的元素</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace namespacename;
class classname
{
    function __construct()
    {
        echo __METHOD__,"\n";
    }
}
function funcname()
{
    echo __FUNCTION__,"\n";
}
const constname = "namespaced";

/* 注意，如果使用双引号，要这样写 "\\namespacename\\classname" */
$a = '\namespacename\classname';
$obj = new $a; // 输出 namespacename\classname::__construct
$a = 'namespacename\classname';
$obj = new $a; // 也会输出 namespacename\classname::__construct
$b = 'namespacename\funcname';
$b(); // 输出 namespacename\funcname
$b = '\namespacename\funcname';
$b(); // 也会输出 namespacename\funcname
echo constant('\namespacename\constname'), "\n"; // 输出 namespaced
echo constant('namespacename\constname'), "\n"; // 也会输出 namespaced
?>
    ]]>
    </programlisting>
   </example>
  </para>
  <para>
   请一定别忘了阅读 <link linkend="language.namespaces.faq.quote">对字符串中的命名空间名称转义的注解</link>.
  </para>
 </sect1>
 <sect1 xml:id="language.namespaces.nsconstants">
  <title>namespace 关键字和 __NAMESPACE__ 魔术常量</title>
  <titleabbrev>namespace 关键字和 __NAMESPACE__</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   PHP支持两种抽象的访问当前命名空间内部元素的方法，<constant>__NAMESPACE__</constant>
   魔术常量和 <literal>namespace</literal> 关键字。
  </para>
  <para>
   常量 <constant>__NAMESPACE__</constant> 的值是包含当前命名空间名称的字符串。在全局的，不包括在任何命名空间中的代码，它包含一个空的字符串。
   <example>
    <title>__NAMESPACE__ 示例, 在命名空间中的代码</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace MyProject;

echo '"', __NAMESPACE__, '"'; // 输出 "MyProject"
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>__NAMESPACE__ 示例，全局代码</title>
    <programlisting role="php">
     <![CDATA[
<?php

echo '"', __NAMESPACE__, '"'; // 输出 ""
?>
]]>
    </programlisting>
   </example>
   常量 <constant>__NAMESPACE__</constant> 在动态创建名称时很有用，例如：
   <example>
    <title>使用 __NAMESPACE__ 动态创建名称</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace MyProject;

function get($classname)
{
    $a = __NAMESPACE__ . '\\' . $classname;
    return new $a;
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   关键字 <literal>namespace</literal> 可用来显式访问当前命名空间或子命名空间中的元素。它等价于类中的
   <literal>self</literal> 操作符。
   <example>
    <title>namespace 操作符，命名空间中的代码</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace MyProject;

use blah\blah as mine; // 参考 "使用命名空间：别名/导入"

blah\mine(); // 调用函数 MyProject\blah\mine()
namespace\blah\mine(); // 调用函数 MyProject\blah\mine()

namespace\func(); // 调用函数 MyProject\func()
namespace\sub\func(); // 调用函数 MyProject\sub\func()
namespace\cname::method(); // 调用 class MyProject\cname 的静态方法 "method"
$a = new namespace\sub\cname(); // class MyProject\sub\cname 的实例对象
$b = namespace\CONSTANT; // 设置 $b 的值为常量 MyProject\CONSTANT
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>namespace 操作符, 全局代码</title>
    <programlisting role="php">
     <![CDATA[
<?php

namespace\func(); // 调用函数 func()
namespace\sub\func(); // 调用函数 sub\func()
namespace\cname::method(); // 调用 class cname 的静态方法 "method"
$a = new namespace\sub\cname(); // class sub\cname 的实例对象
$b = namespace\CONSTANT; // 设置 $b 的值为常量 CONSTANT
?>
]]>
    </programlisting>
   </example>
  </para>
 </sect1>
 <sect1 xml:id="language.namespaces.importing">
  <title>使用命名空间：别名/导入</title>
  <titleabbrev>别名和导入</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   允许通过别名引用或导入外部的完全限定名称，是命名空间的一个重要特征。这有点类似于在类
   unix 文件系统中可以创建对其它的文件或目录的符号连接。
  </para>
  <para>
   PHP 可以为这些项目导入或设置别名：
   常量、函数、类、接口、trait、枚举和命名空间。
  </para>
  <para>
   别名是通过操作符 <literal>use</literal> 来实现的。下面是五种导入方式的例子：
   <example>
    <title>使用 use 操作符导入/使用别名</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace foo;
use My\Full\Classname as Another;

// 下面的例子与 use My\Full\NSname as NSname 相同
use My\Full\NSname;

// 导入一个全局类
use ArrayObject;

// 导入函数
use function My\Full\functionName;

// 为函数设置别名
use function My\Full\functionName as func;

// 导入常量
use const My\Full\CONSTANT;

$obj = new namespace\Another; // 实例化 foo\Another 对象
$obj = new Another; // 实例化 My\Full\Classname　对象
NSname\subns\func(); // 调用函数 My\Full\NSname\subns\func
$a = new ArrayObject(array(1)); // 实例化 ArrayObject 对象
// 如果不使用 "use \ArrayObject" ，则实例化一个 foo\ArrayObject 对象
func(); // 调用函数 My\Full\functionName
echo CONSTANT; // 输出 My\Full\CONSTANT 的值
?>
]]>
    </programlisting>
   </example>
   注意对命名空间中的名称（包含命名空间分隔符的完全限定名称如
   <literal>Foo\Bar</literal> 以及相对的不包含命名空间分隔符的全局名称如
   <literal>FooBar</literal>）来说，前导的反斜杠是不必要的也不推荐的，因为导入的名称必须是完全限定的，不会根据当前的命名空间作相对解析。
  </para>
  <para>
   为了简化操作，PHP 还支持在一行中使用多个 use 语句
   <example>
    <title>通过 use 操作符导入/使用别名，一行中包含多个 use 语句</title>
    <programlisting role="php">
     <![CDATA[
<?php
use My\Full\Classname as Another, My\Full\NSname;

$obj = new Another; // 实例化 My\Full\Classname 对象
NSname\subns\func(); // 调用函数 My\Full\NSname\subns\func
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   导入操作是在编译执行的，但动态的类名称、函数名称或常量名称则不是。
   <example>
    <title>导入和动态名称</title>
    <programlisting role="php">
     <![CDATA[
<?php
use My\Full\Classname as Another, My\Full\NSname;

$obj = new Another; // 实例化一个 My\Full\Classname 对象
$a = 'Another';
$obj = new $a;      // 实际化一个 Another 对象
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   另外，导入操作只影响非限定名称和限定名称。完全限定名称由于是确定的，故不受导入的影响。
   <example>
    <title>导入和完全限定名称</title>
    <programlisting role="php">
     <![CDATA[
<?php
use My\Full\Classname as Another, My\Full\NSname;

$obj = new Another; // class My\Full\Classname 的实例对象
$obj = new \Another; // class Another 的实例对象
$obj = new Another\thing; // class My\Full\Classname\thing 的实例对象
$obj = new \Another\thing; // class Another\thing 的实例对象
?>
]]>
    </programlisting>
   </example>
  </para>
  <sect2 xml:id="language.namespaces.importing.scope">
   <title>导入规则的范围</title>
   <para>
    <literal>use</literal> 关键词必须在文件最外层范围
    （全局作用域）或在命名空间声明内。
    由于导入发生在编译时，而不是运行时，所以不能放入块作用域。
    以下例子展示了不合规则的 <literal>use</literal> 关键词使用示例：
   </para>
   <para>
    <example>
     <title>不合规的导入规则</title>
     <programlisting role="php">
<![CDATA[
<?php
namespace Languages;

function toGreenlandic()
{
    use Languages\Danish;

    // ...
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <para>
     导入规则独立于每个文件，意味着包含的文件
     <emphasis>不会</emphasis>继承父文件的导入规则。
    </para>
   </note>
  </sect2>
  <sect2 xml:id="language.namespaces.importing.group">
   <title><literal>use</literal> 声明编组</title>
   <para>
    通过单个 &use.namespace; 语句，可以将来自同一个 &namespace; 的
    类、函数、常量一起编组导入。
   </para>
   <informalexample>
    <programlisting role="php">
     <![CDATA[
<?php

use some\namespace\ClassA;
use some\namespace\ClassB;
use some\namespace\ClassC as C;

use function some\namespace\fn_a;
use function some\namespace\fn_b;
use function some\namespace\fn_c;

use const some\namespace\ConstA;
use const some\namespace\ConstB;
use const some\namespace\ConstC;

// 等同于以下编组的 use 声明
use some\namespace\{ClassA, ClassB, ClassC as C};
use function some\namespace\{fn_a, fn_b, fn_c};
use const some\namespace\{ConstA, ConstB, ConstC};
]]>
    </programlisting>
   </informalexample>
  </sect2>
 </sect1>
 <sect1 xml:id="language.namespaces.global">
  <title>全局空间</title>
  <titleabbrev>全局空间</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   如果没有定义任何命名空间，所有的类与函数的定义都是在全局空间，与
   PHP 引入命名空间概念前一样。在名称前加上前缀 <literal>\</literal>
   表示该名称是全局空间中的名称，即使该名称位于其它的命名空间中时也是如此。
   <example>
    <title>使用全局空间说明</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace A\B\C;

/* 这个函数是 A\B\C\fopen */
function fopen() { 
     /* ... */
     $f = \fopen(...); // 调用全局的fopen函数
     return $f;
}
?>
    ]]>
    </programlisting>
   </example>
  </para>
 </sect1>
 <sect1 xml:id="language.namespaces.fallback">
  <title>使用命名空间：回退到全局函数和常量的全局空间</title>
  <titleabbrev>回退到全局空间</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   在一个命名空间中，当 PHP 
   遇到一个非限定的类、函数或常量名称时，它使用不同的优先策略来解析该名称。类名称总是解析到当前命名空间中的名称。因此在访问系统内部或不包含在命名空间中的类名称时，必须使用完全限定名称，例如：
   <example>
    <title>在命名空间中访问全局类</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace A\B\C;
class Exception extends \Exception {}

$a = new Exception('hi'); // $a 是类 A\B\C\Exception 的一个对象
$b = new \Exception('hi'); // $b 是类 Exception 的一个对象

$c = new ArrayObject; // 致命错误, 找不到 A\B\C\ArrayObject 类
?>
    ]]>
    </programlisting>
   </example>
  </para>
  <para>
   对于函数和常量来说，如果当前命名空间中不存在该函数或常量，PHP
   会退而使用全局空间中的函数或常量。
   <example>
    <title>命名空间中后备的全局函数/常量</title>
    <programlisting role="php">
     <![CDATA[
<?php
namespace A\B\C;

const E_ERROR = 45;
function strlen($str)
{
    return \strlen($str) - 1;
}

echo E_ERROR, "\n"; // 输出 "45"
echo INI_ALL, "\n"; // 输出 "7" - 使用全局常量 INI_ALL

echo strlen('hi'), "\n"; // 输出 "1"
if (is_array('hi')) { // 输出 "is not array"
    echo "is array\n";
} else {
    echo "is not array\n";
}
?>
    ]]>
    </programlisting>
   </example>
  </para>
 </sect1>

 <sect1 xml:id="language.namespaces.rules">
  <title>名称解析规则</title>
  <titleabbrev>名称解析规则</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   在说明名称解析规则之前，我们先看一些重要的定义：
   <variablelist>
    <title>命名空间名称定义</title>
    <varlistentry>
     <term>非限定名称（Unqualified name）</term>
     <listitem>
      <para>
       名称中不包含命名空间分隔符的标识符，例如 <literal>Foo</literal>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>限定名称（Qualified name）</term>
     <listitem>
      <para>
       名称中含有命名空间分隔符的标识符，例如 <literal>Foo\Bar</literal>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>完全限定名称（Fully qualified name）</term>
     <listitem>
      <para>
       名称中包含命名空间分隔符，并以命名空间分隔符开始的标识符，例如 <literal>\Foo\Bar</literal>。
       <literal>namespace\Foo</literal> 也是一个完全限定名称。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>相对名称（Relative name）</term>
     <listitem>
      <para>
       这是个以 <literal>namespace</literal> 开头的标识符，
       例如
       <literal>namespace\Foo\Bar</literal>。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <para>
   名称解析遵循下列规则：
   <orderedlist>
    <listitem>
     <simpara>
       完全限定名称总是会解析成没有前缀符号的命名空间名称。
       <literal>\A\B</literal> 解析为 <literal>A\B</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      解析相对名称时，会用当前命名空间的名称替换掉 <literal>namespace</literal>。
      如果名称出现在全局命名空间，会截掉 <literal>namespace\</literal> 前缀。
      例如，在命名空间 <literal>X\Y</literal> 里的 <literal>namespace\A</literal> 会被解析成 <literal>X\Y\A</literal>。
      在全局命名空间里，同样的名字却被解析成 <literal>A</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      对于限定名称，名字的第一段会根据当前 class/namespace 导入表进行翻译。
      比如命名空间 <literal>A\B\C</literal> 被导入为 <literal>C</literal>，
      名称 <literal>C\D\E</literal> 会被翻译成
      <literal>A\B\C\D\E</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      对于限定名称，如果没有应用导入规则，就将当前命名空间添加为名称的前缀。
      例如，位于命名空间 <literal>A\B</literal> 内的名称 <literal>C\D\E</literal>
      会解析成 <literal>A\B\C\D\E</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      根据符号类型和对应的当前导入表，解析非限定名称。
      这也就是说，根据 class/namespace 导入表翻译类名称；
      根据函数导入表翻译函数名称；
      根据常量导入表翻译常量名称。
      比如，在
      <literal>use A\B\C;</literal> 后，类似 <literal>new C()</literal> 这样的名称会解析为
      <literal>A\B\C()</literal>。
      类似的，<literal>use function A\B\foo;</literal> 后，
      <literal>foo()</literal> 的用法，解析名称为 <literal>A\B\foo</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      如果没有应用导入规则，对于类似 class 符号的非限定名称，会添加当前命名空间作为前缀。
      比如命名空间 <literal>A\B</literal> 内的 <literal>new C()</literal>
      会把名称解析为 <literal>A\B\C</literal>。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      如果没有应用导入规则，非限定名称指向函数或常量，且代码位于全局命名空间之外，则会在运行时解析名称。
      假设代码位于命名空间 <literal>A\B</literal> 中，
      下面演示了调用函数
      <literal>foo()</literal> 是如何解析的：
     </simpara>
     <orderedlist>
      <listitem>
       <simpara>
        在当前命名空间中查找函数：
        <literal>A\B\foo()</literal>。
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        它会尝试找到并调用 <emphasis>全局</emphasis> 的函数
        <literal>foo()</literal>。
       </simpara>
      </listitem>
     </orderedlist>
    </listitem>
   </orderedlist>
  </para>
  <example>
   <title>名称解析示例</title>
   <programlisting role="php">
<![CDATA[
<?php
namespace A;
use B\D, C\E as F;

// 函数调用

foo();      // 首先尝试调用定义在命名空间"A"中的函数foo()
            // 再尝试调用全局函数 "foo"

\foo();     // 调用全局空间函数 "foo" 

my\foo();   // 调用定义在命名空间"A\my"中函数 "foo"

F();        // 首先尝试调用定义在命名空间"A"中的函数 "F"
            // 再尝试调用全局函数 "F"

// 类引用

new B();    // 创建命名空间 "A" 中定义的类 "B" 的一个对象
            // 如果未找到，则尝试自动装载类 "A\B"

new D();    // 使用导入规则，创建命名空间 "B" 中定义的类 "D" 的一个对象
            // 如果未找到，则尝试自动装载类 "B\D"

new F();    // 使用导入规则，创建命名空间 "C" 中定义的类 "E" 的一个对象
            // 如果未找到，则尝试自动装载类 "C\E"

new \B();   // 创建定义在全局空间中的类 "B" 的一个对象
            // 如果未发现，则尝试自动装载类 "B"

new \D();   // 创建定义在全局空间中的类 "D" 的一个对象
            // 如果未发现，则尝试自动装载类 "D"

new \F();   // 创建定义在全局空间中的类 "F" 的一个对象
            // 如果未发现，则尝试自动装载类 "F"

// 调用另一个命名空间中的静态方法或命名空间函数

B\foo();    // 调用命名空间 "A\B" 中函数 "foo"

B::foo();   // 调用命名空间 "A" 中定义的类 "B" 的 "foo" 方法
            // 如果未找到类 "A\B" ，则尝试自动装载类 "A\B"

D::foo();   // 使用导入规则，调用命名空间 "B" 中定义的类 "D" 的 "foo" 方法
            // 如果类 "B\D" 未找到，则尝试自动装载类 "B\D"

\B\foo();   // 调用命名空间 "B" 中的函数 "foo"

\B::foo();  // 调用全局空间中的类 "B" 的 "foo" 方法
            // 如果类 "B" 未找到，则尝试自动装载类 "B"

// 当前命名空间中的静态方法或函数

A\B::foo();   // 调用命名空间 "A\A" 中定义的类 "B" 的 "foo" 方法
              // 如果类 "A\A\B" 未找到，则尝试自动装载类 "A\A\B"

\A\B::foo();  // 调用命名空间 "A\B" 中定义的类 "B" 的 "foo" 方法
              // 如果类 "A\B" 未找到，则尝试自动装载类 "A\B"
?>
]]>
   </programlisting>
  </example>
 </sect1>
 <sect1 xml:id="language.namespaces.faq">
  <title>FAQ：命名空间必知必会</title>
  <titleabbrev>FAQ</titleabbrev>
  <?phpdoc print-version-for="namespaces"?>
  <para>
   本文分两节：常见问题、有助于完全理解的实现详情。
  </para>
  <para>
   首先，常见问题。
   <orderedlist>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.shouldicare">如果我不用命名空间，是否需要关心它？</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.globalclass">我如何在命名空间内使用一个全局/内置的类？</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.innamespace">
         如何在命名空间内访问它自己的类、函数、常量？</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.full">
       像 <literal>\my\name</literal> 和 <literal>\name</literal> 这样的名称是如何解析的？
      </link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.qualified">像
      <literal>my\name</literal> 这样的名称是如何解析的？</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.shortname1">像 <literal>name</literal> 这样的非限定类名是如何解析的？</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.shortname2">像 <literal>name</literal> 这样的非限定常量和函数名是如何解析的？</link>
     </simpara>
    </listitem>
   </orderedlist>
  </para>
  <para>
   为了帮助理解，我们提供了一些命名空间实现细节。
   <orderedlist>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.conflict">在同一个文件中，导入名称不能和定义的类名发生冲突。</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.nested">不允许嵌套 namespace。
      </link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.quote">动态命名空间名称（引号标识）应该转义反斜线。</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.constants">引用一个未定义的、带反斜线的常量，会导致 fatal 错误并退出</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link linkend="language.namespaces.faq.builtinconst">不能重载特殊常量：
       &null;, &true; or &false;</link>
     </simpara>
    </listitem>
   </orderedlist>
  </para>
  <sect2 xml:id="language.namespaces.faq.shouldicare">
   <title>如果我不用命名空间，是否需要关心它？</title>
   <para>
    不需要。命名空间不影响现存的代码，也不影响即将要写下的不含命名空间的代码。
    想要的话可以这样写：
   </para>
   <para>
    <example>
     <title>在命名空间之外访问全局类</title>
     <programlisting role="php">
<![CDATA[
<?php
$a = new \stdClass;
]]>
     </programlisting>
    </example>
   </para>
   <para>
    以上等同于：
   </para>
   <para>
    <example>
     <title>在命名空间之外访问全局类</title>
     <programlisting role="php">
<![CDATA[
<?php
$a = new stdClass;
]]>
     </programlisting>
    </example>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.globalclass">
   <title>我如何在命名空间内使用一个全局/内置的类？</title>
   <para>
    <example>
     <title>在命名空间内访问内置的类</title>
     <programlisting role="php">
<![CDATA[
<?php
namespace foo;
$a = new \stdClass;

function test(\ArrayObject $parameter_type_example = null) {}

$a = \DirectoryIterator::CURRENT_AS_FILEINFO;

// 扩展内置或全局的 class
class MyException extends \Exception {}
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.innamespace">
   <title>
    如何在命名空间内访问它自己的类、函数、常量？
   </title>
   <para>
    <example>
     <title>在命名空间中访问内置的类、函数、常量</title>
     <programlisting role="php">
<![CDATA[
<?php
namespace foo;

class MyClass {}

// 以当前命名空间中的 class 作为参数的类型
function test(MyClass $parameter_type_example = null) {}
// 以当前命名空间中的 class 作为参数的类型的另一种方式
function test(\foo\MyClass $parameter_type_example = null) {}

// 在当前命名空间中扩展一个类
class Extended extends MyClass {}

// 访问全局函数
$a = \globalfunc();

// 访问全局常量
$b = \INI_ALL;
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.full">
   <title>
    像 <literal>\my\name</literal> 和 <literal>\name</literal> 这样的名称是如何解析的？
   </title>
   <para>
    以 <literal>\</literal> 开头的名称总是会解析成原样，
    因此 <literal>\my\name</literal> 实际上是 <literal>my\name</literal>，
    而 <literal>\Exception</literal> 是 <literal>Exception</literal>。
    <example>
     <title>完全限定名称</title>
     <programlisting role="php">
<![CDATA[
<?php
namespace foo;
$a = new \my\name(); // class "my\name" 的实例
echo \strlen('hi'); // 调用函数 "strlen"
$a = \INI_ALL; // $a 的值设置成常量 "INI_ALL"
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.qualified">
   <title>像 <literal>my\name</literal> 这样的名称是如何解析的？</title>
   <para>
    像 <literal>my\name</literal> 这样包含反斜线的名称，但不以反斜线开头的名称，
    能够以两种不同的方式解析。
   </para>
   <para>
   如果有个导入语句，将其他名字设置别名为 <literal>my</literal>，
   则导入别名会应用到 <literal>my\name</literal> 的 <literal>my</literal> 部分。
   </para>
   <para>
     如果没有导入，就会追加当前的命名空间名称为 <literal>my\name</literal> 的前缀。
   </para>
   <para>
    <example>
     <title>限定名称</title>
     <programlisting role="php">
<![CDATA[
<?php
namespace foo;
use blah\blah as foo;

$a = new my\name(); // class "foo\my\name" 的实例
foo\bar::name(); // 调用 class "blah\blah\bar" 的静态方法 "name"
my\bar(); // 调用函数 "foo\my\bar"
$a = my\BAR; // 设置 $a 的值为 "foo\my\BAR"
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.shortname1">
   <title>像 <literal>name</literal> 这样的非限定名称是如何解析的？</title>
   <para>
    像 <literal>name</literal> 这样不包含反斜线的名称，
    能够以两种不同的方式解析。
   </para>
   <para>
    如果有导入语句，设置别名为 <literal>name</literal>，就会应用导入别名。
   </para>
   <para>
    如果没有，就会把当前命名空间添加到 <literal>name</literal> 的前缀。
   </para>
   <para>
    <example>
     <title>非限定类名</title>
     <programlisting role="php">
<![CDATA[
<?php
namespace foo;
use blah\blah as foo;

$a = new name(); // class "foo\name" 的实例
foo::name(); // 调用 class "blah\blah" 的静态方法 "name"
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.shortname2">
   <title>
    像 <literal>name</literal> 这样的非限定常量和函数名是如何解析的？
   </title>
   <para>
    像 <literal>name</literal> 这样不包含反斜线的常量和函数名，能以两种不同的方式解析。
   </para>
   <para>
   首先，当前命名空间会添加到 <literal>name</literal> 的前缀。
   </para>
   <para>
   然后，如果当前命名空间不存在函数和常量 <literal>name</literal>，
   而全局存在，就会使用全局的函数和常量 <literal>name</literal>。
   </para>
   <para>
    <example>
     <title>非限定函数和常量名</title>
     <programlisting role="php">
<![CDATA[
<?php
namespace foo;
use blah\blah as foo;

const FOO = 1;

function my() {}
function foo() {}
function sort(&$a)
{
    sort($a);
    $a = array_flip($a);
    return $a;
}

my(); // 调用 "foo\my"
$a = strlen('hi'); // 由于 "foo\strlen" 不存在，所以调用全局的 "strlen"
$arr = array(1,3,2);
$b = sort($arr); // 调用函数 "foo\sort"
$c = foo(); // 未导入，调用函数 "foo\foo"

$a = FOO; // 未导入，设置 $a 为常量 "foo\FOO" 的值
$b = INI_ALL; // 设置 $b 为全局常量 "INI_ALL" 的值
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.conflict">
   <title>在同一个文件中，导入名称不能和定义的类名发生冲突</title>
   <para>
   允许以下脚本中的组合：
    <informalexample>
     <simpara>file1.php</simpara>
     <programlisting role="php">
     <![CDATA[
<?php
namespace my\stuff;
class MyClass {}
?>
     ]]>
     </programlisting>
     <simpara>another.php</simpara>
     <programlisting role="php">
     <![CDATA[
<?php
namespace another;
class thing {}
?>
     ]]>
     </programlisting>
     <simpara>file2.php</simpara>
     <programlisting role="php">
     <![CDATA[
<?php
namespace my\stuff;
include 'file1.php';
include 'another.php';

use another\thing as MyClass;
$a = new MyClass; //  class "thing" 的实例来自于命名空间 another
?>
     ]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    尽管在 <literal>my\stuff</literal> 命名空间中存在 <literal>MyClass</literal>，
    因为类定义在了独立的文件中，所以不会发生名称冲突。
    不过，接下来的例子中，因为 MyClass 定义在了 use 语句的同一个文件中，
    所以发生了名称冲突，导致了 fatal 错误。
    <informalexample>
     <programlisting role="php">
     <![CDATA[
<?php
namespace my\stuff;
use another\thing as MyClass;
class MyClass {} // fatal error: MyClass conflicts with import statement
$a = new MyClass;
?>
     ]]>
     </programlisting>
    </informalexample>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.nested">
   <title>不允许嵌套 namespace</title>
   <para>
    PHP 不允许嵌套 namespace
    <informalexample>
     <programlisting role="php">
     <![CDATA[
<?php
namespace my\stuff {
    namespace nested {
        class foo {}
    }
}
?>
     ]]>
     </programlisting>
    </informalexample>
    实际上，它看上去像是这样：
    <informalexample>
     <programlisting role="php">
     <![CDATA[
<?php
namespace my\stuff\nested {
    class foo {}
}
?>
     ]]>
     </programlisting>
    </informalexample>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.quote">
   <title>动态命名空间名称（引号标识）应该转义反斜线</title>
   <para>
     重要的是，字符串中反斜线是一个转义字符，因此在字符串中使用时，必须要写两遍。
     否则就会在无意中造成一些后果：
    <example>
     <title>在双引号字符串中使用命名空间的危险性</title>
     <programlisting role="php">
      <![CDATA[
<?php
$a = new "dangerous\name"; // 在双引号字符串中，\n 是换行符！
$obj = new $a;

$a = new 'not\at\all\dangerous'; // 这里没有问题
$obj = new $a;
?>
      ]]>
     </programlisting>
    </example>
    在单引号字符串中，使用反斜线是安全的。
    但在最佳实践中，我们仍然推荐为所有字符串统一转义反斜线。
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.constants">
   <title>引用一个未定义的、带反斜线的常量，会导致 fatal 错误并退出</title>
   <para>
    像 <literal>FOO</literal> 这样的非限定名称常量，如果使用的时候还没定义，
    会产生一个 notice。PHP 会假设该常量的值是 <literal>FOO</literal>。
    如果没有找到包含反斜线的常量，无论是完全或者不完全限定的名称，都会产生 fatal 错误。
    <example>
     <title>未定义的常量</title>
     <programlisting role="php">
      <![CDATA[
<?php
namespace bar;
$a = FOO; // 产生 notice - undefined constants "FOO" assumed "FOO";
$a = \FOO; // fatal error, undefined namespace constant FOO
$a = Bar\FOO; // fatal error, undefined namespace constant bar\Bar\FOO
$a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
?>
      ]]>
     </programlisting>
    </example>
   </para>
  </sect2>
  <sect2 xml:id="language.namespaces.faq.builtinconst">
   <title>不能重载特殊常量：&null;, &true; or &false;</title>
   <para>
    在命名空间内定义特殊的内置常量，会导致 fatal 错误
    <example>
     <title>未定义的常量</title>
     <programlisting role="php">
      <![CDATA[
<?php
namespace bar;
const NULL = 0; // fatal error;
const true = 'stupid'; // 也是 fatal error;
// etc.
?>
      ]]>
     </programlisting>
    </example>
   </para>
  </sect2>
 </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:"~/.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
-->