diff --git a/README.rst b/README.rst index 6fc5621..a7052b3 100644 --- a/README.rst +++ b/README.rst @@ -2,30 +2,26 @@ Policies ########## -This repository contains a list of policies that the PHP Project has -adopted through its RFC process to govern releases, voting, and naming -guidelines. +This repository contains a list of policies that the PHP Project has adopted +through its RFC process to govern releases, voting, and naming guidelines. It contains the following items: -- `Release Process `_: When releases are made, how - they are named, our policy on version numbers, and the process on - making releases. +- `Release Process `_: When releases are made, how they + are named, our policy on version numbers, and the process on making releases. -- `Feature Proposals (RFCs) `_: How to propose - new features to PHP. +- `Feature Proposals (RFCs) `_: How to propose new + features to PHP. -- `Coding Standards `_: How to name - new classes, methods, extensions, and functions. +- `Coding Standards `_: How to name new + classes, methods, extensions, and functions. -- `Security Classification `_: What we - consider as security issues, their severity, and how to report - issues. +- `Security Classification `_: What we consider as + security issues, their severity, and how to report issues. -- `Security Policies and Process `_: Policies - and process on how and when to update the `security.txt - `_ file on - https://www.php.net. +- `Security Policies and Process `_: Policies and + process on how and when to update the `security.txt + `_ file on https://www.php.net. ************ Formatting diff --git a/coding-standards-and-naming.rst b/coding-standards-and-naming.rst index f0d38e6..ed25f4d 100644 --- a/coding-standards-and-naming.rst +++ b/coding-standards-and-naming.rst @@ -8,24 +8,22 @@ 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: +acronyms/initialisms are to be handled when writing user-level class names. The +current rule is: .. code:: @@ -46,45 +44,43 @@ names. The current rule is: — `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: +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. +- **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. + `_ 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. +- **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. +**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. +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. Good: @@ -121,37 +117,36 @@ From: `Casing of acronyms in class and method names RFC 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 ======== @@ -205,248 +200,208 @@ Bad class names: 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: +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. +- 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. +- 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``. - +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``. - +- ``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. - +- ``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. -- ``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``. +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``. 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). +- 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. +- 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`` +- ``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 +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. +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.) +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. - -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. +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. 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. +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. diff --git a/feature-proposals.rst b/feature-proposals.rst index 348bc39..46a4234 100644 --- a/feature-proposals.rst +++ b/feature-proposals.rst @@ -6,98 +6,90 @@ 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. +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. +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 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. +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. +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. +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 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. +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. +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. +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 ******************* -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: @@ -108,41 +100,38 @@ This section has been amended by: 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: +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: - 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. +- 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 ************** -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 -- 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.) + - Lead developers of PHP based projects (frameworks, cms, tools, etc.) - regular participant of internals discussions ************** 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 8120207..d23d9fe 100644 --- a/release-process.rst +++ b/release-process.rst @@ -28,9 +28,9 @@ Roughly: 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 ==================== @@ -55,8 +55,8 @@ Minor Version Number - 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 + - Source compatibility should be kept if possible, while breakages are + allowed Patch Version Number ==================== @@ -68,10 +68,10 @@ Patch Version Number - 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: @@ -101,15 +101,14 @@ Example time line with only one major version at a time 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 ============== @@ -119,10 +118,8 @@ Alpha Releases :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) + - Release before *First Thursday of July*: ``$rd`` (Jul 4, 2024) - - Alpha 2 - ``$rd + 14`` (Jul 18, 2024) @@ -132,8 +129,7 @@ Alpha Releases 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 ============= @@ -154,15 +150,14 @@ Beta Releases 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. +- Optimisations and internal ABI and API changes are also still allowed. Release Candidates ================== @@ -195,8 +190,7 @@ With the first release candidate: 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 new features, small or otherwise, in subsequent RCs. General Availability ==================== @@ -209,11 +203,10 @@ General Availability - - 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 ============================= @@ -222,25 +215,22 @@ After the general availability release: - 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. + - 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): - - 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. + - Updates to ABI incompatible versions of dependent libraries on Windows. - - Release only when there is a security issue or regression issue - to address. + - 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. + - 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): @@ -248,40 +238,39 @@ After the general availability release: - 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. + - 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. + - 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. +*"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. +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. +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. +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. See also `the voting RFC `_. @@ -292,8 +281,8 @@ The question for this section is about who will be allowed to vote: - 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 @@ -302,77 +291,74 @@ wiki (installed). 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 +- 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 +- 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 -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 **************************** -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 *************************************************************** -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. +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. -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 @@ -380,12 +366,12 @@ or bitbucket can obviously be used as well). - 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 9cbc6f2..fd0d381 100644 --- a/security-classification.rst +++ b/security-classification.rst @@ -2,16 +2,15 @@ Vulnerability Disclosure Policy ################################# -This document was originally published at -. +This document was originally published at . ************** 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. +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 @@ -24,13 +23,12 @@ We classify as security issues bugs that: - 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. +The purpose of this classification is to alert the users and the developers +about the bugs that need to be prioritized in their handling. -We define three categories of security issues, by their severity, -described below. Please note that this categorization is in many aspects -subjective, so it ultimately relies on the judgement of the PHP -developers. +We define three categories of security issues, by their severity, described +below. Please note that this categorization is in many aspects subjective, so it +ultimately relies on the judgement of the PHP developers. High Severity ============= @@ -42,86 +40,83 @@ These issues may allow: - 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. +The issue can be triggered on any, or on most typical installations, and does +not require exotic and non-recommended settings to be triggered. -This category also includes issues that can be triggered in code or -functions known to be frequently used (session, json, mysql, openssl, -etc.) during typical usage, and that require settings or configurations -that may not be strictly the best practice, but are commonly used. +This category also includes issues that can be triggered in code or functions +known to be frequently used (session, json, mysql, openssl, etc.) during typical +usage, and that require settings or configurations that may not be strictly the +best practice, but are commonly used. -This category also may include issues that require special code or code -pattern if such code or pattern is present in many popular libraries. +This category also may include issues that require special code or code 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: +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 +- 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) +- 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. +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 -or limitations that are virtually always present or imposed. +This issue allows theoretical compromise of security, but practical attack is +usually impossible or extremely hard due to common practices or limitations that +are virtually always present or imposed. This also includes problems with configuration, documentation, and other -non-code parts of the PHP project that may mislead users, or cause them -to make their system, or their code less secure. +non-code parts of the PHP project that may mislead users, or cause them to make +their system, or their code less secure. -Issues that can trigger unauthorized actions that do not seem to be -useful for any practical attack can also be categorized as low severity. +Issues that can trigger unauthorized actions that do not seem to be useful for +any practical attack can also be categorized as low severity. -Security issues, that are present only in unstable branches, belong to -this category, too. Any branch that has no stable release, is per se not -intended for the production use. +Security issues, that are present only in unstable branches, belong to this +category, too. Any branch that has no stable release, is per se not intended for +the production use. -Low severity issues usually do not need to have CVE and may, at the -discretion of the PHP developers, be disclosed publicly before the fix -is released or available. +Low severity issues usually do not need to have CVE and may, at the 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 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 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 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 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 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 non-standard builds - ex. obscure embedded platform, not + commonly used compiler - requires the use of code or settings known to be insecure @@ -133,15 +128,13 @@ We do not classify as a security issue any issue that: 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 -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. +Low severity fixes are merged immediately after the fix is available and handled +like all regular bugs are handled consequently. However, release 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 @@ -153,28 +146,27 @@ 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. +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. +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? =============================================================== @@ -184,19 +176,18 @@ 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 435eb4b..2bf4e96 100644 --- a/security-policies.rst +++ b/security-policies.rst @@ -4,9 +4,8 @@ .. 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. @@ -15,40 +14,37 @@ *************************** 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 . +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 +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``: -#. Go to your local clone of `web-php - `_: +#. Go to your local clone of `web-php `_: .. code:: @@ -62,21 +58,20 @@ To make changes to ``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. + 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. - 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. #. Sign your changes: @@ -86,12 +81,12 @@ To make changes to ``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. + 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: +#. Last, replace ``security.txt`` with ``security.txt.asc`` and commit your + changes: .. code::