Annotation of embedaddon/php/README.namespaces, revision 1.1
1.1 ! misho 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.namespaces CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php