Annotation of embedaddon/php/Zend/RFCs/002.txt, revision 1.1
1.1 ! misho 1: Title: Zend 2.0 Namespaces
! 2: Version: $Revision: 148341 $
! 3: Status: declined
! 4: Maintainer: Stig S. Bakken <ssb@php.net>
! 5: Created: 2001-09-08
! 6: Modified: 2001-09-08
! 7:
! 8:
! 9: 1. Background/Need
! 10: ==================
! 11:
! 12: PHP and Zend 1.0 have come to a point where a lot of reusable code is
! 13: being written; from simple functions and classes to entire application
! 14: frameworks. It is becoming increasingly difficult to avoid symbol
! 15: name collisions with the current scoping methods.
! 16:
! 17: The symbol scopes available in Zend 1.0 are the global scope, the
! 18: class scope and the function scope. All scopes but classes may
! 19: contain variables, only the class and global scopes may contain
! 20: functions, while only the global scope may contain constants and
! 21: classes. This means that all of Zend 1.0's scoping methods are
! 22: inherently limited for solving symbol name collision problems.
! 23:
! 24:
! 25: 2. Overview
! 26: ===========
! 27:
! 28: Namespaces in Zend 2.0 provide a way to manage the symbol collision
! 29: problem by making it possible to define multiple symbol tables able to
! 30: contain all types of symbols. Zend will get the notion of a current
! 31: namespace, defaulting to the current global one. The current name
! 32: space may be changed on a file-by-file basis. Symbols in other name
! 33: spaces than the current one may be referenced using a new namespace
! 34: operator. It will be possible to "import" symbols from one namespace
! 35: into another.
! 36:
! 37:
! 38: 3. Functionality
! 39: ================
! 40:
! 41: 3.1. Namespace Syntax
! 42: =====================
! 43:
! 44: The namespace operator ":" is used to refer to symbols in other
! 45: namespaces than the current one:
! 46:
! 47: Class: Namespace:class
! 48: Function: Namespace:function
! 49: Static method: Namespace:class::method
! 50: Variable: $Namespace:variable
! 51: Constant: Namespace:CONSTANT
! 52: Class variable: $Namespace:class::variable
! 53:
! 54: To refer to symbols in the global namespace, symbols are prefixed with
! 55: only the namespace operator:
! 56:
! 57: Class: :class
! 58: Function: :function
! 59: Static method: :class::method
! 60: Variable: $:variable
! 61: Constant: :CONSTANT
! 62: Class variable: $:class::variable
! 63:
! 64: Note: $:variable will effectively be just another syntax for
! 65: $GLOBALS['variable'].
! 66:
! 67: A namespace may have a name containing a ":", it is always the last
! 68: ":" character in the symbol qualifier that is the actual namespace
! 69: operator:
! 70:
! 71: Class: Name:Space:class
! 72: Function: Name:Space:function
! 73: Static method: Name:Space:class::method
! 74: Variable: $Name:Space:variable
! 75: Constant: Name:Space:CONSTANT
! 76: Class variable: $Name:Space:class::variable
! 77:
! 78: (Here, the ":" between "Name" and "Space" is part of the name, it is
! 79: the one after "Space" that is the namespace operator.)
! 80:
! 81:
! 82: 3.2. Defining Namespaces
! 83: ========================
! 84:
! 85: Individual files may define a namespace that will apply to the entire
! 86: file. If no "namespace" operator occurs in the file, it will be in
! 87: the global namespace:
! 88:
! 89: 1 namespace HTML;
! 90: 2
! 91: 3 class Form {
! 92: 4 function Form() {
! 93: 5 // constructor
! 94: 6 }
! 95: 7 // ...
! 96: 8 }
! 97:
! 98: Or with the "nested" name syntax:
! 99:
! 100: 1 namespace HTML:Form;
! 101: 2
! 102: 3 class Image {
! 103: 4 var $src;
! 104: 5 function Image($src) {
! 105: 6 $this->src = $src;
! 106: 7 }
! 107: 8 // ...
! 108: 9 }
! 109:
! 110: Code executed within the "HTML" namespace may refer to the Form class
! 111: as just "Form". Code executed from within other namespaces has to
! 112: refer to it as "HTML:Form". The "namespace" statement must occur
! 113: before any other statements in the file.
! 114:
! 115: # [ssb 2001-09-08]:
! 116: # Should it be possible to "add" symbols to a namespace by including a
! 117: # second file with the same namespace statement?
! 118:
! 119:
! 120: 3.3. Importing Symbols
! 121: ======================
! 122:
! 123: It is possible to import symbols from another namespace into the
! 124: current one with the "import" statement:
! 125:
! 126: import * from HTML; // all symbols
! 127:
! 128: import Form from HTML; // single symbols
! 129:
! 130: import Form,Table from HTML; // multiple symbols
! 131:
! 132: There is a potential for name clashes between symols of different
! 133: types that have the same qualifier syntax. These are resolved in this
! 134: order: class, function, constant.
! 135:
! 136: Optionally, the symbol type may be explicitly given to import (as
! 137: "class", "function", "variable" or "constant"):
! 138:
! 139: import class Form from HTML;
! 140:
! 141: And finally, you may import all symbols of a given type:
! 142:
! 143: import constant * from HTML:Table;
! 144:
! 145: The namespace with its symbols must already be defined before using
! 146: "import".
! 147:
! 148:
! 149: 4. Compatibility Notes
! 150: ======================
! 151:
! 152: Old code that does not take advantage of namespaces will run without
! 153: modifications.
! 154:
! 155:
! 156: 5. Dependencies
! 157: ===============
! 158:
! 159: The class variable syntax depends on this class variables being
! 160: implemented in the new ZE2 object model.
! 161:
! 162:
! 163: 6. Acknowledgements
! 164: ===================
! 165:
! 166: Andi Gutmans <andi@zend.com> and Zeev Suraski <zeev@zend.com> for
! 167: initial ZE2 namespaces proposal
! 168:
! 169: Dean Hall <php@apt7.com> for the initial symbol qualification syntax
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>