php.buildEnv: Provide a list of currently enabled extensions

Rework withExtensions / buildEnv to handle currently enabled
extensions better and make them compatible with override. They now
accept a function with the named arguments enabled and all, where
enabled is a list of currently enabled extensions and all is the set
of all extensions. This gives us several nice properties:

 - You always get the right version of the list of currently enabled
   extensions

 - Invocations chain

 - It works well with overridden PHP packages - you always get the
   correct versions of extensions

As a contrived example of what's possible, you can add ImageMagick,
then override the version and disable fpm, then disable cgi, and
lastly remove the zip extension like this:

{ pkgs ? (import <nixpkgs>) {} }:
with pkgs;

let
  phpWithImagick = php74.withExtensions ({ all, enabled }: enabled ++ [ all.imagick ]);

  phpWithImagickWithoutFpm743 = phpWithImagick.override {
    version = "7.4.3";
    sha256 = "wVF7pJV4+y3MZMc6Ptx21PxQfEp6xjmYFYTMfTtMbRQ=";
    fpmSupport = false;
  };

  phpWithImagickWithoutFpmZip743 = phpWithImagickWithoutFpm743.withExtensions (
    { enabled, all }:
      lib.filter (e: e != all.zip) enabled);

  phpWithImagickWithoutFpmZipCgi743 = phpWithImagickWithoutFpmZip743.override {
    cgiSupport = false;
  };
in
  phpWithImagickWithoutFpmZipCgi743

1 files changed, 24 insertions, 21 deletions

diff --git a/doc/languages-frameworks/php.section.md b/doc/languages-frameworks/php.section.md
index a302a9a7f87d..31190f3b51a4 100644
--- a/doc/languages-frameworks/php.section.md
+++ b/doc/languages-frameworks/php.section.md
@@ -30,7 +30,7 @@ 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 provides is located under
+The different versions of PHP that nixpkgs provides are 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.
@@ -39,28 +39,31 @@ attributes named based on major and minor version number; e.g.,
 
 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:
+function as its only argument; the function should accept two named
+parameters: `enabled` - a list of currently enabled extensions and
+`all` - the set of all extensions, and return a list of wanted
+extensions. For example, a PHP package with all default extensions and
+ImageMagick enabled:
 
 ```nix
-php.withExtensions (e: with e; [ imagick opcache ])
+php.withExtensions ({ enabled, all }:
+  enabled ++ [ all.imagick ])
 ```
 
-Note that this will give you a package with _only_ opcache and
-ImageMagick, none of the other extensions which are enabled by default
-in the `php` package will be available.
+To exclude some, but not all, of the default extensions, you can
+filter the `enabled` list like this:
 
-To enable building on a previous PHP package, the currently enabled
-extensions are made available in its `enabledExtensions`
-attribute. For example, to generate a package with all default
-extensions enabled, except opcache, but with ImageMagick:
+```nix
+php.withExtensions ({ enabled, all }:
+  (lib.filter (e: e != php.extensions.opcache) enabled)
+  ++ [ all.imagick ])
+```
+
+To build your list of extensions from the ground up, you can simply
+ignore `enabled`:
 
 ```nix
-php.withExtensions (e:
-  (lib.filter (e: e != php.extensions.opcache) php.enabledExtensions)
-  ++ [ e.imagick ])
+php.withExtensions ({ all, ... }: with all; [ opcache imagick ])
 ```
 
 If you want a PHP build with extra configuration in the `php.ini`
@@ -73,7 +76,7 @@ and ImageMagick extensions enabled, and `memory_limit` set to `256M`:
 
 ```nix
 php.buildEnv {
-  extensions = e: with e; [ imagick opcache ];
+  extensions = { all, ... }: with all; [ imagick opcache ];
   extraConfig = "memory_limit=256M";
 }
 ```
@@ -85,7 +88,7 @@ follows:
 
 ```nix
 let
-  myPhp = php.withExtensions (e: with e; [ imagick opcache ]);
+  myPhp = php.withExtensions ({ all, ... }: with all; [ opcache imagick ]);
 in {
   services.phpfpm.pools."foo".phpPackage = myPhp;
 };
@@ -94,7 +97,7 @@ in {
 ```nix
 let
   myPhp = php.buildEnv {
-    extensions = e: with e; [ imagick opcache ];
+    extensions = { all, ... }: with all; [ imagick opcache ];
     extraConfig = "memory_limit=256M";
   };
 in {
@@ -105,8 +108,8 @@ in {
 ##### Example usage with `nix-shell`
 
 This brings up a temporary environment that contains a PHP interpreter
-with the extensions `imagick` and `opcache` enabled.
+with the extensions `imagick` and `opcache` enabled:
 
 ```sh
-nix-shell -p 'php.buildEnv { extensions = e: with e; [ imagick opcache ]; }'
+nix-shell -p 'php.withExtensions ({ all, ... }: with all; [ imagick opcache ])'
 ```