From 10844e3681a2228a765425f3bdaeae89ef71657d Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Fri, 3 Feb 2023 19:28:17 +0100 Subject: [PATCH] Sync H1 and H2 Markdown headers --- CONTRIBUTING.md | 8 +-- README.md | 18 +++---- accepted/PSR-0.md | 18 +++---- ...PSR-12-extended-coding-style-guide-meta.md | 49 +++++++++---------- accepted/PSR-14-event-dispatcher-meta.md | 3 +- accepted/PSR-14-event-dispatcher.md | 3 +- accepted/PSR-15-request-handlers-meta.md | 3 +- accepted/PSR-15-request-handlers.md | 5 +- accepted/PSR-16-simple-cache.md | 21 ++++---- accepted/PSR-17-http-factory-meta.md | 3 +- accepted/PSR-17-http-factory.md | 3 +- accepted/PSR-18-http-client-meta.md | 3 +- accepted/PSR-18-http-client.md | 3 +- accepted/PSR-20-clock.md | 13 +++-- accepted/PSR-3-logger-interface.md | 3 +- accepted/PSR-4-autoloader-examples.md | 9 ++-- bylaws/006-licensing-policies.md | 3 +- bylaws/007-psr-amendments.md | 3 +- bylaws/009-naming-conventions.md | 3 +- proposed/phpdoc-tags.md | 3 +- proposed/phpdoc.md | 3 +- proposed/psr-8-hug/PSR-8-hug-meta.md | 15 ++---- proposed/psr-8-hug/psr-8-hug.md | 3 +- .../security-disclosure-publication-meta.md | 28 ++++------- proposed/security-reporting-process-meta.md | 28 ++++------- 25 files changed, 100 insertions(+), 154 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 843a941af..9a67f8bf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ discussion and formation stages involve everyone. See the [PHP-FIG FAQ](https://www.php-fig.org/faqs/) for more information. -# Licensing +## Licensing By contributing code you agree to license your contribution under the MIT license. @@ -18,7 +18,7 @@ By contributing documentation, examples, or any other non-code assets you agree to license your contribution under the CC BY 3.0 license. Attribution shall be given according to the current bylaws of this group. -# Merge & Access Policy +## Merge & Access Policy All Editors, Coordinators and Sponsors of specifications in draft & review stage have access to push to this (php-fig/fig-standards) repository; subject to @@ -34,7 +34,7 @@ pushed to. Secretaries have, and are the only ones to have, full administrative access to all repositories and to the github organisation. -## Guidelines for merging +### Guidelines for merging * Never force push to any branch on a repository in the php-fig organisation * All changes must go through pull requests, a commit should never be pushed @@ -63,7 +63,7 @@ Should you have any questions please contact the secretaries on info [at] php-fi [dot] org. Failure to comply with guidelines will result in revokation of merge access. Merge access is a privilege and not a right. -# Tagging +## Tagging Tagging on utility and interface repository should be done regularly, ideally after every merge, or every batch of merges after PSR approval. diff --git a/README.md b/README.md index 60bf39e7a..f1a8c4356 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -PHP Framework Interoperability Group -==================================== +# PHP Framework Interoperability Group The idea behind the group is for project representatives to talk about the commonalities between our projects and find ways we can work together. Our main @@ -7,8 +6,7 @@ audience is each other, but we’re very aware that the rest of the PHP communit is watching. If other folks want to adopt what we’re doing they are welcome to do so, but that is not the aim. -Proposing a Standard Recommendation ------------------------------------- +## Proposing a Standard Recommendation To propose a PHP Standard Recommendation (PSR): @@ -21,8 +19,7 @@ To propose a PHP Standard Recommendation (PSR): [mailing list]: http://groups.google.com/group/php-fig/ -GitHub usage ------------- +## GitHub usage All discussion regarding a PSR happens on the [mailing list][]. Issues filed in GitHub are rarely monitored, and PRs are likely to be missed unless a message @@ -32,8 +29,7 @@ conducted on the mailing list, not through PR comments for the same reason. Please do not simply file an issue or PR and walk-away. The most likely outcome is that it will never get seen or addressed. -Requesting Membership ---------------------- +## Requesting Membership You **do not** need to be a voting member to participate in discussion on the [mailing list][]. @@ -50,16 +46,14 @@ To become a voting member, you must send an email to the [mailing list][]. Do not combine separate membership requests in a single thread; one request per thread, please. -Language & Translations ------------------------ +## Language & Translations All PSRs are written in British English or American English (Different specifications may vary, but it is consistent within the same specification). The PHP FIG does not offer official translations into other languages but other external entities are free to translate the specifications in accordance with the license. -Voting Members --------------- +## Voting Members The current list of voting members is available on the [project website][]. diff --git a/accepted/PSR-0.md b/accepted/PSR-0.md index e9c1d3e36..103c2e0be 100644 --- a/accepted/PSR-0.md +++ b/accepted/PSR-0.md @@ -1,5 +1,4 @@ -Autoloading Standard -==================== +# Autoloading Standard > **Deprecated** - As of 2014-10-21 PSR-0 has been marked as deprecated. [PSR-4] is now recommended as an alternative. @@ -9,8 +8,7 @@ as an alternative. The following describes the mandatory requirements that must be adhered to for autoloader interoperability. -Mandatory ---------- +## Mandatory * A fully-qualified namespace and class must have the following structure `\\(\)*` @@ -26,16 +24,14 @@ Mandatory * Alphabetic characters in vendor names, namespaces, and class names may be of any combination of lower case and upper case. -Examples --------- +## Examples * `\Doctrine\Common\IsolatedClassLoader` => `/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` * `\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php` * `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php` * `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php` -Underscores in Namespaces and Class Names ------------------------------------------ +## Underscores in Namespaces and Class Names * `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` * `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` @@ -45,8 +41,7 @@ painless autoloader interoperability. You can test that you are following these standards by utilizing this sample SplClassLoader implementation which is able to load PHP 5.3 classes. -Example Implementation ----------------------- +## Example Implementation Below is an example function to simply demonstrate how the above proposed standards are autoloaded. @@ -71,8 +66,7 @@ function autoload($className) spl_autoload_register('autoload'); ``` -SplClassLoader Implementation ------------------------------ +## SplClassLoader Implementation The following gist is a sample SplClassLoader implementation that can load your classes if you follow the autoloader interoperability diff --git a/accepted/PSR-12-extended-coding-style-guide-meta.md b/accepted/PSR-12-extended-coding-style-guide-meta.md index 725a6289b..966566905 100644 --- a/accepted/PSR-12-extended-coding-style-guide-meta.md +++ b/accepted/PSR-12-extended-coding-style-guide-meta.md @@ -1,12 +1,11 @@ -Extended Coding Style Guide Meta Document -========================================= +# Extended Coding Style Guide Meta Document -# 1. Summary +## 1. Summary This document describes the process and discussions that led to the Extended Coding Style PSR. Its goal is to explain the reasons behind each decision. -# 2. Why Bother? +## 2. Why Bother? PSR-2 was accepted in 2012 and since then a number of changes have been made to PHP, most notably recent changes for PHP 7, which have implications for coding style @@ -30,9 +29,9 @@ However it is for a lack of wanting to be dictatorial that we will aim to apply styling, rationale and stances (Described in Section 4, Approaches) in PSR-12 instead of establishing new conventions. -# 3. Scope +## 3. Scope -## 3.1. Goals +### 3.1. Goals This PSR shares the same goals as PSR-2. @@ -51,17 +50,17 @@ This PSR will include coding style guidelines related to new functionality added after the publication of PSR-2; this includes PHP 5.5, PHP 5.6 and PHP 7.0. This PSR will also include clarifications on the text of PSR-2, as described in the PSR-2 Errata. -## 3.2. Non-Goals +### 3.2. Non-Goals It is not the intention of this PSR to add entirely new coding style guidelines. PSR-12 will also not change anything stipulated in PSR-1 and PSR-2. -# 4. Approaches +## 4. Approaches The overarching approach is to attempt to apply existing PSR-2 styling and rationale to new functionality as opposed to establishing new conventions. -## 4.1. Strict Types Declarations +### 4.1. Strict Types Declarations There was a discussion about whether or not strict types should be enforced in the standard https://github.com/cs-extended/fig-standards/issues/7. All were in agreement we should only @@ -70,7 +69,7 @@ to say that strict types could not be declared. The discussion was whether it sh considered a coding style item which should be covered or whether it was out of scope and it was decided to be out of scope of a coding style guide. -## 4.2. Finally and Return Types Declaration Spacing +### 4.2. Finally and Return Types Declaration Spacing Numerous different options were suggested and they can be seen [here for return type declarations](https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-returntypesspacing-php) or @@ -78,18 +77,18 @@ Numerous different options were suggested and they can be seen and the current implementation was chosen due to consistency with other parts of the PSR-12 specification that came from PSR-2. -## 4.3. Enforcing short form for all type keywords +### 4.3. Enforcing short form for all type keywords PHP 7.0 introduced [scalar types declaration](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) which does not support long type aliases. Therefore it makes sense to enforce primary short type forms to be used to have uniform syntax and prevent possible confusion. -## 4.4. Public Survey +### 4.4. Public Survey In order to settle things using data, survey was conducted and responses from 142 people including 17 project representatives were gathered: -### 4.4.1. PHP-FIG Representative Results +#### 4.4.1. PHP-FIG Representative Results | Representative | Project | Compound namespaces with a depth of two or more MUST not be used | Header statement grouping and ordering | Declare statements must each be on their own line | Declare statements in PHP files containing markup | Declare statements have no spaces: `declare(strict_types=1);` | Block declare statement formatting | `new` keyword usage, parenthesis required |Return type declaration formatting |Use statement leading slashes disallowed | Block namespace declaration formatting | General operator spacing |Try, Catch, Finally formatting | Anonymous class declaration formatting | Keyword casing, only lower case | Type keywords, short form only | | -------------- | ------- | ---------------------------------------------------- | ---------------------------------- | ----------------------------------------- | ------------------------------------------- | -------------------------------------------------------- | ------------------------------- | ------------------------------------- |------------------------------- |------------------------------------ | ----------------------------------- | ---------------------- |--------------------------- | ----------------------------------- | --------------------------- | -------------------------- | @@ -111,7 +110,7 @@ including 17 project representatives were gathered: | Chuck Burgess | PEAR | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | **Totals**: |13/3|15/1|15/1|13/3|14/2|15/1|14/2|15/1|14/2|14/2|15/1|16/0|15/1|15/1|15/1| -### 4.4.2. General non-representative voters +#### 4.4.2. General non-representative voters | Question | For | Against | Percentage For | | -------- | --- | ------- | -------------- | @@ -131,7 +130,7 @@ including 17 project representatives were gathered: | Keyword casing, only lower case | 124 | 2 | 98.39% | | Type keywords, short form only | 121 | 5 | 95.87% | -## 4.5. Multiline Function Arguments Mixed With Multiline Return +### 4.5. Multiline Function Arguments Mixed With Multiline Return A potential readability issue [was raised on the mailing list](https://groups.google.com/d/msg/php-fig/ULSL4gqK8GY/cgDELuPOCQAJ). We reviewed options for changes to the specification that could provide better readability and @@ -140,13 +139,13 @@ arguments and the return are both multiline. Instead it was pointed out that thi _already_ allows you to decide where you'd like to add blank lines and so we will leave it to the implementors to decide. -# 5. Changelog from PSR-2 +## 5. Changelog from PSR-2 Please note this changelog is not a verbose list of changes from PSR-2 but highlights the most notable changes. It should be considered a new specification and therefore you should read the specification for a full understanding of its contents. -## 5.1. New Statements +### 5.1. New Statements * Lowercase for all keywords - Section 2.5 * Short form for all type keywords - Section 2.5 @@ -165,7 +164,7 @@ specification for a full understanding of its contents. * Ternary operators - Section 6.3 * Anonymous classes - Section 8 -## 5.2. Clarifications and Errata +### 5.2. Clarifications and Errata * Adjust 'methods' to 'methods and functions' in a number of instances - Throughout * Adjust references to classes and interfaces to also include traits - Throughout @@ -176,34 +175,34 @@ specification for a full understanding of its contents. * PSR-2 errata statement about extending multiple interfaces - Section 4 * Forbid blank lines before/after closing/opening braces for classes - Section 4 -# 6. People +## 6. People -## 6.1. Editor: +### 6.1. Editor: * Korvin Szanto -## 6.2. Sponsor: +### 6.2. Sponsor: * Chris Tankersley -## 6.3. Working Group Members: +### 6.3. Working Group Members: * Alessandro Lai * Alexander Makarov * Michael Cullum * Robert Deutz -## 6.4. Special Thanks +### 6.4. Special Thanks * Michael Cullum for drafting the original specification * Alexandar Makarov for coordinating the draft during PHP-FIG 2.0 * Cees-Jan Kiewiet for moral support -# 7. Votes +## 7. Votes * **Entrance Vote:** https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/php-fig/P9atZLOcUBM/_jwkvlYKEAAJ * **Approval Vote:** https://groups.google.com/forum/#!topic/php-fig/1uaeSMaDGbk -# 8. Relevant Links +## 8. Relevant Links _**Note:** Order descending chronologically._ diff --git a/accepted/PSR-14-event-dispatcher-meta.md b/accepted/PSR-14-event-dispatcher-meta.md index 9a2f6a931..38a296af8 100644 --- a/accepted/PSR-14-event-dispatcher-meta.md +++ b/accepted/PSR-14-event-dispatcher-meta.md @@ -1,5 +1,4 @@ -Event Dispatcher Meta Document -============================== +# Event Dispatcher Meta Document ## 1. Summary diff --git a/accepted/PSR-14-event-dispatcher.md b/accepted/PSR-14-event-dispatcher.md index 7201117d4..e37d8d0fa 100644 --- a/accepted/PSR-14-event-dispatcher.md +++ b/accepted/PSR-14-event-dispatcher.md @@ -1,5 +1,4 @@ -Event Dispatcher -================ +# Event Dispatcher Event Dispatching is a common and well-tested mechanism to allow developers to inject logic into an application easily and consistently. diff --git a/accepted/PSR-15-request-handlers-meta.md b/accepted/PSR-15-request-handlers-meta.md index ff5bd984e..0837ba200 100644 --- a/accepted/PSR-15-request-handlers-meta.md +++ b/accepted/PSR-15-request-handlers-meta.md @@ -1,5 +1,4 @@ -HTTP Server Request Handlers Meta Document -========================================== +# HTTP Server Request Handlers Meta Document ## 1. Summary diff --git a/accepted/PSR-15-request-handlers.md b/accepted/PSR-15-request-handlers.md index f927d7b69..b7c51ae93 100644 --- a/accepted/PSR-15-request-handlers.md +++ b/accepted/PSR-15-request-handlers.md @@ -1,5 +1,4 @@ -HTTP Server Request Handlers -============================ +# HTTP Server Request Handlers This document describes common interfaces for HTTP server request handlers ("request handlers") and HTTP server middleware components ("middleware") @@ -24,7 +23,7 @@ interpreted as described in [RFC 2119][rfc2119]. [psr7]: https://www.php-fig.org/psr/psr-7/ [rfc2119]: http://tools.ietf.org/html/rfc2119 -### References +## References - [PSR-7][psr7] - [RFC 2119][rfc2119] diff --git a/accepted/PSR-16-simple-cache.md b/accepted/PSR-16-simple-cache.md index 5528cc3fe..903ea4bf6 100644 --- a/accepted/PSR-16-simple-cache.md +++ b/accepted/PSR-16-simple-cache.md @@ -1,5 +1,4 @@ -Common Interface for Caching Libraries -====================================== +# Common Interface for Caching Libraries This document describes a simple yet extensible interface for a cache item and a cache driver. @@ -14,9 +13,9 @@ interfaces/functionality first. [RFC 2119]: http://tools.ietf.org/html/rfc2119 -# 1. Specification +## 1. Specification -## 1.1 Introduction +### 1.1 Introduction Caching is a common way to improve the performance of any project, making caching libraries one of the most common features of many frameworks and @@ -30,7 +29,7 @@ standardized streamlined interface for common cases. It is independent of PSR-6 but has been designed to make compatibility with PSR-6 as straightforward as possible. -## 1.2 Definitions +### 1.2 Definitions Definitions for Calling Library, Implementing Library, TTL, Expiration and Key are copied from PSR-6 as the same assumptions are true. @@ -82,7 +81,7 @@ supported by implementing libraries: `{}()/\@:` if one stored `null` is not possible. This is the main deviation from PSR-6's assumptions. -## 1.3 Cache +### 1.3 Cache Implementations MAY provide a mechanism for a user to specify a default TTL if one is not specified for a specific cache item. If no user-specified default @@ -90,7 +89,7 @@ is provided implementations MUST default to the maximum legal value allowed by the underlying implementation. If the underlying implementation does not support TTL, the user-specified TTL MUST be silently ignored. -## 1.4 Data +### 1.4 Data Implementing libraries MUST support all serializable PHP data types, including: @@ -115,9 +114,9 @@ Compatibility with them is simply used as a baseline for acceptable object value If it is not possible to return the exact saved value for any reason, implementing libraries MUST respond with a cache miss rather than corrupted data. -# 2. Interfaces +## 2. Interfaces -## 2.1 CacheInterface +### 2.1 CacheInterface The cache interface defines the most basic operations on a collection of cache-entries, which entails basic reading, writing and deleting individual cache items. @@ -248,7 +247,7 @@ interface CacheInterface } ``` -## 2.2 CacheException +### 2.2 CacheException ```php @@ -264,7 +263,7 @@ interface CacheException } ``` -## 2.3 InvalidArgumentException +### 2.3 InvalidArgumentException ```php now()->getTimestamp(); ``` -# 2. Interfaces +## 2. Interfaces -## 2.1 ClockInterface +### 2.1 ClockInterface The clock interface defines the most basic operations to read the current time and date from the clock. It MUST return the time as a `\DateTimeImmutable`. diff --git a/accepted/PSR-3-logger-interface.md b/accepted/PSR-3-logger-interface.md index ec3f6cb10..a7e1fefc4 100644 --- a/accepted/PSR-3-logger-interface.md +++ b/accepted/PSR-3-logger-interface.md @@ -1,5 +1,4 @@ -Logger Interface -================ +# Logger Interface This document describes a common interface for logging libraries. diff --git a/accepted/PSR-4-autoloader-examples.md b/accepted/PSR-4-autoloader-examples.md index ee2606ec3..109cfe739 100644 --- a/accepted/PSR-4-autoloader-examples.md +++ b/accepted/PSR-4-autoloader-examples.md @@ -1,10 +1,8 @@ -Example Implementations of PSR-4 -================================ +# Example Implementations of PSR-4 The following examples illustrate PSR-4 compliant code: -Closure Example ---------------- +## Closure Example ```php