PHP's new convention on using namespaces for extensions

Published On2021-05-06

Namespace in PHP bundled extensions

A recent RFC to add namespaces to PHP bundled extensions passed, and it will be applied to upcoming PHP versions, starting from PHP 8.1.

With this new change, PHP classes, interfaces, traits, functions and enums, otherwise called as symbols, will be prefixed with the name of the extension. This helps reduce the possible conflicts with other extensions and third-party PHP code.

For example, both IMAP and FTP extensions provide a PHP class for an IMAP/FTP connection. With this new namespace adoption, these classes are named IMAP\Connection and FTP\Connection. In contrast to \IMAPConnection and FTPConnection, the IMAP\ and FTP\ namespaces help keep the symbols contained within that namespace.


PHP's source repository includes several PHP extensions.

"Required" extensions are core PHP extensions that are always available, and PHP cannot be compiled without them. For example, Date, Hash, and SPL extensions are considered require extensions. A complete list of all PHP required extensions are available at Compile PHP: Core extensions. The new practice does not apply to these extensions. At this proposal, required extensions will not be namespaced.

Bundled extensions are the ones that can be enabled/disabled at the time of compilation. There are over 30 bundled extensions, including IMAP, FTP, PDO, and OpenSSL to name a few. This new convention proposes these extensions to be namespaced. A list of PHP's bundled extensions are available at Compile PHP: Extensions enabled by default and disabled by default

Third-party extensions such as Xdebug, PCOV, and other PECL extensions are not affected by this convention either, and it will be up to the extension maintainers to decide on the namespaces.

The new practice only affects bundled extensions such as IMAP, FTP, OpenSSL, etc. There are no particular changes proposed at this time for core extensions and third-party extensions (PECL, commercial, or other extensions).

Previous Attempts

This is not the first RFC that proposed to adopt a namespacing policy.

An RFC named Namespaces in Core created in 2017 proposed to add namespaces for the PHP core, and more discussions to decide a naming pattern. This proposal was not well-received, and was withdrawn.

Last year, an RFC named PHP Namespace in core also proposed to add a namespace for PHP core, to avoid possible conflicts with user-land PHP code as PHP evolves. This RFC advanced to a vote, but it did not pass.

The RFC that brought this convention did not try to introduce any changes to the PHP core, but only to the bundled extensions at the time. It does not rule-out the possibility of adding namespaces to the PHP core symbols, but this is a good start and a small and rather less invasive change, that was accepted by the community.

Namespace Convention

The new adopted convention proposes to not use a vendor name in the namespace.

This convention is different from Composer package, where most of the packages and their symbols are namespaced by the vendor name and the package name. For example, classes in the Composer package doctrine/dbal has the vendor's name Doctrine, followed by the package name DBAL, and all classes from that package reside in the Doctrine/DBAL namespace.

Namespace in Doctrine/DBAL package
The new convention suggests to use the extension name itself as the namespace, and to not use any vendor namespace. Following this convention, \IMAPConnection class will be moved as \IMAP\Connection, and not \PHP\IMAP\Connection.

Namespace in IMAP PHP extension
Some examples:

  • \IMAPConnection moved to \IMAP\Connection
  • \FTPConnection moved to \FTP\Connection
  • \LDAPResult moved to \LDAP\Result

A class provided by a bundled extension that has the same name as the extension itself will be moved to the extension namespace, followed by the same name.

For example, LDAP class from the LDAP extension shall be moved to \LDAP\LDAP.

Backwards Compatibility

There are no immediate plans to retrospectively add namespaces to existing symbols in released PHP versions.

Proposed changes to the upcoming PHP 8.1 will contain some of these changes. The first change as per this new convention already took place for the IMAP extension. As part of PHP's resource to object migration, PHP 8.1 was to bring a new \IMAPConnection class. Following the acceptance of the RFC to bring namespaces to bundled extensions, this class was renamed to \IMAP\Connection.

Future Scope

PHP's global namespace is polluted as-is, with several array_* functions, str_ functions, mb_* functions, file_* functions, Spl* classes, etc. already co-existing in the global namespace.

Some of the potential improvements:

  • str_contains\Str\contains
  • file_open\File\open
  • SplFixedArray\SPL\FixedArray

There are no immediate proposals to move PHP core symbols to their own logical namespaces, although ideally PHP does eventually, at the cost of backwards-compatibility or somewhat unmanageable aliased functions.

Recent Articles on PHP.Watch

All ArticlesFeed
Writing better Regular Expressions in PHP

Writing better Regular Expressions in PHP

How to write more readable, self-explanatory, and effective regular expressions in PHP.
How to compile PHP from source on Debian/Ubuntu - Beginner's guide

How to compile PHP from source on Debian/Ubuntu - Beginner's guide

Beginner's guide to compile PHP from the source, on Ubuntu/Debian with up to date instructions for PHP 8 and up.
Function Inlining in Zend Engine

Function Inlining in Zend Engine

A list of special PHP functions that Zend Engine can inline and optimize.
Subscribe to PHP.Watch newsletter for monthly updates

You will receive an email on last Wednesday of every month and on major PHP releases with new articles related to PHP, upcoming changes, new features and what's changing in the language. No marketing emails, no selling of your contacts, no click-tracking, and one-click instant unsubscribe from any email you receive.