2011 03 02 Namespaces v2

Using PHP 5.
3 Namespaces for Fame and Fortune

Matthew Weier O'Phinney Project Lead, Zend Framework
All rights reserved. Zend Technologies, Inc.
What are namespaces?
What are namespaces?

"A way in which to group related classes, functions and constants"
http://php.net/namespace
Basics
Namespace Separator
\
Get over it!
What can live in namespaces
Classes Constants Functions
Declaring namespaces
Single line declaration

namespace Zend; namespace Zend;
Block declaration
namespace Zend namespace Zend { { } } namespace Phly namespace Phly { { } }
Subnamespaces
Separate the subnamespaces using the namespace separator

namespace Zend\Log; namespace Zend\Log; namespace Zend\Log\Writer; namespace Zend\Log\Writer;
Referring to namespaced elements
From non-namespaced code:

$class = new My\Registry(); $class = new My\Registry(); $class = new My\Log\Logger(); $class = new My\Log\Logger(); My\str_split($s); // function call My\str_split($s); // function call $val = My\APIKEY; // constant value $val = My\APIKEY; // constant value
From code using the same namespace:

namespace My; namespace My; $class = new Registry(); $class = new Registry(); $class = new Log\Logger(); $class = new Log\Logger(); str_split($s); // function call str_split($s); // function call $val = APIKEY; // constant value $val = APIKEY; // constant value
From code in a different namespace:

namespace Your; namespace Your; $class = new \My\Registry(); $class = new \My\Registry(); $class = new \My\Log\Logger(); $class = new \My\Log\Logger(); \My\str_split($s); // function call \My\str_split($s); // function call $val = \My\APIKEY; // constant value $val = \My\APIKEY; // constant value
Using namespaced code:
Prefixing with a namespace separator resolves as a fully qualified name Resolution order:

Globally qualified: known; otherwise: Current namespace, or relative to it (Classes, functions, constants) Global namespace (functions, constants)
This means:
You can override system functions within namespaces!

namespace My; namespace My; function str_split($string, $splitlen = 2) function str_split($string, $splitlen = 2) { { return preg_split('/\W/', $string, $splitlen); return preg_split('/\W/', $string, $splitlen); } } $a = str_split("Foo, Bar"); // invokes My\str_split() $a = str_split("Foo, Bar"); // invokes My\str_split() /* array ( /* array ( * * 0 => 'Foo', 0 => 'Foo', * * 1 => ' Bar', 1 => ' Bar', * ) * ) */ */
Importing namespaces
A way to bring code from another namespace into the current namespace. Import:

Classes Other namespaces
Keyword used is use
namespace My; namespace My; class Registry {} class Registry {} namespace Your; namespace Your; use My; // imports namespace use My; // imports namespace use My\Registry; // imports class use My\Registry; // imports class
Using imported code

namespace Your; namespace Your; use My; // imports namespace use My; // imports namespace $r = new My\Registry(); $r = new My\Registry(); namespace Your; namespace Your; use My\Registry; // imports class use My\Registry; // imports class $r = new Registry(); $r = new Registry();
Aliasing
"import namespace or class, but refer to it using this name" PHP utilizes the as keyword to alias
Aliasing
namespace Your; namespace Your; use My as m; use My as m; $r = new m\Registry(); $r = new m\Registry(); namespace Your; namespace Your; use My\Registry as reg; use My\Registry as reg; $r = new reg(); $r = new reg();
Make typehinting more semantic!

namespace App; namespace App; use Zend\EventManager\EventManager as Events; use Zend\EventManager\EventManager as Events; class Foo class Foo { { public function events(Events $events = null) public function events(Events $events = null) { { if ($events instanceof Events) { if ($events instanceof Events) { $this->events = $events; $this->events = $events; } elseif (!$this->events instanceof Events) { } elseif (!$this->events instanceof Events) { $this->events = new Events(__CLASS__); $this->events = new Events(__CLASS__); } } return $this->events; return $this->events; } } } }
Importing multiple namespaces/classes
Multiple use statements

namespace Their; namespace Their; use My; use My; use Your; use Your;
Or use a comma (,) to separate statements

namespace Their; namespace Their; use My, use My, Your; Your;
With aliases
namespace Their; namespace Their; use My as m, // aliased use My as m, // aliased Your; // not aliased Your; // not aliased
What namespace are you in?
__NAMESPACE__
Comprehensive example
The setup:
namespace My\Package; namespace My\Package; const APIKEY = 1; const APIKEY = 1; function get($data) {} function get($data) {} class Service {} class Service {} namespace My\OtherPackage; namespace My\OtherPackage; const APIKEY = 2; const APIKEY = 2; function get($data) {} function get($data) {} class Service {} class Service {}
namespace Test; namespace Test; use My\Package\Service as PackageService, use My\Package\Service as PackageService, My\OtherPackage; My\OtherPackage; const APIKEY = 3; const APIKEY = 3; echo APIKEY; // 3 echo APIKEY; // 3 echo OtherPackage\APIKEY; // 2 echo OtherPackage\APIKEY; // 2 echo \My\Package\APIKEY; // 1 echo \My\Package\APIKEY; // 1 $s = new PackageService(); // My\Package\Service $s = new PackageService(); // My\Package\Service $s = new Service(); // E_FATAL (no match) $s = new Service(); // E_FATAL (no match) $s = new OtherPackage\Service(); $s = new OtherPackage\Service(); // My\OtherPackage\Service // My\OtherPackage\Service get($baz); get($baz); // E_FATAL (no matching function in // E_FATAL (no matching function in // current namespace) // current namespace) OtherPackage\get($baz); // My\OtherPackage\get() OtherPackage\get($baz); // My\OtherPackage\get()
Pitfalls
Referencing namespaced code in strings
Classes, constants, and functions referenced in a string MUST be fully qualified No namespace separator prefix is necessary
Example 1
namespace My; namespace My; // Assume My\Log\Logger is a defined class // Assume My\Log\Logger is a defined class $class = 'Log\Logger'; $class = 'Log\Logger'; $o = new $class; // E_FATAL; can't find $o = new $class; // E_FATAL; can't find // relative names // relative names $class = 'My\Log\Logger'; $class = 'My\Log\Logger'; $o = new $class; // Success $o = new $class; // Success $class = '\My\Log\Logger'; $class = '\My\Log\Logger'; $o = new $class; // Also success, $o = new $class; // Also success, // but not necessary // but not necessary
Example 2
namespace My; namespace My; // Assume My\Log\Logger is a defined class // Assume My\Log\Logger is a defined class $class = 'Log\Logger'; $class = 'Log\Logger'; if ($o instanceof $class) { } // Fails; can't if ($o instanceof $class) { } // Fails; can't // resolve class // resolve class $class = 'My\Log\Logger'; $class = 'My\Log\Logger'; if ($o instanceof $class) { } // Success if ($o instanceof $class) { } // Success
Why use namespaces?
Code Organization: Filesystem
Namespace separator has an affinity for the directory separator Suggests a 1:1 relationship with file system
namespace My\Log; namespace My\Log; class Logger {} class Logger {} /* My/Log/Logger.php (*nix) /* My/Log/Logger.php (*nix) My\Log\Logger.php (Windows) */ My\Log\Logger.php (Windows) */
Code Organization: By Responsibility
Interfaces
Use cases:

instanceof: $class instanceof Adapter implements: SomeClass implements Adapter
Natural language is easiest to understand Natural language suggests a hierarchy

namespace Translator\Adapter; namespace Translator\Adapter; use Translator\Adapter; use Translator\Adapter; class ConcreteAdapter implements Adapter class ConcreteAdapter implements Adapter {} {}
interface Translator\Adapter in
Translator/Adapter.php
class Translator\Adapter\ConcreteAdapter in
Translator/Adapter/ConcreteAdapter.php
Takeaway: we're referencing the capabilities, not the language type
Readability
When within a namespace, reference classes directly, keeping usage succinct

namespace Zend\Http; namespace Zend\Http; $client = new Client(); $client = new Client();
Readability
Importing and aliasing make names more succinct

namespace Application; namespace Application; use Zend\Http\Client as HttpClient, use Zend\Http\Client as HttpClient, Zend\Logger\Logger; Zend\Logger\Logger; $client = new HttpClient(); $client = new HttpClient(); $log = new Logger(); $log = new Logger();
Readability
Aliasing allows giving names context

namespace Application\Controller; namespace Application\Controller; use Zend\Controller\Action use Zend\Controller\Action as ActionController; as ActionController; class FooController class FooController extends ActionController {} extends ActionController {}
Dependency declarations
Suggestion: import every class outside the current namespace that you consume
namespace Application\Controller; namespace Application\Controller; use Zend\Controller\Action use Zend\Controller\Action as ActionController, as ActionController, My\ORM\Mapper as DataMapper, My\ORM\Mapper as DataMapper, My\Entity\BlogEntry, My\Entity\BlogEntry, Zend\EventManager\EventManager; Zend\EventManager\EventManager;
Imports are hints to the interpreter, and don't cost anything Helps to document dependencies up front Allows static analysis to determine dependencies
Resources
PHP Manual: http://php.net/namespace
k Z L j 'y O W w M u F f p m a N 3 5 H P g s U I , o c T n Z . d v e s t h g i r l A
? p s m a W I , T Z . d v s h g r A 2 l n o i t c e S
/ : f u g y w " ? p s m a W I , T Z . d v s h g r A 3 l n o i t c e S
Basically, a language-supported mechanism for grouping these language features, as well as a language-supported mechanism for avoiding naming conflicts.
s a B I , T Z . d v s h g r A 4 l n o i t c e S
Namespace Separator
\
Get over it!
There are a ton of reasons why the backslash was used, ranging from length of token to position of the token on most keyboards to previous use of other tokens to understanding the scope of a given operator/operation visually. Just use it, and move along.
What can live in namespaces
Classes Constants Functions
Single line declaration

namespace Zend; namespace Zend;
You _can_ declare multiple namespaces in the same file in this way, but it's not recommended
Block declaration
namespace Zend namespace Zend { { } } namespace Phly namespace Phly { { } }
This is the recommended way to declare multiple namespaces when in a single file.
Subnamespaces
Separate the subnamespaces using the namespace separator

namespace Zend\Log; namespace Zend\Log; namespace Zend\Log\Writer; namespace Zend\Log\Writer;
From non-namespaced code:

$class = new My\Registry(); $class = new My\Registry(); $class = new My\Log\Logger(); $class = new My\Log\Logger(); My\str_split($s); // function call My\str_split($s); // function call $val = My\APIKEY; // constant value $val = My\APIKEY; // constant value
From code using the same namespace:

namespace My; namespace My; $class = new Registry(); $class = new Registry(); $class = new Log\Logger(); $class = new Log\Logger(); str_split($s); // function call str_split($s); // function call $val = APIKEY; // constant value $val = APIKEY; // constant value
From code in a different namespace:

namespace Your; namespace Your; $class = new \My\Registry(); $class = new \My\Registry(); $class = new \My\Log\Logger(); $class = new \My\Log\Logger(); \My\str_split($s); // function call \My\str_split($s); // function call $val = \My\APIKEY; // constant value $val = \My\APIKEY; // constant value
Using namespaced code:
Prefixing with a namespace separator resolves as a fully qualified name Resolution order:

Globally qualified: known; otherwise: Current namespace, or relative to it (Classes, functions, constants) Global namespace (functions, constants)
classes outside the current namespace must be referenced using a fully (globally) qualified name, or _imported_.
This means:
You can override system functions within namespaces!

namespace My; namespace My; function str_split($string, $splitlen = 2) function str_split($string, $splitlen = 2) { { return preg_split('/\W/', $string, $splitlen); return preg_split('/\W/', $string, $splitlen); } } $a = str_split("Foo, Bar"); // invokes My\str_split() $a = str_split("Foo, Bar"); // invokes My\str_split() /* array ( /* array ( * * 0 => 'Foo', 0 => 'Foo', * * 1 => ' Bar', 1 => ' Bar', * ) * ) */ */
A way to bring code from another namespace into the current namespace. Import:

Classes Other namespaces
Keyword used is use
namespace My; namespace My; class Registry {} class Registry {} namespace Your; namespace Your; use My; // imports namespace use My; // imports namespace use My\Registry; // imports class use My\Registry; // imports class
Note: importing top-level namespaces in code with no namespace has no effect and results in a warning.
Using imported code

namespace Your; namespace Your; use My; // imports namespace use My; // imports namespace $r = new My\Registry(); $r = new My\Registry(); namespace Your; namespace Your; use My\Registry; // imports class use My\Registry; // imports class $r = new Registry(); $r = new Registry();
Aliasing
"import namespace or class, but refer to it using this name" PHP utilizes the as keyword to alias
Aliasing
namespace Your; namespace Your; use My as m; use My as m; $r = new m\Registry(); $r = new m\Registry(); namespace Your; namespace Your; use My\Registry as reg; use My\Registry as reg; $r = new reg(); $r = new reg();
Make typehinting more semantic!

namespace App; namespace App; use Zend\EventManager\EventManager as Events; use Zend\EventManager\EventManager as Events; class Foo class Foo { { public function events(Events $events = null) public function events(Events $events = null) { { if ($events instanceof Events) { if ($events instanceof Events) { $this->events = $events; $this->events = $events; } elseif (!$this->events instanceof Events) { } elseif (!$this->events instanceof Events) { $this->events = new Events(__CLASS__); $this->events = new Events(__CLASS__); } } return $this->events; return $this->events; } } } }
Multiple use statements

namespace Their; namespace Their; use My; use My; use Your; use Your;
Or use a comma (,) to separate statements

namespace Their; namespace Their; use My, use My, Your; Your;
With aliases
namespace Their; namespace Their; use My as m, // aliased use My as m, // aliased Your; // not aliased Your; // not aliased
What namespace are you in?
__NAMESPACE__
The setup:
namespace My\Package; namespace My\Package; const APIKEY = 1; const APIKEY = 1; function get($data) {} function get($data) {} class Service {} class Service {} namespace My\OtherPackage; namespace My\OtherPackage; const APIKEY = 2; const APIKEY = 2; function get($data) {} function get($data) {} class Service {} class Service {}
namespace Test; namespace Test; use My\Package\Service as PackageService, use My\Package\Service as PackageService, My\OtherPackage; My\OtherPackage; const APIKEY = 3; const APIKEY = 3; echo APIKEY; // 3 echo APIKEY; // 3 echo OtherPackage\APIKEY; // 2 echo OtherPackage\APIKEY; // 2 echo \My\Package\APIKEY; // 1 echo \My\Package\APIKEY; // 1 $s == new PackageService(); // My\Package\Service $s new PackageService(); // My\Package\Service $s == new Service(); // E_FATAL (no match) $s new Service(); // E_FATAL (no match) $s == new OtherPackage\Service(); $s new OtherPackage\Service(); // My\OtherPackage\Service // My\OtherPackage\Service get($baz); get($baz); // E_FATAL (no matching function in // E_FATAL (no matching function in // current namespace) // current namespace) OtherPackage\get($baz); // My\OtherPackage\get() OtherPackage\get($baz); // My\OtherPackage\get()
s a f P I , T Z . d v s h g r A 7 2 l n o i t c e S
Classes, constants, and functions referenced in a string MUST be fully qualified No namespace separator prefix is necessary
Example 1
namespace My; namespace My; // Assume My\Log\Logger is a defined class // Assume My\Log\Logger is a defined class $class = 'Log\Logger'; $class = 'Log\Logger'; $o = new $class; // E_FATAL; can't find $o = new $class; // E_FATAL; can't find // relative names // relative names $class = 'My\Log\Logger'; $class = 'My\Log\Logger'; $o = new $class; // Success $o = new $class; // Success $class = '\My\Log\Logger'; $class = '\My\Log\Logger'; $o = new $class; // Also success, $o = new $class; // Also success, // but not necessary // but not necessary
Example 2
namespace My; namespace My; // Assume My\Log\Logger is a defined class // Assume My\Log\Logger is a defined class $class = 'Log\Logger'; $class = 'Log\Logger'; if ($o instanceof $class) { } // Fails; can't if ($o instanceof $class) { } // Fails; can't // resolve class // resolve class $class = 'My\Log\Logger'; $class = 'My\Log\Logger'; if ($o instanceof $class) { } // Success if ($o instanceof $class) { } // Success
? p m a s u y W I , T Z . d v s h g r A 1 3 l n o i t c e S
Code Organization: Filesystem
Namespace separator has an affinity for the directory separator Suggests a 1:1 relationship with file system
namespace My\Log; namespace My\Log; class Logger {} class Logger {} /* My/Log/Logger.php (*nix) /* My/Log/Logger.php (*nix) My\Log\Logger.php (Windows) */ My\Log\Logger.php (Windows) */
Interfaces
Use cases:

instanceof: $class instanceof Adapter implements: SomeClass implements Adapter
Natural language is easiest to understand Natural language suggests a hierarchy

namespace Translator\Adapter; namespace Translator\Adapter; use Translator\Adapter; use Translator\Adapter; class ConcreteAdapter implements Adapter class ConcreteAdapter implements Adapter {} {}
interface Translator\Adapter in
Translator/Adapter.php
class Translator\Adapter\ConcreteAdapter in
Translator/Adapter/ConcreteAdapter.php
Takeaway: we're referencing the capabilities, not the language type
Readability
When within a namespace, reference classes directly, keeping usage succinct

namespace Zend\Http; namespace Zend\Http; $client = new Client(); $client = new Client();
Readability
Importing and aliasing make names more succinct

namespace Application; namespace Application; use Zend\Http\Client as HttpClient, use Zend\Http\Client as HttpClient, Zend\Logger\Logger; Zend\Logger\Logger; $client = new HttpClient(); $client = new HttpClient(); $log = new Logger(); $log = new Logger();
Readability
Aliasing allows giving names context

namespace Application\Controller; namespace Application\Controller; use Zend\Controller\Action use Zend\Controller\Action as ActionController; as ActionController; class FooController class FooController extends ActionController {} extends ActionController {}
Suggestion: import every class outside the current namespace that you consume
namespace Application\Controller; namespace Application\Controller; use Zend\Controller\Action use Zend\Controller\Action as ActionController, as ActionController, My\ORM\Mapper as DataMapper, My\ORM\Mapper as DataMapper, My\Entity\BlogEntry, My\Entity\BlogEntry, Zend\EventManager\EventManager; Zend\EventManager\EventManager;
Imports are hints to the interpreter, and don't cost anything Helps to document dependencies up front Allows static analysis to determine dependencies
u s R I , T Z . d v s h g r A 1 4 l n o i t c e S
Click to add title
PHP Manual: http://php.net/namespace

2011 03 02 Namespaces v2

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

2011 03 02 Namespaces v2

Încărcat de

Drepturi de autor:

Formate disponibile

Using PHP 5.

3 Namespaces for Fame and Fortune

All rights reserved. Zend Technologies, Inc.

What are namespaces?

All rights reserved. Zend Technologies, Inc.

What are namespaces?

All rights reserved. Zend Technologies, Inc.

All rights reserved. Zend Technologies, Inc.

What can live in namespaces

Classes Constants Functions

All rights reserved. Zend Technologies, Inc.

Single line declaration

All rights reserved. Zend Technologies, Inc.

All rights reserved. Zend Technologies, Inc.

Separate the subnamespaces using the namespace separator

All rights reserved. Zend Technologies, Inc.

Referring to namespaced elements

From non-namespaced code:

All rights reserved. Zend Technologies, Inc.

Referring to namespaced elements

From code using the same namespace:

All rights reserved. Zend Technologies, Inc.

Referring to namespaced elements

From code in a different namespace:

All rights reserved. Zend Technologies, Inc.

Using namespaced code:

All rights reserved. Zend Technologies, Inc.

You can override system functions within namespaces!

Classes Other namespaces

Keyword used is use

All rights reserved. Zend Technologies, Inc.

All rights reserved. Zend Technologies, Inc.

Using imported code

All rights reserved. Zend Technologies, Inc.

All rights reserved. Zend Technologies, Inc.

All rights reserved. Zend Technologies, Inc.

Make typehinting more semantic!

Importing multiple namespaces/classes

Multiple use statements

All rights reserved. Zend Technologies, Inc.

Importing multiple namespaces/classes

Or use a comma (,) to separate statements

All rights reserved. Zend Technologies, Inc.

Importing multiple namespaces/classes

All rights reserved. Zend Technologies, Inc.

What namespace are you in?

All rights reserved. Zend Technologies, Inc.

All rights reserved. Zend Technologies, Inc.

All rights reserved. Zend Technologies, Inc.

Referencing namespaced code in strings

All rights reserved. Zend Technologies, Inc.

Referencing namespaced code in strings

Referencing namespaced code in strings

All rights reserved. Zend Technologies, Inc.

Why use namespaces?

All rights reserved. Zend Technologies, Inc.

Code Organization: Filesystem

All rights reserved. Zend Technologies, Inc.

Code Organization: By Responsibility

instanceof: $class instanceof Adapter implements: SomeClass implements Adapter

Natural language is easiest to understand Natural language suggests a hierarchy

All rights reserved. Zend Technologies, Inc.