PHP RFC: Namespaces in bundled PHP extensions

• Date: 2021-02-25
• Author: Nikita Popov nikic@php.net
• 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.

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 TopLevelNamespace\Symbol.

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: PHP and 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 (bundled): Uses FFI namespace, e.g. FFI\CType. Also uses FFI itself.
• aerospike: Uses Aerospike namespace, e.g. Aerospike\Bytes. Also uses Aerospike itself.
• cassandra: Uses Cassandra namespace, e.g. Cassandra\Table. Also uses Cassandra itself.
• couchbase: Uses Couchbase namespace, e.g. Couchbase\Document.
• crypto: Uses Crypto namespace, e.g. Crypto\PBKDF2.
• decimal: Uses Decimal namespace, e.g. Decimal\Decimal.
• ds: Uses Ds namespace, e.g. Ds\Collection.
• grpc: Uses Grpc namespace, e.g. Grpc\Server.
• http: Uses http namespace, e.g. http\Client.
• mongodb: Uses MongoDB namespace, e.g. MongoDB\Driver\Manager.
• mosquitto: Uses Mosquitto namespace, e.g. Mosquitto\Client.
• mysql_xdevapi: Uses mysql_xdevapi namespace, e.g. mysql_xdevapi\Collection.
• parallel: Uses parallel namespace, e.g. parallel\Runtime.
• parle: Uses Parle namespace, e.g. Parle\Lexer.
• pcov: Uses pcov namespace, e.g. pcov\start().
• pq: Uses pq namespace, e.g. pq\Connection.
• rdkafka: Uses RdKafka namespace, e.g. RdKafka\Producer. Also uses RdKafka itself, and a handful of rd_kafka_*() functions.
• xlswriter: Uses Vtiful\Kernel namespace, e.g. Vtiful\Kernel\Excel.
• yaf: Uses Yaf namespace, e.g. Yaf\Application. Also supports aliases in the global namespace, e.g. Yaf_Application.
• zstd: Uses Zstd 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 FFI and FFI\CType.

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 CamelCase.
• 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:

• OpenSSLCertificate becomes OpenSSL\Certificate
• openssl_dh_compute_key() becomes OpenSSL\dh_compute_key()
• X509_PURPOSE_SSL_CLIENT becomes OpenSSL\X509_PURPOSE_SSL_CLIENT

The above guidelines recommend against the global FFI class used by the ffi extension. Using FFI\FFI would be preferred.

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 stdClass and Iterator, as well as introspection functions like get_object_vars(). The “standard” extension contains the majority of the standard library functions, including array_*() and 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 Core, Standard or Spl namespaces. Instead, these extensions should be considered as a collection of different components, and should be namespaced according to these.

For example, str_contains() could become Str\contains(), fopen() could become File\open(), and password_hash() could become Password\hash(). (These are non-normative examples, the RFC does not propose using these specific namespaces.)

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 OpenSSL\Certificate.

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.

None.

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.

Allow use of namespaces in line with these guidelines?
Real name	Yes	No
alcaeus (alcaeus)
alec (alec)
asgrim (asgrim)
ashnazg (ashnazg)
brzuchal (brzuchal)
carusogabriel (carusogabriel)
cmb (cmb)
crell (crell)
daverandom (daverandom)
derick (derick)
dharman (dharman)
galvao (galvao)
girgias (girgias)
heiglandreas (heiglandreas)
ilutov (ilutov)
imsop (imsop)
kalle (kalle)
kguest (kguest)
kinncj (kinncj)
kocsismate (kocsismate)
lcobucci (lcobucci)
levim (levim)
lufei (lufei)
marandall (marandall)
mcmic (mcmic)
nicolasgrekas (nicolasgrekas)
nikic (nikic)
ocramius (ocramius)
patrickallaert (patrickallaert)
sammyk (sammyk)
santiagolizardo (santiagolizardo)
sebastian (sebastian)
seld (seld)
sergey (sergey)
svpernova09 (svpernova09)
tandre (tandre)
theodorejb (theodorejb)
trowski (trowski)
Final result:	37	1
This poll has been closed.