How to use PHP namespaces

→ Are you a new visitor? Please visit the page guidance for new visitors ←

PHP namespaces

Before we dig in into namespaces, we have to understand what they are, and how they are used. A simple analogy can be made between PHP namespaces and a filesystem. They work quite the same and apply the same principle.

Imagine the following directory structure:

Everything clear. You have a “foo.txt” file in the /myLocalSpace/home and a “bar.txt” in the /myLocalSpace/work. Namespaces work in a very similar way. A namespace definition is the first statement the PHP interpreter should encounter in a PHP file. The only statement allowed to occur above a namespace declaration is a declare statement.

Why namespaces?

Let’s assume that you have a project with thirty or more classes defined. The website is working fine, but you want to include another php library in your project for some functionality and you end up realising that one or more classes use the same name as the ones in the library. What happens then? A conflict with the same name for class declaration occurred.

Defining Namespaces

Declaring a namespace is as simple as using the namespace keyword. A namespace must start with a letter or underscore, followed by any number of letters, numbers or underscores.

Keep in mind that you are allowed also to have multiple namespaces in the same file.

The “use” keyword

The “use” statement is the keyword that will be used to say you want to use the specified namespace. For example if we want to call our newly created namespace, we use it like this:

You can see the use keyword telling the PHP parser to use the myLocalSpace namespace. You should also notice that there is the “as” keyword too. Using a namespace will not work if you don’t define the new name for the namespace.

Calling functions from the namespace

There are some ways to call a function from an existing namespace.

  • Unqualified name
  • Qualified name
  • Fully qualified name

Unqualified name

Unqualified name, resolves to the namespace you are currently in. In our example it is referring to the “myLocalSpace” namespace.

Qualified name

This is how you access the sub-namespace hierarchy. This method uses the backslash notation. Qualified name, instantiating a class from a sub-namespace of myProject. Let’s see the below example:

Fully qualified name

The unqualified and qualified names are both relative to the namespace you are currently in. They can only be used to access definitions on that level or to go deeper into the namespace declarations. If you want to access a function, class or constant that is placed at a higher level in the hierarchy, then you need to use the fully qualified name. That is an absolute path rather than a relative one.

 The __NAMESPACE__ constant

Like other constants from php (__CLASS__, __METHOD__, etc) that return the class or the method that you are in, we have this “__NAMESPACE__” constant also that returns the namespace name that you are in.

Conclusion

Namespaces were long awaited in php, and they are available in versions that are newer or equal with 5.3.0. They are great tools  to avoid conflicts in class names declarations for example. You are not forced to use them but once you master them, you step into another level of programming.

Request an article ←