diff --git a/language/namespaces.xml b/language/namespaces.xml new file mode 100644 index 0000000000..d650dbe13e --- /dev/null +++ b/language/namespaces.xml @@ -0,0 +1,437 @@ + + + + Namespaces + + + Namespaces overview + + Namespaces in PHP are designed to solve scoping problem in large PHP + libraries. In PHP, all class definitions are global. Thus, when a library + author creates various utility or public API classes for the library, he must + be aware of the possibility that other libraries with similar functionality + would exist and thus choose unique names so that these libraries could be + used together. Usually it is solved by prefixing the class names with an + unique string - e.g., database classes would have prefix + My_Library_DB, etc. As the library grows, prefixes add up, + leading to the very long names. + + + The namespaces allow the developer to manage naming scopes without using the + long names each time the class is referred to, and solve the problem of + shared globals space without making code unreadable. + + + Namespaces are available in PHP as of PHP 5.3.0. This section is experimental + and subject to changes. + + + + + Namespace definition + + The namespace is declared using namespace + keyword, which should be at the very beginning of the file. Example: + + Defining namespace + + +]]> + + + Same namespace name can be used in multiple files. + + + + Namespace can contain class, constant and function definitions, but no free code. + + + + Namespace definition does the following: + + + + Inside namespace, all class, function and constant names in definitions are + automatically prefixed with namespace name. The class name is always the + full name, i.e. in the example above the class is called + MyProject::DB::Connection. + + + + + Constant definitions create constant which is composed of namespace name and constant name. + Like class constants, namespace constant can only contains static values. + + + + + Unqualified class name (i.e., name not containing ::) + is resolved at runtime following this procedure: + + + + Class is looked up inside the current namespace (i.e. prefixing the + name with the current namespace name) without attempting to + autoload. + + + + + Class is looked up inside the global namespace without attempting to + autoload. + + + + + Autoloading for name in current namespace is attempted. + + + + If previous failed, lookup fails. + + + + + + + Unqualified function name (i.e., name not containing + ::) is looked up at runtime first in the current namespace + and then in the global space. + + + + + Unqualified constant names are looked up first at current namespace and then + among globally defined constants. + + + + See also the full name resolution rules. + + + + + + Using namespaces + + Every class and function in a namespace can be referred to by the full name - + e.g. MyProject::DB::Connection or + MyProject::DB::connect - at any time. + + Using namespaced name + + +]]> + + + + + + Namespaces can be imported into current context (global or namespace) using + the use operator. The syntax for the operator is: + + + +]]> + + + The imported name works as follows: every time that the compiler encounters + the local name Othername (as stand-alone name or as + prefix to the longer name separated by ::) the imported + name Some::Name is substituted instead. + + + + use can be used only in global scope, not inside + function or class. Imported names have effect from the point of import to + the end of the current file. It is recommended to put imports at the + beginning of the file to avoid confusion. + + + + + Importing and accessing namespace + + +]]> + + + + + + + The import operation is compile-time only, all local names are converted to + their full equivalents by the compiler. Note that it won't translate names + in strings, so callbacks can't rely on import rules. + + + + + + + Global space + + Without any namespace definition, all class and function definitions are + placed into the global space - as it was in PHP before namespaces were + supported. Prefixing a name with :: will specify that + the name is required from the global space even in the context of the + namespace. + + Using global space specification + + +]]> + + + + + + + __NAMESPACE__ + + The compile-time constant __NAMESPACE__ is defined to + the name of the current namespace. Outside namespace this constant has the + value of empty string. This constant is useful when one needs to compose + full name for local namespaced names. + + Using __NAMESPACE__ + + +]]> + + + + + + + Name resolution rules + + Names are resolved following these resolution rules: + + + + All qualified names are translated during compilation according to current + import rules. In example, if the namespace A::B::C is imported, a call to + C::D::e() is translated to A::B::C::D::e(). + + + + + Unqualified class names are translated during compilation according to current + import rules (full name substituted for short imported name). In example, if + the namespace A::B::C is imported, new C() is + translated to new A::B::C(). + + + + + Inside namespace, calls to unqualified functions that are defined in the + current namespace (and are known at the time the call is parsed) are + interpreted as calls to these namespace functions, at compile time. + + + + + Inside namespace (say A::B), calls to unqualified functions that are not + defined in current namespace are resolved at run-time. Here is how a + call to function foo() is resolved: + + + + + It looks for a function from the current namespace : + A::B::foo(). + + + + + It tries to find and call the internal function + foo(). + + + + + To call a user defined function in the global namespace, + ::foo() has to be used. + + + + + Inside namespace (say A::B), calls to unqualified class names are + resolved at run-time. Here is how a call to + new C() is resolved: + + + + + It looks for a class from the current namespace : + A::B::C(). + + + + + It tries to find and call the internal class + C(). + + + + + It attemts to autoload A::B::C(). + C(). + + + + + To reference a user defined class in the global namespace, + new ::C() has to be used. + + + + + Calls to qualified functions are resolved at run-time. Here is how a call + to A::B::foo() is resolved: + + + + + It looks for a function foo() in the namespace + A::B. + + + + + It looks for a class A::B and call its static + method foo(). It will autoload the class if + necessary. + + + + + + + Qualified class names are resolved in compile-time as class from corresponding + namespace. For example, new A::B::C() refers to class + C from namespace >A::B. + + + + + + Name resolutions illustrated + + +]]> + + + + + +