====== 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

===== Introduction =====

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.


===== Proposal =====

==== PHP tooling ====

PHP tooling (the PHP.net website, first-party marketing material, the documentation generator project PhD, etc.) MAY make use of existing third party libraries and tools (collectively "libraries"), provided that the library meets all of the "Inclusion" criteria, and does not meet any of the "Exclusion" criteria.

Inclusion criteria:

  - 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.)
  - The library provides targeted, necessary functionality.
  - The library is a recognized de facto standard, or one of a small number of de facto standards, in its problem space.
  - The library is available under an MIT, BSD, LGPL, or GPL license.


Exclusion criteria:

  - The library is a "full" framework
  - The library is available under an AGPL license.
  - The library is not available under an Open Source license.
  - 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.

==== PHP documentation ====

Documentation hosted on the PHP.net website, first-party marketing material, and other public facing text (collectively "documentation") MAY reference and link to third party libraries and tools (collectively "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:

  - The library must have a stable >= 1.0 release, and have had one for at least a year.
  - 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.
  - 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.
  - The library is available under an Free Software license (as defined by the Free Software Foundation).
  - 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:

  - 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.
  - The library is not available under an Open Source license.
  - The library has shown no meaningful activity for one year prior to its first mention.
  - 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.

==== Conflict resolution ====

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 either use or reference.  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.

==== Initially approved libraries ====

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


===== Discussion =====

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 even 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.
  * 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.
  * Symfony, Laravel, Slim, Yii, etc. - While Laravel and Symfony are the market leaders in PHP frameworks, 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.
  * WordPress, Drupal, TYPO3, Concrete5, etc. - As with frameworks, this market is far too dynamic for us to document without tipping the scales.  We therefore should mention none, and use none.
  * Serializers - This is another market with many viable players of various sizes, so we should not "endorse" any in particular.  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.

===== Proposed Voting Choices =====

Simple 2/3 majority vote.


===== References =====

Links to external references, discussions or RFCs

===== Rejected Features =====