PHP RFC: Namespaces in bundled PHP extensions
- Date: 2021-02-25
- Author: Nikita Popov email@example.com
- Status: Accepted
- Target Version: PHP 8.1
Classes and functions provided by bundled PHP extensions are currently all located in the global namespace (with one exception). There is a strong sentiment that future additions to PHP's standard library should make use of namespaces, to the point that otherwise unrelated proposals increasingly degenerate into namespace-related discussions. This question needs to be resolved one way or another, to avoid reiterating it for every future addition to the standard library.
PHP extension classification
All symbols (classes, functions, constants) provided by PHP are part of an extension. Extensions can be classified into three categories:
- Required extensions (including Core and standard). These extensions are always present, and PHP cannot be built without them.
- Bundled extensions (including ctype and mbstring). These extensions are part of the php-src distribution, but PHP can be built without them. Bundled extensions can be either enabled or disabled by default.
- 3rd-party extensions (including apcu and igbinary). These extensions are not part of the php-src distribution, and either available through PECL, or simply on GitHub.
Extensions may move between these three categories over time. hash and json recently moved from “bundled” to “required” (though I believe extensions never move out of the “required” category). sodium and ffi moved from 3rd-party to bundled. xmlrpc and wddx moved from bundled to 3rd-party.
Most userland open-source libraries nowadays follow a namespace structure of the form
VendorNamespace\PackageNamespace\Symbol, with all names being at least two levels deep. PSR-4 itself only requires a top-level namespace and permits symbols of the form
The concept of a vendor namespace is hard to reconcile with the extension classification discussed in the previous section, as extensions may move between different “vendors”. It is educative to consider the issues that a
PHP\Component\Symbol name structure would encounter, which was assumed by many prior RFCs and discussions.
3rd-party extensions clearly cannot start out under a
PHP namespace, as they have no direct relation to, endorsement by, or oversight of the PHP project. If all symbols in bundled extensions are to be prefixed by
PHP, this would require a rename of all symbols when an extension moves from 3rd-party to bundled. While compatibility shims can somewhat mitigate this, such a rename constitutes an unnecessary disruption to all existing users of the extension, as well as any documentation relating to it.
Conversely, if a bundled extension is removed from PHP, the question arises whether it should be moved out of the
PHP namespace. Extensions are typically unbundled from PHP if they are unmaintained. Retaining them under the
PHP namespace may create the mistaken impression that the PHP project still maintains such extensions. Of course, changing the vendor prefix on unbundling would once again disrupt any remaining users.
The PHP Namespace Policy RFC sought to address this by introducing two vendor namespaces for extensions:
Ext. The latter may be used by all extensions, whether they be bundled or 3rd-party. The
PHP namespace would only be eligible for bundled functionality directly tied to PHP, such as built-in attributes, altough the exact dividing line is unclear. Most symbols would be part of the
Ext vendor namespace.
PHP itself only bundles a single extension with namespaced symbols (ffi). However, there are a number of 3rd-party extensions making use of namespaces. For extensions present in phpstorm-stubs, the following list summarizes in what way they utilize namespaces:
FFI\CType. Also uses
Aerospike\Bytes. Also uses
Cassandra\Table. Also uses
RdKafka\Producer. Also uses
RdKafkaitself, and a handful of
Yaf\Application. Also supports aliases in the global namespace, e.g.
Zstd\compress(). However, it also declares
zstd_*()functions in the global namespace.
It is notable that with the exception of
xlswriter, none of these extensions make use of a vendor namespace. They all use the package/extension name as the top-level namespace. Some extensions additionally have a global class that matches the extension name, e.g. the ffi extension uses both
This RFC proposes to explicitly allow and encourage the use of namespaces for bundled PHP extensions, subject to the guidelines laid out in the following.
- Extensions should not use a vendor namespace.
- The top-level namespace should match the extension name (apart from casing).
- Namespace names should follow
- All symbols defined in the extension should be part of the extension's top-level namespace or a sub-namespace.
If we were to introduce
openssl as a new namespaced extension, here is how the symbol names could change in line with these guidelines:
The above guidelines recommend against the global
FFI class used by the ffi extension. Using
FFI\FFI would be preferred.
Core, standard, spl
PHP has three extensions that together form the core of the standard library. The “Core” extension is part of the Zend Engine, and defines a relatively small number of functions and classes. It contains core types like
Iterator, as well as introspection functions like
get_object_vars(). The “standard” extension contains the majority of the standard library functions, including
str_*() functions. The “spl” extension was historically the “object-oriented” part of the standard library, containing data-structures like
ArrayObject, exceptions and iterators.
The distinction between these three extensions is somewhat murky from an end-user perspective, and largely historical. Symbols have moved between these extensions, e.g. the
Iterator interface originated in spl, but now lives in Core.
Because these extensions combine a lot of unrelated or only tangentially related functionality, symbols should not be namespaced under the
Spl namespaces. Instead, these extensions should be considered as a collection of different components, and should be namespaced according to these.
str_contains() could become
fopen() could become
password_hash() could become
Password\hash(). (These are non-normative examples, the RFC does not propose using these specific namespaces.)
Existing non-namespaces symbols and consistency
When adding new symbols to existing extensions, it is more important to be consistent with existing symbols than to follow the namespacing guidelines.
For example, the
array_is_list() function added in PHP 8.1 should indeed be called
array_is_list() and should not be introduced as
Array\is_list() or similar. Unless and until existing
array_*() functions are aliased under an
Array\* namespace, new additions should continue to be of the form
array_*() to maintain horizontal consistency.
This is a somewhat loose guideline, and applies more strongly to functions than classes. In particular, when new object-oriented elements are introduced into an extension that has historically been procedural, these may be namespaced. For example, if
OpenSSLCertificate had only been introduced in PHP 8.1, it should have been named
For the Core/standard/spl extensions, the previous considerations on component subdivision apply. The fact that string and array functions are not namespaced does not preclude new namespaced components in these extensions.
The disadvantage of not using a vendor namespace is that namespace collisions are more likely. A mitigating factor is the pervasive use of vendor namespaces in the userland ecosystem (in which case the collision would have to be between a vendor namespace and a component namespace, which is less likely).
As a matter of courtesy, top-level namespaces used by extensions should avoid collisions with existing, commonly used open-source libraries or extensions (or happen with the agreement of the parties involved). This RFC does not try to provide a hard guideline on what constitutes a sufficiently important library. The application of common sense is recommended.
Backward Incompatible Changes
This RFC only officially allows use of namespaces, and provides basic guidelines for their use. However, it does not propose to migrate already existing non-namespaced symbols to use namespaces. Such a migration should be the subject of a separate RFC.
Voting started 2021-04-19 and ended 2021-05-03.