php: Document withExtensions + general improvements

doc/languages-frameworks/php.section.md

@@ -21,34 +21,67 @@ of a given NixOS release will be included in that release of
 NixOS. See [PHP Supported
 Versions](https://www.php.net/supported-versions.php).
 
-For packages we have `php.packages` that contains packages related
-for human interaction, notable example is `php.packages.composer`.
+Interactive tools built on PHP are put in `php.packages`; composer is
+for example available at `php.packages.composer`.
 
-For extensions we have `php.extensions` that contains most upstream
-extensions as separate attributes as well some additional extensions
-that tend to be popular, notable example is: `php.extensions.imagick`.
+Most extensions that come with PHP, as well as some popular
+third-party ones, are available in `php.extensions`; for example, the
+opcache extension shipped with PHP is available at
+`php.extensions.opcache` and the third-party ImageMagick extension at
+`php.extensions.imagick`.
 
-The different versions of PHP that nixpkgs fetch is located under
+The different versions of PHP that nixpkgs provides 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 majorly different parts of the PHP ecosystem in NixOS:
- - Command line utilities for human interaction. These comes from the
-   `php.packages.*` attributes.
- - PHP environments with different extensions enabled. These are
-   composed with `php.buildEnv` using an additional configuration file.
+A PHP package with specific extensions enabled can be built using
+`php.withExtensions`. This is a function which accepts an anonymous
+function as its only argument; the function should take one argument,
+the set of all extensions, and return a list of wanted extensions. For
+example, a PHP package with the opcache and ImageMagick extensions
+enabled:
+
+```nix
+php.withExtensions (e: with e; [ imagick opcache ])
+```
+
+If you want a PHP build with extra configuration in the `php.ini`
+file, you can use `php.buildEnv`. This function takes two named and
+optional parameters: `extensions` and `extraConfig`. `extensions`
+takes an extension specification equivalent to that of
+`php.withExtensions`, `extraConfig` a string of additional `php.ini`
+configuration parameters. For example, a PHP package with the opcache
+and ImageMagick extensions enabled, and `memory_limit` set to `256M`:
+
+```nix
+php.buildEnv {
+  extensions = e: with e; [ imagick opcache ];
+  extraConfig = "memory_limit=256M";
+}
+```
 
 ##### Example setup for `phpfpm`
 
-Example to build a PHP with the extensions `imagick` and `opcache`
-enabled. Then to configure it for the "foo" `phpfpm` pool:
+You can use the previous examples in a `phpfpm` pool called `foo` as
+follows:
+
+```nix
+let
+  myPhp = php.withExtensions (e: with e; [ imagick opcache ]);
+in {
+  services.phpfpm.pools."foo".phpPackage = myPhp;
+};
+```
 
 ```nix
 let
-  myPhp = php.buildEnv { exts = pp: with pp; [ imagick opcache ]; };
+  myPhp = php.buildEnv {
+    extensions = e: with e; [ imagick opcache ];
+    extraConfig = "memory_limit=256M";
+  };
 in {
   services.phpfpm.pools."foo".phpPackage = myPhp;
 };
@@ -60,5 +93,5 @@ This brings up a temporary environment that contains a PHP interpreter
 with the extensions `imagick` and `opcache` enabled.
 
 ```sh
-nix-shell -p 'php.buildEnv { exts = pp: with pp; [ imagick opcache ]; }'
+nix-shell -p 'php.buildEnv { extensions = e: with e; [ imagick opcache ]; }'
 ```

pkgs/top-level/php-packages.nix

@@ -26,8 +26,7 @@ in
 {
   inherit buildPecl;
 
-  # Packages are an attribute set meant for for human interaction and not
-  # extensions for the language itself.
+  # This is a set of interactive tools based on PHP.
   packages = {
     box = mkDerivation rec {
       version = "2.7.5";
@@ -293,8 +292,9 @@ in
 
 
 
-  # Extensions are an attribute set meant for for PHP extensions that extend the
-  # language rather than human interaction.
+  # This is a set of PHP extensions meant to be used in php.buildEnv
+  # or php.withExtensions to extend the functionality of the PHP
+  # interpreter.
   extensions = {
     apcu = buildPecl {
       version = "5.1.18";