PHP OOP - Importing namespaces

Last revision:

Fully qualified names

PHP specifies that when you want to refer to classes, functions, and constants from another namespace (such as from other Drupal modules or third party libraries), you must use their fully qualified name.

In the following example we are working inside the MoonMission namespace, and we want to use a function from a different namespace, so we must use its fully qualified name:

Example 1

<?php
namespace MoonMission;

// Do some stuff.

// Start the rocket.
$ignition_status = \Nasa\SpaceTools\MoonRocket\ignite();
 
// Do more stuff.

We used the fully qualified name \Nasa\SpaceTools\MoonRocket\ignite() to refer to the ignite() function within the Nasa\SpaceTools\MoonRocket namespace (which we left out of the example for clarity).

Dealing with long namespaces

When the namespaces you're referring to are short, your code stays readable. However, often namespaces can get quite long, making your code more tedious to read and write than necessary.

Some examples of long namespaces in Drupal's source code:

  • Drupal\Core\Routing\Access\AccessInterface
  • Drupal\views\Plugin\views\display\EntityReference
  • Symfony\Component\HttpKernel\Exception\NotFoundHttpException

Imagine how much extra work it would be to have to type out full namespaces like \Symfony\Component\HttpKernel\Exception\NotFoundHttpException multiple times per code file.

A solution to dealing with long namespaces is importing them at the top of your code via the use statement. That way you only have to reference the namespace one time, and it will be available throughout your file.

But remember, while it's incredibly useful to import namespaces, and your framework's coding conventions may state that you must do so, from a technical point of view PHP does not require you to import namespaces. 

If you want to keep writing out full namespaces throughout your code, you can. It's not recommended, but you are allowed to.

Example 2

<?php
namespace MoonMission;

use Nasa\SpaceTools\MoonRocket;

// Do some stuff.

// Start the rocket.
$ignition_status = ignite();

// do more stuff.

This is much easier to read, and all the classes and functions within the Nasa\SpaceTools\MoonRocket namespace are now available without having to explicitly write out the full namespace each time.

Example 3

In the previous example we imported namespace \Nasa\SpaceTools\MoonRocket, which made the ignite() function directly available.

Alternatively, we could have chosen to import namespace \Nasa\SpaceTools, which would have made the ignite() function available via the partial namespace MoonRocket\ignite():

<?php
namespace MoonMission;

use Nasa\SpaceTools;

// Do some stuff.

// Start the rocket.
$ignition_status = Moonrocket\ignite();

// do more stuff.

Notice that we wrote :

Moonrocket\ignite();

and not:

\Moonrocket\ignite();

Moonrocket\ignite() does not start with a backslash, so it's a partial namespace that gets combined with the available namespaces: \Nasa\SpaceTools and \MoonMission to find the function \Nasa\SpaceTools\MoonRocket\ignite().

Had we written \Moonrocket\ignite() (with a leading backslash), PHP would have tried to find the ignite() function in namespace \MoonRocket, but that namespace does not exist on its own.

Importing namespaces: no leading backslash 

To import a namespace you must always provide the fully qualified namespace - in other words: the complete namespace. 

It is not possible to import partial namespaces.

As such, the leading backslash is unnecessary and not recommended as import names are not processed relative to the current namespace, but always relative to the global namespace.

In other words, the following two are valid, but only the first one is recommended:

// Valid, and recommended.
use Nasa\SpaceTools\MoonRocket;

// Also valid, but NOT recommended.
use \Nasa\SpaceTools\MoonRocket;

Namespace aliases

Going one step further, you can also give your own alternative name, or alias, to any namespace you import.

This can clarify your code or help you distinguish packages from each other if they provide functions or classes with the same name.

To provide an alias, use the keyword as, followed by your alias of choice:

use A\Long\Namespace\For\A\Thing as MyThing;

Example 4: an alias for clarity

In this example we provide the Rocket namespace alias so later on we can simply use Rocket to refer to the full namespace Nasa\SpaceTools\MoonRocket.

<?php

// No alias is used here.
namespace \Nasa\SpaceTools\MoonRocket;

function ignite() {
  print "Igniting...";
  return TRUE;
}

namespace MoonMission;

// Use alias.
use Nasa\SpaceTools\MoonRocket as Rocket;

// Start the rocket.
$status = Rocket\ignite();

Example 5: an alias to avoid naming conflicts

The following example imports two namespaces and gives an alias to each of them.

This makes the code easier to read/write, and avoids a naming conflict, as both namespaces contain a partial namespace named Rocket:

<?php
namespace MoonMission;

use Nasa\SaturnV\Rocket as SaturnRocket; 
use ESA\Ariane6\Rocket as ArianeRocket;

// Start both rockets.
$status_saturn = SaturnRocket\ignite();
$status_ariane = ArianeRocket\startInitialBurn();

Conclusion

You can provide aliases for the namespaces you import. You would typically do so for convenience and code clarity, or to avoid naming conflicts.

Note that we discussed aliases for namespaces in this unit. 

PHP also supports aliases for constants, functions, classes, interfaces, traits, and enums.

Summary

  • Import namespaces with the syntax use Fully\Qualified\Namespace.
  • Provide an alias with the syntax use Fully\Qualified\Namespace as my_alias.