Return to README.namespaces CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php

php

    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: