Using Namespaces in PHP

Namespaces help to avoid naming collisions between libraries or other shared code. A namespace will encapsulate the codes (classes, functions, and constants) inside it so that they don’t conflict with items declared elsewhere.

Declaring and using namespaces
Declaring sub-namespaces

Global namespaces
Namespace aliases
Function and constant aliases

PHP declaring and using namespaces

To create a namespace in PHP, use the namespace keyword followed by the name. The namespace declaration must be the very first line after opening <?php tag:

<?php
 //File name: "a.php"
 namespace brainbell;

 function hello() {
  return 'Hi, namespace: '.__NAMESPACE__;
 }

Once the namespace declared at the top of a PHP file, all code within that file belongs to that namespace. In the above example, the hello() function belongs to the brainbell namespace.

To use a class, function or constant that was declared in the same namespace, just write its name as usual:

<?php
 namespace brainbell;
 require 'a.php';
 echo hello();
 # Prints: Hi, namespace: brainbell

To use a namespaced class, function or constant from outside a namespace, write the namespace name, followed by a backslash \, followed by the class, function or constant name:

<?php
 /*File name: "example.php", namespace not defined in this file*/

 require 'a.php';
 echo \brainbell\hello();
 # Prints: Hi, namespace: brainbell

In the following example, the example.php and a.php files contain functions with the same name hello(). By default, a fatal error occurred when you include a PHP file that already contains the same function name, but using namespaces you can avoid naming collisions:

<?php
 //File name: "example.php"
 require 'a.php';
 function hello() {
  return 'Hi, no namespace defined';
 }
 echo hello();
 # Prints: Hi, no namespace defined

 echo \brainbell\hello();
 # Prints: Hi, namespace: brainbell

It is also possible to have two or more namespaces in a file by wrapping the code for the namespace in braces (not recommended):

<?php
 namespace first {
  // ...
 }

 namespace second {
  // ...
 }

 namespace {
  // the global namespace
 }

PHP sub-namespaces

You can also create sub-namespaces, much like sub-folders (or sub-directories) in a file system. This allows you to create a namespace hierarchy. You separate each namespace level with a backslash \ character:

<?php
 namespace brainbell\template

The above code declares the template namespace inside the brainbell namespace. Let’s declare the same name function hello() inside the sub-namespaced file and save it as b.php.

<?php
 //File name: "b.php"
 namespace brainbell\template;

 function hello() {
  return 'Hi, namespace: '.__NAMESPACE__;
 }

Next, edit the example.php (which we’ve already created in the previous example) and include the b.php file. Now you can see that all files a.php, b.php and example.php declared the hello() function but they not clashing with each other nor generating any error because they are all in different namespaces:

<?php
 //File name: "example.php"

 require 'a.php'; # namespace: brainbell
 require 'b.php'; # namespace: brainbell\template

 function hello() {
  return 'Hi, no namespace defined';
 }
 
 echo hello() . '<br>';
 # Prints: Hi, no namespace defined

 echo \brainbell\hello() . '<br>';
 # Prints: Hi, namespace: brainbell
 
 echo \brainbell\template\hello();
 # Prints: Hi, namespace: brainbell\template

You can specify namespaces using relative notation, much like working with relative paths:

<?php
 namespace brainbell;
 require 'b.php'; # namespace: \brainbell\template

 # Using the relative name
 echo template\hello();

 # Using the fully qualified name
 echo \brainbell\template\hello();

PHP global namespace

If the namespace keyword is not declared at the top of a PHP file, it belongs to the global namespace. For example:

<?php
 //File name: "no_namespace_defined.php"
 function hello() {
  return 'Global namespace, no namespace defined';
 }

You can reference globally namespaced code inside another namespace by prepending the \ character to the class, function, or constant name:

<?php
 //File name: "a.php"
 namespace brainbell;
 require 'no_namespace_defined.php'; # global namespace

 function hello() {
  return 'Hi, namespace: '.__NAMESPACE__;
 }

 echo \hello();
 # Prints: Global namespace, no namespace defined

In the above example, we’ve called the hello() function that exists in the global namespace.

PHP namespace aliases

If you’re working with a big namespace hierarchy, specifying the full namespace name each time can get tiresome:

<?php
require 'uses_long_namespace.php';
$o = brainbell\template\db\views\hello();

To get around this problem, you can use a namespace alias, which works much like a symbolic link in UNIX file systems. To create an alias you write: use namespace as alias;.

Once you’ve created an alias, you can use it in place of the full namespace name:

<?php
 require 'uses_long_namespace.php';
 use brainbell\template\db\views as dbviews;
 $o = new dbviews\DbClass();

You can leave out the as statement (and the name that follows), in which case the use statement uses the last portion of the namespace name as the alias. So the following two lines of code are equivalent:

use brainbell\template\db\views as views;
use brainbell\template\db\views;

The modified example:

<?php
 require 'uses_long_namespace.php';
 use brainbell\template\db\views;
 $o = new views\DbClass();

Function and constant aliases

You can use the use keyword to import or alias a function, see the following syntax:

<?php
 require 'b.php';
 use function \brainbell\template\hello as BThello;
 
 echo BThello();
 # Prints: Hi, namespace: brainbell\template

Similarly, you can also alias a constant (if declared with the const keyword and not with define()):

<?php
 require 'file_contains_const.php';
 use const name\space\constName as newConst;
 echo 'Value of newConst: ' . newConst;

Summary

Namespaces help you avoid naming collisions between libraries or other shared code.
As well as functions, you can also use namespaces with classes and constants (but you must declare them with the const keyword and not with define()).

It is possible to have more than one namespace in a file, but it is not recommended.
When you are working in a namespace, then the PHP will assume that names are relative to the current namespace.

PHP OOP Tutorials: