release/src/router/php/README.namespaces

   1 Design
   2 ======
   3
   4 Main assumption of the model is that the problem that we are to solve is the
   5 problem of the very long class names in PHP libraries. We would not attempt
   6 to take autoloader's job or create packaging model - only make names
   7 manageable.
   8
   9 Namespaces are defined the following way:
  10
  11 Zend/DB/Connection.php:
  12 <?php
  13 namespace Zend\DB;
  14
  15 class Connection {
  16 }
  17
  18 function connect() {
  19 }
  20 ?>
  21
  22 Namespace definition does the following:
  23 All class and function names inside are automatically prefixed with
  24 namespace name. Inside namespace, local name always takes precedence over
  25 global name. Several files may be using the same namespace.
  26 The namespace declaration statement must be the very first statement in
  27 the file. The only exception is "declare" statement that can be used before.
  28
  29 Every class and function in a namespace can be referred to by the full name
  30 - e.g. Zend\DB\Connection or Zend\DB\connect - at any time.
  31
  32 <?php
  33 require 'Zend/Db/Connection.php';
  34 $x = new Zend\DB\Connection;
  35 Zend\DB\connect();
  36 ?>
  37
  38 Namespace or class name can be imported:
  39
  40 <?php
  41 require 'Zend/Db/Connection.php';
  42 use Zend\DB;
  43 use Zend\DB\Connection as DbConnection;
  44
  45 $x = new Zend\DB\Connection();
  46 $y = new DB\connection();
  47 $z = new DbConnection();
  48 DB\connect();
  49 ?>
  50
  51 The use statement only defines name aliasing. It may create name alias for
  52 namespace or class. The simple form of statement "use A\B\C\D;" is
  53 equivalent to "use A\B\C\D as D;". The use statement can be used at any
  54 time in the global scope (not inside function/class) and takes effect from
  55 the point of definition down to the end of file. It is recommended however to
  56 place the use statements at the beginning of the file. The use statements have
  57 effect only on the file where they appear.
  58
  59 The special "empty" namespace (\ prefix) is useful as explicit global
  60 namespace qualification. All class and function names started from \
  61 interpreted as global.
  62
  63 <?php
  64 namespace A\B\C;
  65
  66 $con = \mysql_connect(...);
  67 ?>
  68
  69 A special constant __NAMESPACE__ contains the name of the current namespace.
  70 It can be used to construct fully-qualified names to pass them as callbacks.
  71
  72 <?php
  73 namespace A\B\C;
  74
  75 function foo() {
  76 }
  77
  78 set_error_handler(__NAMESPACE__ . "\foo");
  79 ?>
  80
  81 In global namespace __NAMESPACE__ constant has the value of empty string.
  82
  83 Names inside namespace are resolved according to the following rules:
  84
  85 1) all qualified names are translated during compilation according to
  86 current import rules. So if we have "use A\B\C" and then "C\D\e()"
  87 it is translated to "A\B\C\D\e()".
  88 2) unqualified class names translated during compilation according to
  89 current import rules. So if we have "use A\B\C" and then "new C()" it
  90 is translated to "new A\B\C()".
  91 3) inside namespace, calls to unqualified functions that are defined in
  92 current namespace (and are known at the time the call is parsed) are
  93 interpreted as calls to these namespace functions.
  94 4) inside namespace, calls to unqualified functions that are not defined
  95 in current namespace are resolved at run-time. The call to function foo()
  96 inside namespace (A\B) first tries to find and call function from current
  97 namespace A\B\foo() and if it doesn't exist PHP tries to call internal
  98 function foo(). Note that using foo() inside namespace you can call only
  99 internal PHP functions, however using \foo() you are able to call any
 100 function from the global namespace.
 101 5) unqualified class names are resolved at run-time. E.q. "new Exception()"
 102 first tries to use (and autoload) class from current namespace and in case
 103 of failure uses internal PHP class. Note that using "new A" in namespace
 104 you can only create class from this namespace or internal PHP class, however
 105 using "new \A" you are able to create any class from the global namespace.
 106 6) Calls to qualified functions are resolved at run-time. Call to
 107 A\B\foo() first tries to call function foo() from namespace A\B, then
 108 it tries to find class A\B (__autoload() it if necessary) and call its
 109 static method foo()
 110 7) qualified class names are interpreted as class from corresponding
 111 namespace. So "new A\B\C()" refers to class C from namespace A\B.
 112
 113 Examples
 114 --------
 115 <?php
 116 namespace A;
 117 foo();   // first tries to call "foo" defined in namespace "A"
 118          // then calls internal function "foo"
 119 \foo(); // calls function "foo" defined in global scope
 120 ?>
 121
 122 <?php
 123 namespace A;
 124 new B();   // first tries to create object of class "B" defined in namespace "A"
 125            // then creates object of internal class "B"
 126 new \B(); // creates object of class "B" defined in global scope
 127 ?>
 128
 129 <?php
 130 namespace A;
 131 new A(); // first tries to create object of class "A" from namespace "A" (A\A)
 132          // then creates object of internal class "A"
 133 ?>
 134
 135 <?php
 136 namespace A;
 137 B\foo();   // first tries to call function "foo" from namespace "A\B"
 138             // then calls method "foo" of internal class "B"
 139 \B\foo(); // first tries to call function "foo" from namespace "B"
 140             // then calls method "foo" of class "B" from global scope
 141 ?>
 142
 143 The worst case if class name conflicts with namespace name
 144 <?php
 145 namespace A;
 146 A\foo();   // first tries to call function "foo" from namespace "A\A"
 147             // then tries to call method "foo" of class "A" from namespace "A"
 148             // then tries to call function "foo" from namespace "A"
 149             // then calls method "foo" of internal class "A"
 150 \A\foo(); // first tries to call function "foo" from namespace "A"
 151             // then calls method "foo" of class "A" from global scope
 152 ?>
 153
 154 TODO
 155 ====
 156
 157 * Support for namespace constants?
 158
 159 * performance problems
 160   - calls to internal functions in namespaces are slower, because PHP first
 161     looks for such function in current namespace
 162   - calls to static methods are slower, because PHP first tries to look
 163     for corresponding function in namespace
 164
 165 * Extend the Reflection API?
 166   * Add ReflectionNamespace class
 167     + getName()
 168     + getClasses()
 169     + getFunctions()
 170     + getFiles()
 171   * Add getNamespace() methods to ReflectionClass and ReflectionFunction
 172
 173 * Rename namespaces to packages?
 174