PHP RFC: Policy on 3rd party code

• Version: 0.9
• Date: 2013-02-24 (use today's date here)
• Author: Larry Garfield (larry@garfieldtech.com)
• Status: Draft
• First Published at: http://wiki.php.net/rfc/third-party-code

The PHP project has had a long-standing but unwritten, vague, and inconsistently-applied proscription against mentioning or using third-party PHP projects, on the grounds that it implies some sort of endorsement over other third-party projects. While the desire to avoid endorsing a particular competing project is reasonable, it many cases it is actively harmful to the PHP project, its documentation, and the PHP ecosystem. “PHP” is not simply the php-src repository, and PHP.net is the home page of the PHP ecosystem, not of the php-src repository, whether we approve of that evolution or not.

This RFC proposes an updated heuristic for when and how third party code may be used or referenced, and a resolution process in case of conflict.

PHP tooling refers to the code behind the PHP.net website, the documentation generator project PhD, the PHP wiki, and other similar systems. In general, “PHP code run by PHP.net.”

Documentation refers to objective information about PHP, the PHP language, the PHP standard library, and PHP ecosystem hosted on PHP.net. This may include reference material, tutorials, FAQs, and similar.

Marketing material refers to content on PHP.net or similar sites intended to promote or evangelize PHP the language or ecosystem.

Libraries refers to existing third party code packages or tools, either C extensions or PHP code, maintained by someone other than the PHP Internals team. It may also refer to non-profit PHP ecosystem organizations, such as the PHP Foundation or PHP-FIG.

Approved license refers to a license approved by the Free Software Foundation as Free Software. Of note, this excludes the PHP License, but as that is virtually never used for user-space code that is a non-issue.

PHP tooling MAY make use third party libraries, provided that the library meets all of the “Inclusion” criteria, and does not meet any of the “Exclusion” criteria.

Inclusion criteria:

1. The library must have a stable >= 1.0 release, and have had one for at least a year. (This is to ensure it has longevity.)
2. The library provides targeted, necessary functionality.
3. The library is a recognized de facto standard, or one of a small number of de facto standards, in its problem space.
4. The library is available under an Approved License.

Exclusion criteria:

1. The library is a “full” framework or application
2. The library is not available under an Approved License.
3. The library has shown no meaningful activity for one year prior to its first inclusion.

PHP tooling maintainers MAY use their judgement to determine if a library meets the above criteria, but SHOULD be conservative in their interpretation of whether or not a library satisfies the necessary criteria.

Documentation MAY reference and link to third party libraries, provided that the library meets all of the “Inclusion” criteria, and does not meet any of the “Exclusion” criteria. Additionally, the language used to refer to the library must also follow the criteria below.

Inclusion criteria:

1. The library must have a stable >= 1.0 release, and have had one for at least a year.
2. The library provides a use that is commonly needed by numerous types of projects, and a reasonable estimate would make it relevant to at least 40% of the PHP ecosystem.
3. The library is a recognized de facto standard, or one of a small number of de facto standards, in its problem space. If there are a small number of de facto standard libraries, then all should be listed and given equal weight.
4. The library is available under an Approved License.
5. The language used to describe the library does not imply that the PHP Project is involved in or specifically recommends the library over some other.

Exclusion criteria:

1. The library is one of many (more than ~4) viable options in its problem space, even if it is the most common of those many options.
2. The library is a “full” application or framework.
3. The library is not available under an Approved License.
4. The library has shown no meaningful activity for one year prior to its first mention.
5. The library is not of broad interest to the PHP ecosystem.

PHP documentation maintainers MAY use their judgement to determine if a library meets the above criteria, but SHOULD be conservative in their interpretation of whether or not a library satisfies the necessary criteria.

Marketing material MAY reference and link to third party libraries, provided that the library meets all of the “Inclusion” criteria, and does not meet any of the “Exclusion” criteria. Additionally, the language used to refer to the library must also follow the criteria below.

Inclusion criteria:

1. The library must have a stable >= 1.0 release, and have had one for at least a year.
2. The library provides a use that is commonly needed by numerous types of projects, and a reasonable estimate would make it relevant to at least 25% of the PHP ecosystem.
3. The library is a recognized de facto standard, or one of a small number of de facto standards, in its problem space. If there are a small number of de facto standard libraries, then all should be listed and given equal weight.
4. The library MAY be a full application or framework, provided its mention clearly does not specifically endorse the library. If many options exist in a space that bears mention, at least the three most common should be given equal exposure.
5. The library is available under an Approved License.
6. The language used to describe the library does not imply that the PHP Project is involved in or specifically recommends the library over some other.

Exclusion criteria:

1. The library is not available under an Approved License.
2. The library has shown no meaningful activity for one year prior to its first mention.
3. The library is not of broad interest to the PHP ecosystem.

PHP marketing material maintainers MAY use their judgement to determine if a library meets the above criteria, but SHOULD be conservative in their interpretation of whether or not a library satisfies the necessary criteria.

Should there be a reasonable dispute as to whether a given library satisfies the criteria above, an RFC may be posted to explicitly approve the library for one or more of the above cases. The RFC MUST have a 2/3 vote threshold to approve the library. If the library is rejected, it may be revisited after six months, like any other RFC.

The following packages are explicitly approved for use by this RFC, as they meet all of the criteria above.

• Composer
• PHPUnit
• Xdebug
• PHPStan
• Psalm
• Any library or PSR published by the PHP-FIG

Additionally, for historical reasons, Docuwiki is explicitly approved for use despite it being a “full” application.

This section is non-normative. It is a discussion of how this RFC author feels the above criteria would apply to various packages, as a way to demonstrate the expected thought process.

• Composer - It's 2024. Composer is the sole project in its market, and is used by the overwhelming majority of the PHP ecosystem. It is the only way to access the vast majority of the PHP ecosystem. We should use it, we should document it, we should promote it.
• Symfony/Yaml - I am not aware of any other Yaml library in widespread use. This is the de facto standard way to parse YAML in PHP, and has been for years. It would be fine for PHP tooling to make use of it. However, whether or not it is of broad enough interest to be mentioned in the documentation is debatable. I would likely lean no. It may make sense in marketing, potentially.
• Ramsey/uuid - This has long been a staple of UUID handling in PHP. It would be fine for tooling to use. More recently, Symfony/UUID has also come along, and though less used is still stable. If the documentation were to mention UUID handling, it would be prudent to list both as options. However, it is debatable if UUID handling is of broad enough interest for documentation. It may make sense in marketing.
• Symfony, Laravel, Slim, Yii,WordPress, Drupal, TYPO3, etc. - While Laravel and Symfony are the market leaders in PHP frameworks, and WordPress dominates the CMS-oid market, it is a highly dynamic market, with literally dozens of players that have reasonable use. That makes listing them in the documentation without “playing favorites” essentially impossible, and therefore none should be listed by name. They should also not be used directly to build any PHP tooling, again to avoid the appearance of endorsement. However, it may make sense to list several of them in passing in marketing material, explicitly noting that they are just some among many options.
• Serializers - This is another market with many viable players of various sizes, so we should not “endorse” any in particular via the documentation. It may or may not make sense for marketing material, but definitely not documentation. However, any of the major supported ones are fair game for tooling to leverage as appropriate.
• PHPStan, Psalm - These are, to my knowledge, the only serious players in the static analysis space that meet the above criteria. It's entirely reasonable, and encouraged, for tooling to make use of them. We can also document both under the heading of “static analysis tools, they're a good idea”, without saying people should use one instead of the other. This would be fair game for both documentation and marketing material.

1. It likely would not come up, but are we OK with using AGPL code in PHP tooling? It's not like any of our code is inaccessible.

Simple 2/3 majority vote.

Links to external references, discussions or RFCs