How to Use PHP Namespaces, Part 1: the Basics
Total Page:16
File Type:pdf, Size:1020Kb
How to Use PHP Namespaces, Part 1: The Basics Author: Craig Buckler Namespaces are one of the most significant changes in PHP 5.3. They will be familiar to C# and Java developers, and they are likely to change the structure of PHP applications for the better. Why Do We Need Namespaces? As the size of your PHP code library increases, there is increased risk of accidentally re-defining a function or class name that has been declared before. The problem is exacerbated when you attempt to add third-party components or plugins; what if two or more code sets implement a ‘Database’ or ‘User’ class? Until now, the only solution has been long class/function names. For example, WordPress prefixes every name with ‘WP_’. The Zend Framework uses a highly descriptive naming convention that results in long-winded class names such as Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive . Name collision problems can be solved with namespaces. PHP constants, classes, and functions can be grouped into namespaced libraries. How are Namespaces Defined? By default, all constant, class, and function names are placed in the global space — like they were before PHP supported namespaces. Namespaced code is defined using a single namespace keyword at the top of your PHP file. It must be the first command (with the exception of declare ) and no non-PHP code, HTML, or white-space can precede the command, e.g. 1. <?php 2. // define this code in the 'MyProject' namespace 3. namespace MyProject; 4. // ... code ... The code following this line will be assigned to the ‘MyProject’ namespace. It is not possible to nest namespaces or define more than one namespace for the same code block (only the last will be recognized). However, you can define different namespaced code in the same file, e.g. 1. <?php 2. namespace MyProject1; 3. // PHP code for the MyProject1 namespace 4. namespace MyProject2; 5. // PHP code for the MyProject2 namespace 6. // Alternative syntax 7. namespace MyProject3 { 8. // PHP code for the MyProject3 namespace 9. } 10. ?> Although this is possible, I would advise against it: retain your sanity by defining a single namespace per file. Sub-namespaces PHP allows you to define a hierarchy of namespaces so libraries can be sub-divided. Sub- namespaces are separated using a backslash (\) character, e.g. • MyProject\SubName • MyProject\Database\MySQL • CompanyName\MyProject\Library\Common\Widget1 Calling Namespaced Code In a file named lib1.php, we will define a constant, a function, and a class within the App\Lib1 namespace: lib1.php 1. <?php 2. // application library 1 3. namespace App\Lib1; 4. const MYCONST = 'App\Lib1\MYCONST'; 5. function MyFunction() { 6. return __FUNCTION__; 7. } 8. class MyClass { 9. static function WhoAmI() { 10. return __METHOD__; 11. } 12. } 13. ?> We can now include this code in another PHP file, e.g. myapp.php 1. <?php 2. header('Content-type: text/plain'); 3. require_once('lib1.php'); 4. echo \App\Lib1\MYCONST . "\n"; 5. echo \App\Lib1\MyFunction() . "\n"; 6. echo \App\Lib1\MyClass::WhoAmI() . "\n"; 7. ?> No namespace is defined in myapp.php so the code exists in the global space. Any direct reference to MYCONST, MyFunction or MyClass will fail because they exist in the App\Lib1 namespace. To call code in lib1.php, we can add a prefix of \App\Lib1 to define fully- qualified names. The following result is output when we load myapp.php: 1. App\Lib1\MYCONST 2. App\Lib1\MyFunction 3. App\Lib1\MyClass::WhoAmI Fully-qualified names can become quite long and there are few obvious benefits over defining long class names such as App-Lib1-MyClass. Therefore, in the next article, we will discuss aliasing and take a closer look at how PHP resolves namespace names. How to Use PHP Namespaces, Part 2: Importing, Aliases, and Name Resolution In part 1 , we discussed why PHP namespaces are useful and the namespace keyword. In this article, we examine the use command and the way PHP resolves namespace names. For the purposes of this example, we will define two almost identical code blocks; the only difference is their namespace: lib1.php: 1. <?php 2. // application library 1 3. namespace App\Lib1; 4. const MYCONST = 'App\Lib1\MYCONST'; 5. function MyFunction() { 6. return __FUNCTION__; 7. } 8. class MyClass { 9. static function WhoAmI() { 10. return __METHOD__; 11. } 12. } 13. ?> lib2.php: 1. <?php 2. // application library 2 3. namespace App\Lib2; 4. const MYCONST = 'App\Lib2\MYCONST'; 5. function MyFunction() { 6. return __FUNCTION__; 7. } 8. class MyClass { 9. static function WhoAmI() { 10. return __METHOD__; 11. } 12. } 13. ?> There is a little PHP terminology to understand before we begin… Fully-qualified name Any PHP code can refer to a fully-qualified name — an identifier starting with the namespace backslash separator, e.g. \App\Lib1\MYCONST, \App\Lib2\MyFunction(), etc. Fully-qualified names have no ambiguity. The initial backslash operates in a similar way to a file path; it signifies the ‘root’ global space. If we implemented a different MyFunction() in our global space, it could be called from lib1.php or lib2.php using \MyFunction() . Fully-qualified names are useful for one-off function calls or object initialization. However, they can become impractical when you are making lots of calls. As we will discover below, PHP offers other options to save us from namespace typing cramps. Qualified name An identifier with at least one namespace separator, e.g. Lib1\MyFunction(). Unqualified name An identifier without a namespace separator, e.g. MyFunction(). Working Within the Same Namespace Consider the following code: myapp1.php: 1. <?php 2. namespace App\Lib1; 3. require_once('lib1.php'); 4. require_once('lib2.php'); 5. header('Content-type: text/plain'); 6. echo MYCONST . "\n"; 7. echo MyFunction() . "\n"; 8. echo MyClass::WhoAmI() . "\n"; 9. ?> Although we include both lib1.php and lib2.php , the identifiers MYCONST, MyFunction, and MyClass will only reference code in lib1.php . This occurs because the myapp1.php code is within the same App\Lib1 namespace: result: 1. App\Lib1\MYCONST 2. App\Lib1\MyFunction 3. App\Lib1\MyClass::WhoAmI Namespace Importing Namespaces can be imported with the use operator, e.g. myapp2.php: 1. <?php 2. use App\Lib2; 3. require_once('lib1.php'); 4. require_once('lib2.php'); 5. header('Content-type: text/plain'); 6. echo Lib2\MYCONST . "\n"; 7. echo Lib2\MyFunction() . "\n"; 8. echo Lib2\MyClass::WhoAmI() . "\n"; 9. ?> Any number of use statements can be defined or you can separate individual namespaces with a comma. In this example we have imported the App\Lib2 namespace. We still cannot refer directly to MYCONST, MyFunction or MyClass because our code is in the global space and PHP will look for them there. However, if we add a prefix of ‘Lib2\’, they become qualified names; PHP will search through the imported namespaces until it finds a match. result: 1. App\Lib2\MYCONST 2. App\Lib2\MyFunction 3. App\Lib2\MyClass::WhoAmI Namespace Aliases Namespace aliases are perhaps the most useful construct. Aliases allow us to reference long namespaces using a shorter name. myapp3.php: 1. <?php 2. use App\Lib1 as L; 3. use App\Lib2\MyClass as Obj; 4. header('Content-type: text/plain'); 5. require_once('lib1.php'); 6. require_once('lib2.php'); 7. echo L\MYCONST . "\n"; 8. echo L\MyFunction() . "\n"; 9. echo L\MyClass::WhoAmI() . "\n"; 10. echo Obj::WhoAmI() . "\n"; 11. ?> The first use statement defines App\Lib1 as ‘L’. Any qualified names using ‘L’ will be translated to ‘App\Lib1 ′ at compile-time. We can therefore refer to L\MYCONST and L\MyFunction rather than the fully-qualified name. The second use statement is more interesting. It defines ‘Obj’ as an alias for the class ‘MyClass’ within the App\Lib2\ namespace. This is only possible for classes — not constants or functions. We can now use new Obj() or run static methods as shown above. result: 1. App\Lib1\MYCONST 2. App\Lib1\MyFunction 3. App\Lib1\MyClass::WhoAmI 4. App\Lib2\MyClass::WhoAmI PHP Name Resolution Rules PHP identifier names are resolved using the following namespace rules. Refer to the PHP manual for more information. 1. Calls to fully-qualified functions, classes or constants are resolved at compile-time. 2. Unqualified and qualified names are translated according to the import rules, e.g. if the namespace A\B\C is imported as C, a call to C\D\e() is translated to A\B\C\D\e() . 3. Inside a namespace, all qualified names not already translated according to import rules have the current namespace prepended, e.g. if a call to C\D\e() is performed within namespace A\B, it is translated to A\B\C\D\e() . 4. Unqualified class names are translated according to current import rules and the full name is substituted for short imported name, e.g. if class C in namespace A\B is imported as X, new X() is translated to new A\B\C() . 5. Unqualified function calls within a namespace are resolved at run-time. For example, if MyFunction() is called within namespace A\B, PHP first looks for the function \A\B\MyFunction(). If that is not found, it looks for \MyFunction() in the global space. 6. Calls to unqualified or qualified class names are resolved at run-time. For example, if we call new C() within namespace A\B, PHP will look for the class A\B\C. If that is not found, it will attempt to autoload A\B\C. How to Use PHP Namespaces, Part 3: Keywords and Autoloading In parts 1 and 2 of this series, we looked at PHP namespace basics , the use operator, and name resolution . In this final article we discuss some of the more advanced namespace options.