doc/php: Add initial documentation for PHP

.github/CODEOWNERS

@@ -178,6 +178,7 @@
 /nixos/tests/prometheus-exporters.nix                        @WilliButz
 
 # PHP
-/pkgs/development/interpreters/php  @etu
-/pkgs/top-level/php-packages.nix    @etu
-/pkgs/build-support/build-pecl.nix  @etu
+/doc/languages-frameworks/php.section.md @etu
+/pkgs/development/interpreters/php       @etu
+/pkgs/top-level/php-packages.nix         @etu
+/pkgs/build-support/build-pecl.nix       @etu

doc/languages-frameworks/php.section.md

@@ -0,0 +1,75 @@
+# PHP
+
+## User Guide
+
+### Using PHP
+
+#### Overview
+
+Several versions of PHP are available on Nix, each of which having a
+wide variety of extensions and libraries available.
+
+The attribute `php` refers to the version of PHP considered most
+stable and thoroughly tested in nixpkgs for any given release of
+NixOS. Note that while this version of PHP may not be the latest major
+release from upstream, any version of PHP supported in nixpkgs may be
+utilized by specifying the desired attribute by version, such as
+`php74`.
+
+Only versions of PHP that are supported by upstream for the entirety
+of a given NixOS release will be included in that release of
+NixOS. See [PHP Supported
+Versions](https://www.php.net/supported-versions.php).
+
+As for packages we have `php.packages` that contains a bunch of
+attributes where some are suitable as extensions (notable example:
+`php.packages.imagick`). And some are more suitable for command
+line use (notable example: `php.packages.composer`).
+
+We have a special section within `php.packages` called
+`php.packages.exts` that contain certain PHP modules that may not
+be part of the default PHP derivation (example:
+`php.packages.exts.opcache`).
+
+The `php.packages.exts.*` attributes are official extensions which
+originate from the mainline PHP project, while other extensions within
+the `php.packages.*` attribute are of mixed origin (such as `pecl`
+and other places).
+
+The different versions of PHP that nixpkgs fetch is located under
+attributes named based on major and minor version number; e.g.,
+`php74` is PHP 7.4 with commonly used extensions installed,
+`php74base` is the same PHP runtime without extensions.
+
+#### Installing PHP with packages
+
+There's two different kinds of things you could install:
+ - A command line utility. Simply refer to it via
+   `php*.packages.*`, and it automatically comes with the necessary
+   PHP environment, certain extensions and libraries around it.
+ - A PHP interpreter with certain extensions available.  The `php`
+   attribute provides `php.buildEnv` that allows you to wrap the PHP
+   derivation with an additional config file that makes PHP import
+   additional libraries or dependencies.
+
+##### Example setup for `phpfpm`
+
+Example to build a PHP with `imagick` and `opcache` enabled, and
+configure it for the "foo" `phpfpm` pool:
+
+```nix
+let
+  myPhp = php.buildEnv { exts = pp: with pp; [ imagick exts.opcache ]; };
+in {
+  services.phpfpm.pools."foo".phpPackage = myPhp;
+};
+```
+
+##### Example usage with `nix-shell`
+
+This brings up a temporary environment that contains a PHP interpreter
+with `imagick` and `opcache` enabled.
+
+```sh
+nix-shell -p 'php.buildEnv { exts = pp: with pp; [ imagick exts.opcache ]; }'
+```