diff --git a/coding-standards-and-naming.rst b/coding-standards-and-naming.rst index 278ad93..f0d38e6 100644 --- a/coding-standards-and-naming.rst +++ b/coding-standards-and-naming.rst @@ -1,375 +1,452 @@ -================================== -Coding Standards and Naming Policy -================================== +#################################### + Coding Standards and Naming Policy +#################################### -Classes -======= +********* + Classes +********* From: `Class Naming RFC `_ -**Editor’s note: Parts of this RFC have been superseded by the “Casing of acronyms in class and method names” section** +**Editor’s note: Parts of this RFC have been superseded by the “Casing +of acronyms in class and method names” section** -The PHP coding standard does not cover how class names should be written. This -leads to friction within the userland community that is now largely following -the `standard recommendation PSR-1 `_. +The PHP coding standard does not cover how class names should be +written. This leads to friction within the userland community that is +now largely following the `standard recommendation PSR-1 +`_. -Extending our current coding standard to cover edge cases about abbreviations -and acronyms/initialisms would resolve any future discussion. +Extending our current coding standard to cover edge cases about +abbreviations and acronyms/initialisms would resolve any future +discussion. Proposal --------- +======== Extend the coding standard to explicitly specify how abbreviations and -acronyms/initialisms are to be handled when writing user-level class names. -The current rule is:: - - Classes should be given descriptive names. Avoid using abbreviations where - possible. Each word in the class name should start with a capital letter, - without underscore delimiters (CamelCaps starting with a capital letter). - The class name should be prefixed with the name of the 'parent set' (e.g. - the name of the extension):: - - Good: - 'Curl' - 'FooBar' - - Bad: - 'foobar' - 'foo_bar' - -— `CODING_STANDARDS `_. - -While it is stated that abbreviations should be avoided, it is silent on what -to do if they are used; especially in the case of acronyms/initialisms. There -are essentially three choices possible now: - -- **PascalCase except Acronyms/Initialisms** — which is how the majority of - user-level class names are written, and it matches the approach of many - other programming languages. -- **Always PascalCase** — which is basically what - `PSR-1 `_ defines, however, it would - make most of the currently existing user-level class names invalid. -- **Do Nothing** — which of course automatically means that any approach is - allowed, and the community discussions around this topic will continue. - -**IMPORTANT!**: Regardless of the outcome of this RFC, existing user-level -class names are not required to be changed. Although it would be possible -(class names are case-insensitive). The reason why renaming is not proposed is -simple: this RFC would most probably fail because too many people are against -such purely cosmetic changes. +acronyms/initialisms are to be handled when writing user-level class +names. The current rule is: + +.. code:: + + Classes should be given descriptive names. Avoid using abbreviations where + possible. Each word in the class name should start with a capital letter, + without underscore delimiters (CamelCaps starting with a capital letter). + The class name should be prefixed with the name of the 'parent set' (e.g. + the name of the extension):: + + Good: + 'Curl' + 'FooBar' + + Bad: + 'foobar' + 'foo_bar' + +— `CODING_STANDARDS +`_. + +While it is stated that abbreviations should be avoided, it is silent on +what to do if they are used; especially in the case of +acronyms/initialisms. There are essentially three choices possible now: + +- **PascalCase except Acronyms/Initialisms** — which is how the + majority of user-level class names are written, and it matches the + approach of many other programming languages. + +- **Always PascalCase** — which is basically what `PSR-1 + `_ defines, however, it would make + most of the currently existing user-level class names invalid. + +- **Do Nothing** — which of course automatically means that any + approach is allowed, and the community discussions around this topic + will continue. + +**IMPORTANT!**: Regardless of the outcome of this RFC, existing +user-level class names are not required to be changed. Although it would +be possible (class names are case-insensitive). The reason why renaming +is not proposed is simple: this RFC would most probably fail because too +many people are against such purely cosmetic changes. PascalCase except Acronyms/Initialisms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------- -**Editor’s note: This section has been superseded by the “Casing of acronyms in class and method names” section** +**Editor’s note: This section has been superseded by the “Casing of +acronyms in class and method names” section** Class names should be descriptive nouns in PascalCase and as short as -possible. Each word in the class name should start with a capital letter, -without underscore delimiters. The class name should be prefixed with the name -of the "parent set" (e.g. the name of the extension) if no namespaces are -used. Abbreviations and acronyms as well as initialisms should be avoided -wherever possible, unless they are much more widely used than the long form -(e.g. HTTP or URL). Abbreviations start with a capital letter followed by -lowercase letters, whereas acronyms and initialisms are written according to -their standard notation. Usage of acronyms and initialisms is not allowed if -they are not widely adopted and recognized as such. +possible. Each word in the class name should start with a capital +letter, without underscore delimiters. The class name should be prefixed +with the name of the "parent set" (e.g. the name of the extension) if no +namespaces are used. Abbreviations and acronyms as well as initialisms +should be avoided wherever possible, unless they are much more widely +used than the long form (e.g. HTTP or URL). Abbreviations start with a +capital letter followed by lowercase letters, whereas acronyms and +initialisms are written according to their standard notation. Usage of +acronyms and initialisms is not allowed if they are not widely adopted +and recognized as such. Good: -- ``Curl`` -- ``CurlResponse`` -- ``HTTPStatusCode`` -- ``URL`` -- ``BTreeMap`` (B-tree Map) -- ``Id`` (Identifier) -- ``ID`` (Identity Document) -- ``Char`` (Character) -- ``Intl`` (Internationalization) -- ``Radar`` (Radio Detecting and Ranging) +- ``Curl`` +- ``CurlResponse`` +- ``HTTPStatusCode`` +- ``URL`` +- ``BTreeMap`` (B-tree Map) +- ``Id`` (Identifier) +- ``ID`` (Identity Document) +- ``Char`` (Character) +- ``Intl`` (Internationalization) +- ``Radar`` (Radio Detecting and Ranging) Bad: -- ``curl`` -- ``curl_response`` -- ``HttpStatusCode`` -- ``Url`` -- ``BtreeMap`` -- ``ID`` (Identifier) -- ``CHAR`` -- ``INTL`` -- ``RADAR`` (Radio Detecting and Ranging) +- ``curl`` +- ``curl_response`` +- ``HttpStatusCode`` +- ``Url`` +- ``BtreeMap`` +- ``ID`` (Identifier) +- ``CHAR`` +- ``INTL`` +- ``RADAR`` (Radio Detecting and Ranging) -Casing of acronyms in class and method names -============================================ +********************************************** + Casing of acronyms in class and method names +********************************************** -From: `Casing of acronyms in class and method names RFC `_ +From: `Casing of acronyms in class and method names RFC +`_ -The class naming policy should be updated to the following, with changes highlighted: +The class naming policy should be updated to the following, with changes +highlighted: -Method names follow the studlyCaps (also referred to as bumpy case or camel caps) naming convention, with care taken to minimize the letter count. The initial letter of the name is lowercase, and each letter that starts a new word is capitalized. +Method names follow the studlyCaps (also referred to as bumpy case or +camel caps) naming convention, with care taken to minimize the letter +count. The initial letter of the name is lowercase, and each letter that +starts a new word is capitalized. -Class names should be descriptive nouns in PascalCase and as short as possible. Each word in the class name should start with a capital letter, without underscore delimiters. The class name should be prefixed with the name of the "parent set" (e.g. the name of the extension) if no namespaces are used. +Class names should be descriptive nouns in PascalCase and as short as +possible. Each word in the class name should start with a capital +letter, without underscore delimiters. The class name should be prefixed +with the name of the "parent set" (e.g. the name of the extension) if no +namespaces are used. -Abbreviations and acronyms as well as initialisms should be avoided wherever possible, unless they are much more widely used than the long form (e.g. HTTP or URL). +Abbreviations and acronyms as well as initialisms should be avoided +wherever possible, unless they are much more widely used than the long +form (e.g. HTTP or URL). .. raw:: html Abbreviations start with a capital letter followed by lowercase letters, whereas acronyms and initialisms are written according to their standard notation. -**Abbreviations, acronyms, and initialisms should be treated like regular words, thus they should be written with an uppercase first character, followed by lowercase characters.** +**Abbreviations, acronyms, and initialisms should be treated like +regular words, thus they should be written with an uppercase first +character, followed by lowercase characters.** .. raw:: html Usage of acronyms and initialisms is not allowed if they are not widely adopted and recognized as such. -**Diverging from this policy is allowed to keep internal consistency within a single extension, if the name follows an established, language-agnostic standard, or for other reasons, if those reasons are properly justified and voted on as part of the RFC process.** +**Diverging from this policy is allowed to keep internal consistency +within a single extension, if the name follows an established, +language-agnostic standard, or for other reasons, if those reasons are +properly justified and voted on as part of the RFC process.** Examples --------- +======== Good method names: -- ``connect()`` -- ``getData()`` -- ``buildSomeWidget()`` -- ``performHttpRequest()`` +- ``connect()`` +- ``getData()`` +- ``buildSomeWidget()`` +- ``performHttpRequest()`` Bad method names: -- ``get_Data()`` -- ``buildsomewidget()`` -- ``getI()`` -- ``performHTTPRequest()`` +- ``get_Data()`` +- ``buildsomewidget()`` +- ``getI()`` +- ``performHTTPRequest()`` Good class names: -- ``Curl`` -- ``CurlResponse`` -- ``HttpStatusCode`` -- ``Url`` -- ``BtreeMap`` (B-tree Map) -- ``UserId`` (User Identifier) -- ``Char`` (Character) -- ``Intl`` (Internationalization) -- ``Ssl\Certificate`` -- ``Ssl\Crl`` (Certificate Revocation List) -- ``Ssl\CrlUrl`` +- ``Curl`` +- ``CurlResponse`` +- ``HttpStatusCode`` +- ``Url`` +- ``BtreeMap`` (B-tree Map) +- ``UserId`` (User Identifier) +- ``Char`` (Character) +- ``Intl`` (Internationalization) +- ``Ssl\Certificate`` +- ``Ssl\Crl`` (Certificate Revocation List) +- ``Ssl\CrlUrl`` Bad class names: -- ``curl`` -- ``curl_response`` -- ``HTTPStatusCode`` -- ``URL`` -- ``BTreeMap`` -- ``UserID`` (User Identifier) -- ``CHAR`` -- ``INTL`` -- ``SSL\Certificate`` -- ``SSL\CRL`` -- ``SSL\CRLURL`` - -Namespaces in Extensions -======================== +- ``curl`` +- ``curl_response`` +- ``HTTPStatusCode`` +- ``URL`` +- ``BTreeMap`` +- ``UserID`` (User Identifier) +- ``CHAR`` +- ``INTL`` +- ``SSL\Certificate`` +- ``SSL\CRL`` +- ``SSL\CRLURL`` + +************************** + Namespaces in Extensions +************************** From `Namespaces in Bundled Extensions RFC `_. -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. +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. -All symbols (classes, functions, constants) provided by PHP are part of an -extension. Extensions can be classified into three categories: +- 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. -- 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. +- 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. +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. Vendor Namespace ----------------- - -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 (declined) 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. +================ + +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 (declined) 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. Existing practice ------------------ - -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. +================= + +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``. +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``. Proposal --------- +======== -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: +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. +- 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. Examples -~~~~~~~~ +-------- -If we were to introduce ``openssl`` as a new namespaced extension, here is how -the symbol names could change in line with these guidelines: +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`` +- ``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. +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 -``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. +------------------- + +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. +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. +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.) +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.) 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. +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 +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. +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. Namespace collisions -~~~~~~~~~~~~~~~~~~~~ +-------------------- -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). +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. +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. Future Scope -~~~~~~~~~~~~ +------------ 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. +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. diff --git a/feature-proposals.rst b/feature-proposals.rst index 9f89301..348bc39 100644 --- a/feature-proposals.rst +++ b/feature-proposals.rst @@ -1,125 +1,148 @@ -Feature Proposals -================= - -Introduction ------------- - -This document describes the procedure to propose an idea for adoption by the -PHP community and decide if the community accepts or rejects the idea. - -Proposal Initiation -------------------- - -Proposal is formally initiated by creating an RFC on PHP wiki and announcing it -on the list. If the proposal is a repeated discussion of an existing RFC, with -or without modification, it still should be announced on the list for -discussion. - -The announcement will be done in a way that's easy to flag & follow, e.g. - by -``[RFC]`` in the subject line followed by the title of the RFC. - -The proposal should be initiated by one of its authors. If the proposal is a -repeated one, re-proposed by somebody else, the proposer should discuss it with -the original author, if possible, and add himself to the RFC author list before -proposing it. - -If the proposer is not a member of php.net and thus can not create RFCs on the -wiki, they should recruit one of the members for help or request membership. - -Discussion Period ------------------ - -There'd be a minimum of 2 weeks between when an RFC that touches the language -is brought up on this list and when it's voted on is required. Other RFCs might -use a smaller timeframe, but it should be at least a week. The effective date -will not be when the RFC was published on the PHP wiki - but when it was -announced on ``internals@lists.php.net``, by the author, with the intention of -voting on it. This period can be extended when circumstances warrant it - such -as major conferences, key people being busy, force major events, or when -discussion merits it - but should never be less than minimal time. - -This does not preclude discussion on the merits on any idea or proposal on the -list without formally submitting it as a proposal, but the discussion time is -measured only since the formal discussion announcement as described above. - -Voting ------- - -The author decides when it's time to move ahead and call a vote on the RFC. If -the author feels that there's still healthy discussion going on, they can -decide not to move ahead to request a vote after the minimal period, but extend -it as needed. On the other hand, if they feel that the discussion is being -derailed - they can always move ahead to a vote as long as the minimum -discussion time elapsed. - -The vote is announced on the mailing list in a separate thread by sending an -email with the subject ``[VOTE]``. It should reference the RFCs being voted on -and if there are different options discussed, explain these options. It should -also contain the URL of the page where the vote is taking place. - -Votes should be open for two weeks at minimum, at the authors discretion this -may be extended, for example during holiday periods. - -A valid voting period must be declared when voting is started and must not be -changed during the vote. +################### + Feature Proposals +################### + +************** + Introduction +************** + +This document describes the procedure to propose an idea for adoption by +the PHP community and decide if the community accepts or rejects the +idea. + +********************* + Proposal Initiation +********************* + +Proposal is formally initiated by creating an RFC on PHP wiki and +announcing it on the list. If the proposal is a repeated discussion of +an existing RFC, with or without modification, it still should be +announced on the list for discussion. + +The announcement will be done in a way that's easy to flag & follow, +e.g. - by ``[RFC]`` in the subject line followed by the title of the +RFC. + +The proposal should be initiated by one of its authors. If the proposal +is a repeated one, re-proposed by somebody else, the proposer should +discuss it with the original author, if possible, and add himself to the +RFC author list before proposing it. + +If the proposer is not a member of php.net and thus can not create RFCs +on the wiki, they should recruit one of the members for help or request +membership. + +******************* + Discussion Period +******************* + +There'd be a minimum of 2 weeks between when an RFC that touches the +language is brought up on this list and when it's voted on is required. +Other RFCs might use a smaller timeframe, but it should be at least a +week. The effective date will not be when the RFC was published on the +PHP wiki - but when it was announced on ``internals@lists.php.net``, by +the author, with the intention of voting on it. This period can be +extended when circumstances warrant it - such as major conferences, key +people being busy, force major events, or when discussion merits it - +but should never be less than minimal time. + +This does not preclude discussion on the merits on any idea or proposal +on the list without formally submitting it as a proposal, but the +discussion time is measured only since the formal discussion +announcement as described above. + +******** + Voting +******** + +The author decides when it's time to move ahead and call a vote on the +RFC. If the author feels that there's still healthy discussion going on, +they can decide not to move ahead to request a vote after the minimal +period, but extend it as needed. On the other hand, if they feel that +the discussion is being derailed - they can always move ahead to a vote +as long as the minimum discussion time elapsed. + +The vote is announced on the mailing list in a separate thread by +sending an email with the subject ``[VOTE]``. It should reference the +RFCs being voted on and if there are different options discussed, +explain these options. It should also contain the URL of the page where +the vote is taking place. + +Votes should be open for two weeks at minimum, at the authors discretion +this may be extended, for example during holiday periods. + +A valid voting period must be declared when voting is started and must +not be changed during the vote. This section has been amended by: -- `Abolish Short Votes RFC `_. +- `Abolish Short Votes RFC + `_. -Required Majority ------------------ +******************* + Required Majority +******************* -The primary vote of an RFC, determining overall acceptance of the proposal, may -only have two voting options and requires a 2/3 majority. This means that the -number of Yes votes must be greater than or equal to the number of No votes -multiplied by two. +The primary vote of an RFC, determining overall acceptance of the +proposal, may only have two voting options and requires a 2/3 majority. +This means that the number of Yes votes must be greater than or equal to +the number of No votes multiplied by two. Additionally, an RFC may have secondary votes, which are used to decide -implementation details. Such votes may have more than two voting options and -may be decided by simple plurality. This means that the voting option with the -most votes wins. If there are multiple options with the most number of votes, -it is left at the discretion of the RFC author to choose one of them. +implementation details. Such votes may have more than two voting options +and may be decided by simple plurality. This means that the voting +option with the most votes wins. If there are multiple options with the +most number of votes, it is left at the discretion of the RFC author to +choose one of them. -For procedural reasons, multiple RFCs may be combined into one, in which case -there may be multiple primary votes. Combining multiple RFCs into one does not -allow turning a primary vote into a secondary vote. +For procedural reasons, multiple RFCs may be combined into one, in which +case there may be multiple primary votes. Combining multiple RFCs into +one does not allow turning a primary vote into a secondary vote. This section has been amended by: -- `Abolish Narrow Margins RFC `_. +- `Abolish Narrow Margins RFC + `_. + +********************************* + Resurrecting Rejected Proposals +********************************* + +In order to save valuable time, it will not be allowed to bring up a +rejected proposal up for another vote, unless one of the following +happens: -Resurrecting Rejected Proposals -------------------------------- +- 6 months pass from the time of the previous vote, **OR** -In order to save valuable time, it will not be allowed to bring up a rejected -proposal up for another vote, unless one of the following happens: +- The author(s) make substantial changes to the proposal. While it's + impossible to put clear definitions on what constitutes 'substantial' + changes, they should be material enough so that they'll significantly + affect the outcome of another vote. -- 6 months pass from the time of the previous vote, **OR** -- The author(s) make substantial changes to the proposal. While it's - impossible to put clear definitions on what constitutes 'substantial' - changes, they should be material enough so that they'll significantly - affect the outcome of another vote. +************** + Who Can Vote +************** -Who Can Vote ------------- +There's no way around this 'small' issue. Changes made to the PHP +language will affect millions of people, and theoretically, each and +every one of them should have a say in what we do. For obvious reasons, +though, this isn't a practical approach. -There's no way around this 'small' issue. Changes made to the PHP language -will affect millions of people, and theoretically, each and every one of them -should have a say in what we do. For obvious reasons, though, this isn't a -practical approach. +The proposal here is for two audiences to participate in the voting +process: -The proposal here is for two audiences to participate in the voting process: +- People with php.net VCS accounts that have contributed code to PHP -- People with php.net VCS accounts that have contributed code to PHP -- Representatives from the PHP community, that will be chosen by those with - php.net VCS accounts +- Representatives from the PHP community, that will be chosen by those + with php.net VCS accounts - - Lead developers of PHP based projects (frameworks, cms, tools, etc.) - - regular participant of internals discussions + - Lead developers of PHP based projects (frameworks, cms, tools, + etc.) + - regular participant of internals discussions -RFC Proposer ------------- +************** + RFC Proposer +************** -- Proposers vote with +1 on their own RFC per default if they are allowed to - vote +- Proposers vote with +1 on their own RFC per default if they are + allowed to vote diff --git a/release-process.rst b/release-process.rst index 5de6da1..8120207 100644 --- a/release-process.rst +++ b/release-process.rst @@ -1,343 +1,391 @@ -=============== -Release Process -=============== +################# + Release Process +################# .. contents:: :depth: 2 -:From: https://wiki.php.net/rfc/releaseprocess -:Updated by: https://wiki.php.net/rfc/release_cycle_update +:From: + https://wiki.php.net/rfc/releaseprocess + +:Updated by: + https://wiki.php.net/rfc/release_cycle_update This document outlines the release cycles of the PHP language. -Release Cycle -============= +*************** + Release Cycle +*************** Roughly: -- Yearly release cycle -- 4 years release life cycle +- Yearly release cycle + +- 4 years release life cycle - - 2 years bug fixes only - - 2 years security fixes only + - 2 years bug fixes only + - 2 years security fixes only No feature addition after final x.y.0 release (or x.0.0). -Backward compatibility MUST be respected within the same major release (e.g., -8.x.x). Binary compatibility (API or ABI) MAY be broken between two -features releases, f.e. between 8.3 and 8.4. +Backward compatibility MUST be respected within the same major release +(e.g., 8.x.x). Binary compatibility (API or ABI) MAY be broken between +two features releases, f.e. between 8.3 and 8.4. Major Version Number --------------------- +==================== -- x.y.z to x+1.0.0 +- x.y.z to x+1.0.0 - - Bug fixes - - New features - - Extensions support can be ended (moved to PECL) - - Backward compatibility can be broken - - API compatibility can be broken (internals and userland) - - ABI can be broken (internals) + - Bug fixes + - New features + - Extensions support can be ended (moved to PECL) + - Backward compatibility can be broken + - API compatibility can be broken (internals and userland) + - ABI can be broken (internals) Minor Version Number --------------------- +==================== -- x.y.z to x.y+1.z +- x.y.z to x.y+1.z - - Bugfixes - - New features - - Extensions support can be ended (moved to PECL) - - Backward compatibility must be kept - - API compatibility must be kept (userland) - - ABI and API can be broken (internals) - - Source compatibility should be kept if possible, while breakages are allowed + - Bugfixes + - New features + - Extensions support can be ended (moved to PECL) + - Backward compatibility must be kept + - API compatibility must be kept (userland) + - ABI and API can be broken (internals) + - Source compatibility should be kept if possible, while breakages + are allowed Patch Version Number --------------------- +==================== -- x.y.z to x.y.z+1 +- x.y.z to x.y.z+1 - - Bug fixes and security patches only - - Extensions support can't be removed (like move them to PECL) - - Backward compatibility must be kept (internals and userland) - - ABI and API compatibility must be kept (internals) + - Bug fixes and security patches only + - Extensions support can't be removed (like move them to PECL) + - Backward compatibility must be kept (internals and userland) + - ABI and API compatibility must be kept (internals) -It is critical to understand the consequences of breaking BC, APIs or ABIs -(only internals related). It should not be done for the sake of doing it. RFCs -explaining the reasoning behind a breakage and the consequences along with -test cases and patch(es) should help. +It is critical to understand the consequences of breaking BC, APIs or +ABIs (only internals related). It should not be done for the sake of +doing it. RFCs explaining the reasoning behind a breakage and the +consequences along with test cases and patch(es) should help. See the following links for explanation about API and ABI: -- http://en.wikipedia.org/wiki/Application_programming_interface -- http://en.wikipedia.org/wiki/Application_binary_interface +- http://en.wikipedia.org/wiki/Application_programming_interface +- http://en.wikipedia.org/wiki/Application_binary_interface Example time line with only one major version at a time -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------------- -:: +.. code:: - **** pre release phase - ++++ release lifetime with all bug fixes, no feature addition - ---- release lifetime security fixes only - G GA Release - D EOL + **** pre release phase + ++++ release lifetime with all bug fixes, no feature addition + ---- release lifetime security fixes only + G GA Release + D EOL - Version Time -> - 2023 2024 2025 2026 2027 2028 2029 - | | | | | | | | | | | | | - 8.1 |++++++++++-------------------------D - 8.2 |+++++++++++++++++++++++------------------------D - 8.3 | *****G++++++++++++++++++++++++------------------------D - 8.4 | | | |****G++++++++++++++++++++++++------------------------D + Version Time -> + 2023 2024 2025 2026 2027 2028 2029 + | | | | | | | | | | | | | + 8.1 |++++++++++-------------------------D + 8.2 |+++++++++++++++++++++++------------------------D + 8.3 | *****G++++++++++++++++++++++++------------------------D + 8.4 | | | |****G++++++++++++++++++++++++------------------------D +****************** + Release Timeline +****************** -Release Timeline -================ +The process starts the first Tuesday of July of each year, and nominally +runs for 20 weeks. With 3 alpha releases, 3 beta releases, 4 release +candidates, and a GA (x.0.0) release. -The process starts the first Tuesday of July of each year, and nominally runs -for 20 weeks. With 3 alpha releases, 3 beta releases, 4 release candidates, -and a GA (x.0.0) release. +Examples are given for 2024 and PHP 8.4. Releases are tagged on the +Tuesday of each week, with a release before Thursday 24:00 (UTC). -Examples are given for 2024 and PHP 8.4. Releases are tagged on the Tuesday of -each week, with a release before Thursday 24:00 (UTC). - -In the examples, `$rd` describes the release day of the first alpha release. +In the examples, `$rd` describes the release day of the first alpha +release. Alpha Releases --------------- +============== .. list-table:: :header-rows: 0 :stub-columns: 1 - * - Alpha 1 - - * Tag on *First Tuesday of July*: ``$rd - 2`` (Jul 2, 2024) - * Release before *First Thursday of July*: ``$rd`` (Jul 4, 2024) - * - Alpha 2 - - ``$rd + 14`` (Jul 18, 2024) - * - Alpha 3 - - ``$rd + 28`` (Aug 01, 2024) + - - Alpha 1 + + - - Tag on *First Tuesday of July*: ``$rd - 2`` (Jul 2, 2024) + - Release before *First Thursday of July*: ``$rd`` (Jul 4, + 2024) + + - - Alpha 2 + - ``$rd + 14`` (Jul 18, 2024) + + - - Alpha 3 + - ``$rd + 28`` (Aug 01, 2024) During the alpha releases: -- New features may be added at will, following the normal RFC procedures. +- New features may be added at will, following the normal RFC + procedures. Beta Releases -------------- +============= .. list-table:: :header-rows: 0 :stub-columns: 1 - * - Beta 1 - - * Tag / Feature Freeze: ``$rd + 40`` (Aug 13, 2024) - * Release: ``$rd + 42`` (Aug 15, 2024) - * - Beta 2 - - ``$rd + 56`` (Aug 29, 2024) - * - Beta 3 - - ``$rd + 70`` (Sep 12, 2024) + - - Beta 1 + - - Tag / Feature Freeze: ``$rd + 40`` (Aug 13, 2024) + - Release: ``$rd + 42`` (Aug 15, 2024) + + - - Beta 2 + - ``$rd + 56`` (Aug 29, 2024) + + - - Beta 3 + - ``$rd + 70`` (Sep 12, 2024) At feature freeze: -- All features requiring an RFC must have passed by the voting mechanism, and - SHOULD be merged prior to feature freeze. +- All features requiring an RFC must have passed by the voting + mechanism, and SHOULD be merged prior to feature freeze. After feature freeze, with blessing of the release managers: -- Merging features that do require an RFC is still allowed. -- Features that do not require an RFC are still allowed. -- Optimisations and internal ABI and API changes are also still allowed. +- Merging features that do require an RFC is still allowed. +- Features that do not require an RFC are still allowed. +- Optimisations and internal ABI and API changes are also still + allowed. Release Candidates ------------------- +================== .. list-table:: :header-rows: 0 :stub-columns: 1 - * - Release Candidate 1 - - * Tag: ``$rd + 82`` (Sep 24, 2024) - * Release: ``$rd + 84`` (Sep 26, 2024) - * - Release Candidate 2 - - ``$rd + 98`` (Oct 10, 2024) - * - Release Candidate 3 - - ``$rd + 112`` (Oct 24, 2024) - * - Release Candidate 4 - - ``$rd + 126`` (Nov 07, 2024) + - - Release Candidate 1 + - - Tag: ``$rd + 82`` (Sep 24, 2024) + - Release: ``$rd + 84`` (Sep 26, 2024) + + - - Release Candidate 2 + - ``$rd + 98`` (Oct 10, 2024) + + - - Release Candidate 3 + - ``$rd + 112`` (Oct 24, 2024) + + - - Release Candidate 4 + - ``$rd + 126`` (Nov 07, 2024) More release candidates MAY be added on a two-week cycle, if necessary. With the first release candidate: -- Internal API numbers MUST be updated (``PHP_API_VERSION``, - ``ZEND_MODULE_API_NO``, and ``ZEND_EXTENSION_API_NO``). -- The release branch (``PHP-8.4``) MUST be created. +- Internal API numbers MUST be updated (``PHP_API_VERSION``, + ``ZEND_MODULE_API_NO``, and ``ZEND_EXTENSION_API_NO``). +- The release branch (``PHP-8.4``) MUST be created. After the first release candidate: -- There MUST NOT be any API and ABI changes in subsequent RCs. -- There MUST NOT be any new features, small or otherwise, in subsequent RCs. - +- There MUST NOT be any API and ABI changes in subsequent RCs. +- There MUST NOT be any new features, small or otherwise, in subsequent + RCs. General Availability --------------------- +==================== .. list-table:: :header-rows: 0 :stub-columns: 1 - * - x.y.0 (8.4.0) - - * Tag: ``$rd + 138`` (Nov 19, 2024) - * Release: ``$rd + 140`` (Nov 21, 2024) + - - x.y.0 (8.4.0) + - - Tag: ``$rd + 138`` (Nov 19, 2024) + - Release: ``$rd + 140`` (Nov 21, 2024) -The GA release MUST be released from the last Release Candidate tag (RC4 or -later). There MUST NOT be any changes between the last Release Candidate tag and -the GA tag (with exception to files such as `NEWS` and other files where the -PHP version number must change for the GA release). +The GA release MUST be released from the last Release Candidate tag (RC4 +or later). There MUST NOT be any changes between the last Release +Candidate tag and the GA tag (with exception to files such as `NEWS` and +other files where the PHP version number must change for the GA +release). Bug Fix and Security Releases ------------------------------ +============================= After the general availability release: -- Until the end of year 2 (e.g., for PHP 8.4: until Dec 31, 2026): +- Until the end of year 2 (e.g., for PHP 8.4: until Dec 31, 2026): + + - A new release every 4 weeks, synchronised with other release + branches. + - Bug fixes and security fixes. - - A new release every 4 weeks, synchronised with other release branches. - - Bug fixes and security fixes. +- Until the end of year 3 (e.g., for PHP 8.4: until Dec 31, 2027): -- Until the end of year 3 (e.g., for PHP 8.4: until Dec 31, 2027): + - Security fixes, and fixes to address regressions introduced + during a normal bug fix release. - - Security fixes, and fixes to address regressions introduced during a - normal bug fix release. - - Updates to ABI incompatible versions of dependent libraries on Windows. - - Release only when there is a security issue or regression issue to - address. - - Security fix and regression releases SHOULD occur on the same date as bug - fix releases for the other branches. Exceptions can be made for high risk - security issues or high profile regressions. + - Updates to ABI incompatible versions of dependent libraries on + Windows. -- Until the end of year 4 (e.g., for PHP 8.4: until Dec 31, 2028): + - Release only when there is a security issue or regression issue + to address. - - Security fixes **only**. - - Release only when there is a security issue. - - Security fix releases SHOULD occur on the same date as bug fix releases - for the other branches. Exceptions can be made for high risk security - issues. - - Updates to ABI incompatible versions of dependent libraries on Windows - are **not** performed. + - Security fix and regression releases SHOULD occur on the same + date as bug fix releases for the other branches. Exceptions can + be made for high risk security issues or high profile + regressions. +- Until the end of year 4 (e.g., for PHP 8.4: until Dec 31, 2028): -*"End of year" means:* The end of the calendar year, i.e., Dec 31 at 24:00 UTC. The numbered years in the examples (e.g., "end of year 2") indicate the number of calendar years following the *original planned GA release date*. For example, if the planned GA release date for PHP 8.4 is Nov 21, 2024, then "end of year 2" is Dec 31, 2026, 24:00 UTC, even if the actual release date slips to Jan 9, 2025. + - Security fixes **only**. -Feature selection and development -================================= + - Release only when there is a security issue. -RFCs have been introduced many years ago and have been proven as being an -amazing way to avoid conflicts while providing a very good way to propose new -things to php.net. New features or additions to the core should go through the -RFC process. It has been done successfully (as the process went well, but the -features were not necessary accepted) already for a dozen of new features or -improvements. + - Security fix releases SHOULD occur on the same date as bug fix + releases for the other branches. Exceptions can be made for + high risk security issues. -Features can use branch(es) if necessary, doing so will minimize the impact of -other commits and changes on the development of a specific feature (or the -other way 'round). The shorter release cycle also ensures that a given feature -can get into the next release, as long as the RFC has been accepted. + - Updates to ABI incompatible versions of dependent libraries on + Windows are **not** performed. + +*"End of year" means:* The end of the calendar year, i.e., Dec 31 at +24:00 UTC. The numbered years in the examples (e.g., "end of year 2") +indicate the number of calendar years following the *original planned GA +release date*. For example, if the planned GA release date for PHP 8.4 +is Nov 21, 2024, then "end of year 2" is Dec 31, 2026, 24:00 UTC, even +if the actual release date slips to Jan 9, 2025. + +*********************************** + Feature selection and development +*********************************** + +RFCs have been introduced many years ago and have been proven as being +an amazing way to avoid conflicts while providing a very good way to +propose new things to php.net. New features or additions to the core +should go through the RFC process. It has been done successfully (as the +process went well, but the features were not necessary accepted) already +for a dozen of new features or improvements. + +Features can use branch(es) if necessary, doing so will minimize the +impact of other commits and changes on the development of a specific +feature (or the other way 'round). The shorter release cycle also +ensures that a given feature can get into the next release, as long as +the RFC has been accepted. The change to what we have now is the voting process. It will not happen -anymore on the mailing list but in the RFCs directly, for php.net members, in -a public way. +anymore on the mailing list but in the RFCs directly, for php.net +members, in a public way. See also `the voting RFC `_. The question for this section is about who will be allowed to vote: -- php-src (yes, no) -- php-doc (yes, no) -- qa, phpt (yes, no) -- other sub projects like pear (yes, no) +- php-src (yes, no) +- php-doc (yes, no) +- qa, phpt (yes, no) +- other sub projects like pear (yes, no) -We have voting plugin for dokuwiki (doodle2) that allows voting on the wiki -(installed). +We have voting plugin for dokuwiki (doodle2) that allows voting on the +wiki (installed). -RMs Role -======== +********** + RMs Role +********** The roles of the release managers are about being a facilitator: -- Manage the release process -- Start the decisions discussions and vote about the features and change for a given release -- Create a roadmap and planing according to this RFC -- Package the releases (test and final releases) -- Decide which bug fixes can be applied to a release, within the cases defined in this RFC +- Manage the release process +- Start the decisions discussions and vote about the features and + change for a given release +- Create a roadmap and planing according to this RFC +- Package the releases (test and final releases) +- Decide which bug fixes can be applied to a release, within the cases + defined in this RFC But they are not: -- Decide which features, extension or SAPI get in a release or not +- Decide which features, extension or SAPI get in a release or not -Discussions or requests for a feature or to apply a given patch must be done -on the public internals mailing list or in the security mailing (ideally using -the bug tracker) +Discussions or requests for a feature or to apply a given patch must be +done on the public internals mailing list or in the security mailing +(ideally using the bug tracker) -Release managers selection -========================== +**************************** + Release managers selection +**************************** -About three months prior to the scheduled release of the first alpha release -of the next minor or major version (around April 1st or shortly thereafter), -the release managers for the latest version branch should issue a call for -volunteers to begin the selection process for the next release managers. +About three months prior to the scheduled release of the first alpha +release of the next minor or major version (around April 1st or shortly +thereafter), the release managers for the latest version branch should +issue a call for volunteers to begin the selection process for the next +release managers. -The release manager team consists of two or three people, it is notable that -at least one of the volunteers should be a "veteran" release manager, meaning -they have contributed to at least one PHP release in the past. The other can -be an additional veteran or, ideally, someone new to the RM role (to increase -number of veteran RMs). +The release manager team consists of two or three people, it is notable +that at least one of the volunteers should be a "veteran" release +manager, meaning they have contributed to at least one PHP release in +the past. The other can be an additional veteran or, ideally, someone +new to the RM role (to increase number of veteran RMs). -Issue the call for volunteers on internals@lists.php.net on or around March -1st. See, for example: https://news-web.php.net/php.internals/113334 +Issue the call for volunteers on internals@lists.php.net on or around +March 1st. See, for example: +https://news-web.php.net/php.internals/113334 -There is no rule for how long the call for volunteers must remain open. We -should aim to select the release managers by early April, so announcing the -call in early March gives people about a month to decide whether they wish to -volunteer. +There is no rule for how long the call for volunteers must remain open. +We should aim to select the release managers by early April, so +announcing the call in early March gives people about a month to decide +whether they wish to volunteer. Voting is conducted using "Single Transferrable Vote" (STV). -Using some maths, we'll start with the 1st preference and gradually remove -candidates with the fewest votes, transferring votes that had previously gone -to them to their voter’s 2nd preference, and so on. Once required number of -candidates have a quorum (Droop quota), those will be officially selected as -our RMs. +Using some maths, we'll start with the 1st preference and gradually +remove candidates with the fewest votes, transferring votes that had +previously gone to them to their voter’s 2nd preference, and so on. Once +required number of candidates have a quorum (Droop quota), those will be +officially selected as our RMs. -Feature(s) preview release, solving the experimental features -============================================================= +*************************************************************** + Feature(s) preview release, solving the experimental features +*************************************************************** -Some features require a lot of testing or users feedback before they can be -considered as ready, stable enough, or proven as having made good design -decisions. Having them in normal releases is dangerous. The past releases told -us more that once than many good ideas ended as being not so good after all. -But we had to keep them in and, even worst, maintain them forever. +Some features require a lot of testing or users feedback before they can +be considered as ready, stable enough, or proven as having made good +design decisions. Having them in normal releases is dangerous. The past +releases told us more that once than many good ideas ended as being not +so good after all. But we had to keep them in and, even worst, maintain +them forever. A feature preview release could solve this problem. A feature(s) preview -release gives us and our users a way to try bleeding edge additions to the -language or core while providing us with an invaluable feedback to actually -valid both the implementation and the design choices. +release gives us and our users a way to try bleeding edge additions to +the language or core while providing us with an invaluable feedback to +actually valid both the implementation and the design choices. + +Non core features (engine, stream, etc.) could benefit from a feature +preview release while doing it via PECL should be the preferred way. -Non core features (engine, stream, etc.) could benefit from a feature preview -release while doing it via PECL should be the preferred way. +Feature(s) preview releases can happen any time and can be platform +specific. Whether a specific development branch is used or not is up to +the developers of the given features (external repositories like github +or bitbucket can obviously be used as well). -Feature(s) preview releases can happen any time and can be platform specific. -Whether a specific development branch is used or not is up to the developers -of the given features (external repositories like github or bitbucket can -obviously be used as well). +********************* + Security Management +********************* -Security Management -=================== +- Each security flaw must have a CVE id before the final release. -- Each security flaw must have a CVE id before the final release. -- Ideally security issues and their fixes are reported and discussed in the issues tracker +- Ideally security issues and their fixes are reported and discussed in + the issues tracker - - Needs a 'security' flag in bugs.php.net (implemented, a CVE field has been added as well) - - Methods to reproduce a flaw may remain non public (on a case by case basis) - - Be sure that the security team of each major distributions have access to the security reports, before public release + - Needs a 'security' flag in bugs.php.net (implemented, a CVE field + has been added as well) + - Methods to reproduce a flaw may remain non public (on a case by + case basis) + - Be sure that the security team of each major distributions have + access to the security reports, before public release diff --git a/security-classification.rst b/security-classification.rst index bb43f0a..9cbc6f2 100644 --- a/security-classification.rst +++ b/security-classification.rst @@ -1,25 +1,28 @@ -=============================== -Vulnerability Disclosure Policy -=============================== +################################# + Vulnerability Disclosure Policy +################################# -This document was originally published at . +This document was originally published at +. -Introduction -============ +************** + Introduction +************** For the sake of our users, we classify some of the issues found in PHP as "security issues". This document is intended to explain which issues are thus classified, how we handle those issues and how to report them. -Classification -============== +**************** + Classification +**************** We classify as security issues bugs that: -- allow users to execute unauthorized actions -- cross security boundaries -- access data that is not intended to be accessible -- severely impact accessibility or performance of the system +- allow users to execute unauthorized actions +- cross security boundaries +- access data that is not intended to be accessible +- severely impact accessibility or performance of the system The purpose of this classification is to alert the users and the developers about the bugs that need to be prioritized in their handling. @@ -30,14 +33,14 @@ subjective, so it ultimately relies on the judgement of the PHP developers. High Severity -------------- +============= These issues may allow: -- third party to compromise any, or most installations of PHP -- the execution of arbitrary code -- disabling the system completely -- access to any file a local PHP user can access. +- third party to compromise any, or most installations of PHP +- the execution of arbitrary code +- disabling the system completely +- access to any file a local PHP user can access. The issue can be triggered on any, or on most typical installations, and does not require exotic and non-recommended settings to be triggered. @@ -53,25 +56,25 @@ pattern if such code or pattern is present in many popular libraries. This kind of issues usually requires a CVE report. Medium Severity ---------------- +=============== These issues may have the same potential to compromise an installation as a high severity issue, but may also require: -- an extension that is not commonly used -- a particular type of configuration that is used only in narrow - specific circumstances -- relies on old version of a third-party library being used -- code, or patterns of code, that are known to be used infrequently -- code that is very old, or extremely uncommon (and so is used - infrequently) +- an extension that is not commonly used +- a particular type of configuration that is used only in narrow + specific circumstances +- relies on old version of a third-party library being used +- code, or patterns of code, that are known to be used infrequently +- code that is very old, or extremely uncommon (and so is used + infrequently) This kind of issues usually will have a CVE number, unless the required configuration is particularly exotic to the point it's not practically usable. Low Severity ------------- +============ This issue allows theoretical compromise of security, but practical attack is usually impossible or extremely hard due to common practices @@ -93,34 +96,46 @@ discretion of the PHP developers, be disclosed publicly before the fix is released or available. Not a Security Issue --------------------- +==================== We do not classify as a security issue any issue that: -- requires invocation of specific code, which may be valid but is - obviously malicious -- requires invocation of functions with specific arguments, which may - be valid but are obviously malicious -- requires specific actions to be performed on the server, which are - not commonly performed, or are not commonly permissible for the user - (uid) executing PHP -- requires privileges superior to that of the user (uid) executing PHP -- requires the use of debugging facilities - ex. xdebug, var_dump -- requires the use of settings not recommended for production - ex. - error reporting to output -- requires the use of non-standard environment variables - ex. - USE_ZEND_ALLOC -- requires the use of non-standard builds - ex. obscure embedded - platform, not commonly used compiler -- requires the use of code or settings known to be insecure -- requires the use of FFI -- requires an open_basedir bypass - -Handling Issues -=============== +- requires invocation of specific code, which may be valid but is + obviously malicious + +- requires invocation of functions with specific arguments, which may + be valid but are obviously malicious + +- requires specific actions to be performed on the server, which are + not commonly performed, or are not commonly permissible for the user + (uid) executing PHP + +- requires privileges superior to that of the user (uid) executing PHP + +- requires the use of debugging facilities - ex. xdebug, var_dump + +- requires the use of settings not recommended for production - ex. + error reporting to output + +- requires the use of non-standard environment variables - ex. + USE_ZEND_ALLOC + +- requires the use of non-standard builds - ex. obscure embedded + platform, not commonly used compiler + +- requires the use of code or settings known to be insecure + +- requires the use of FFI + +- requires an open_basedir bypass + +***************** + Handling Issues +***************** -High and medium severity fixes are merged into a private security repository, -and then merged to the main repository before the release is tagged. +High and medium severity fixes are merged into a private security +repository, and then merged to the main repository before the release is +tagged. Low severity fixes are merged immediately after the fix is available and handled like all regular bugs are handled consequently. However, release @@ -128,58 +143,60 @@ managers may choose to pull those fixes into the RC branch after the branch is created, and also backport them into a security-only release branch. -FAQ -=== +***** + FAQ +***** How Do I Report a Security Issue? ---------------------------------- +================================= Please report security vulnerabilities on GitHub at: -If for some reason you cannot use the form at GitHub, or you need to talk to -somebody about a PHP security issue that might not be a bug report, please write -to . +If for some reason you cannot use the form at GitHub, or you need to +talk to somebody about a PHP security issue that might not be a bug +report, please write to . -Vulnerability reports remain private until published. When published, you will -be credited as a contributor, and your contribution will reflect the MITRE -Credit System. +Vulnerability reports remain private until published. When published, +you will be credited as a contributor, and your contribution will +reflect the MITRE Credit System. What Do You Consider a Responsible Disclosure? ----------------------------------------------- +============================================== -Please report the issue as described above. Please communicate with -the developers about when the fix will be released - usually it's the -next monthly release after the bug was reported. Some issues can take -longer. After the fix is released (releases usually happen on Thursdays) -please feel free to disclose the issue as you see fit. +Please report the issue as described above. Please communicate with the +developers about when the fix will be released - usually it's the next +monthly release after the bug was reported. Some issues can take longer. +After the fix is released (releases usually happen on Thursdays) please +feel free to disclose the issue as you see fit. What If I Think It's a Security Issue But The Developers Disagree? ------------------------------------------------------------------- +================================================================== Please read the above and try to explain to us why it fits the description. What If The Developers Still Don't Think It's a Security Issue? ---------------------------------------------------------------- +=============================================================== We'll have to agree to disagree. The Bug I Submitted Was Classified As "Not a Security Issue." You Don't Believe It's Real? ------------------------------------------------------------------------------------------- +========================================================================================== -It has nothing to do with the bug being real or its importance to -you. It just means it does not fit our specific definitions for issues -that we will handle in a special way. We fix a lot of non-security bugs -and pull requests are always welcome. +It has nothing to do with the bug being real or its importance to you. +It just means it does not fit our specific definitions for issues that +we will handle in a special way. We fix a lot of non-security bugs and +pull requests are always welcome. But You Classified Bug #424242 As a Security Issue, But Not This One?! ----------------------------------------------------------------------- +====================================================================== -Each bug usually has its aspects, if a short discussion does not -yield agreement we'd rather do more fixing and less arguing. +Each bug usually has its aspects, if a short discussion does not yield +agreement we'd rather do more fixing and less arguing. Do You Pay Bounties For Security Issues? ----------------------------------------- +======================================== -PHP is a volunteer project. We have no money, thus we can't pay bounties. +PHP is a volunteer project. We have no money, thus we can't pay +bounties. diff --git a/security-policies.rst b/security-policies.rst index 8a167da..435eb4b 100644 --- a/security-policies.rst +++ b/security-policies.rst @@ -1,84 +1,107 @@ -============================= -Security Policies and Process -============================= +############################### + Security Policies and Process +############################### .. IMPORTANT:: - This is a meta document discussing PHP security policies and processes. For - the actual PHP security policy, see the PHP `Vulnerability Disclosure - Policy + + This is a meta document discussing PHP security policies and + processes. For the actual PHP security policy, see the PHP + `Vulnerability Disclosure Policy `_ document. -PHP.net security.txt file -========================= +*************************** + PHP.net security.txt file +*************************** PHP.net includes a `security.txt -`_ file that complements the -`Vulnerability Disclosure Policy +`_ file that complements +the `Vulnerability Disclosure Policy `_, -aiding security vulnerability disclosure. This file implements the standard -defined in `RFC 9116 `_, and more -information is available at . - -RFC 9116 requires an ``Expires`` field in ``security.txt``, and its recommendation -is for the ``Expires`` field to be less than a year in the future. This provides -security researchers with confidence they are using our most up-to-date -reporting policies. To facilitate yearly updates to the ``Expires`` field and -ensure freshness of the information in ``security.txt``, the PHP release managers -`update the Expires field as part of the X.Y.0 GA release +aiding security vulnerability disclosure. This file implements the +standard defined in `RFC 9116 +`_, and more information is +available at . + +RFC 9116 requires an ``Expires`` field in ``security.txt``, and its +recommendation is for the ``Expires`` field to be less than a year in +the future. This provides security researchers with confidence they are +using our most up-to-date reporting policies. To facilitate yearly +updates to the ``Expires`` field and ensure freshness of the information +in ``security.txt``, the PHP release managers `update the Expires field +as part of the X.Y.0 GA release `_. -From time-to-time, we may update ``security.txt`` with new information, outside -of the yearly changes to the ``Expires`` field. +From time-to-time, we may update ``security.txt`` with new information, +outside of the yearly changes to the ``Expires`` field. Making changes to security.txt ------------------------------- +============================== -All changes to ``security.txt`` must be signed by a PHP release manager for a -`currently supported version of PHP -`_ (at the time of the changes). -Release managers are the most logical choice for signing this file, since we -already `publish their PGP keys `_. +All changes to ``security.txt`` must be signed by a PHP release manager +for a `currently supported version of PHP +`_ (at the time of the +changes). Release managers are the most logical choice for signing this +file, since we already `publish their PGP keys +`_. To make changes to ``security.txt``: -1. Go to your local clone of `web-php `_:: +#. Go to your local clone of `web-php + `_: + + .. code:: + + cd /path/to/web-php/.well-known - cd /path/to/web-php/.well-known +#. Remove the PGP signature that wraps the body of ``security.txt``: -2. Remove the PGP signature that wraps the body of ``security.txt``:: + .. code:: - gpg --decrypt --output security.txt security.txt + gpg --decrypt --output security.txt security.txt .. NOTE:: - To "decrypt" ``security.txt``, you will need the public key of the release - manager who last signed it in your GPG keychain. -3. Make and save your changes to this file, e.g., update the ``Expires`` timestamp. + To "decrypt" ``security.txt``, you will need the public key of the + release manager who last signed it in your GPG keychain. + +#. Make and save your changes to this file, e.g., update the ``Expires`` + timestamp. + + There should be a "Signed by" comment in the file that looks similar + to this: - There should be a "Signed by" comment in the file that looks similar to - this:: + .. code:: - # Signed by Ben Ramsey on 2023-09-28. + # Signed by Ben Ramsey on 2023-09-28. - Update this line with your name, the email address associated with the key - you're using to sign the file, and the current date. + Update this line with your name, the email address associated with + the key you're using to sign the file, and the current date. -4. Sign your changes:: +#. Sign your changes: - gpg --clearsign --local-user YOU@php.net --output security.txt.asc security.txt + .. code:: + + gpg --clearsign --local-user YOU@php.net --output security.txt.asc security.txt .. WARNING:: - You cannot use ``--output`` to output the signature to the same file as the - input file or ``gpg`` will result in a signature wrapped around empty content. -5. Last, replace ``security.txt`` with ``security.txt.asc`` and commit your - changes:: + You cannot use ``--output`` to output the signature to the same + file as the input file or ``gpg`` will result in a signature + wrapped around empty content. + +#. Last, replace ``security.txt`` with ``security.txt.asc`` and commit + your changes: + + .. code:: - mv security.txt.asc security.txt - git commit security.txt + mv security.txt.asc security.txt + git commit security.txt .. NOTE:: - You may verify the signature with the following command:: - gpg --verify security.txt + You may verify the signature with the following command: + + .. code:: + + gpg --verify security.txt