diff options
author | Elis Hirwing <elis@hirwing.se> | 2020-04-29 19:57:37 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-04-29 19:57:37 +0200 |
commit | 27b9b7b3af7297a63db72f045d4f1994ae5c8315 (patch) | |
tree | f92417d2fa6db6c231ffc703c934d447d5cd6898 /doc/languages-frameworks | |
parent | 3407b8c0fb25d312d65d1138ff62ca4efc8442cd (diff) | |
parent | 2535cdfe91b9e0100a2950a128648c2ba509eb8c (diff) |
Merge pull request #85026 from talyz/php_buildenv_override
php.buildEnv: Make the exported php package overridable, improve handling of currently enabled extensions, etc
Diffstat (limited to 'doc/languages-frameworks')
-rw-r--r-- | doc/languages-frameworks/php.section.md | 75 |
1 files changed, 43 insertions, 32 deletions
diff --git a/doc/languages-frameworks/php.section.md b/doc/languages-frameworks/php.section.md index a302a9a7f87d7..101f7b043fff6 100644 --- a/doc/languages-frameworks/php.section.md +++ b/doc/languages-frameworks/php.section.md @@ -9,18 +9,24 @@ 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`. +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. 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). +The attribute `php` refers to the version of PHP considered most +stable and thoroughly tested in nixpkgs for any given release of +NixOS - not necessarily the latest major release from upstream. + +All available PHP attributes are wrappers around their respective +binary PHP package and provide commonly used extensions this way. The +real PHP 7.4 package, i.e. the unwrapped one, is available as +`php74.unwrapped`; see the next section for more details. + Interactive tools built on PHP are put in `php.packages`; composer is for example available at `php.packages.composer`. @@ -30,39 +36,44 @@ 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 -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 +#### Installing PHP with extensions 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: + +```nix +php.withExtensions ({ enabled, all }: + (lib.filter (e: e != php.extensions.opcache) enabled) + ++ [ all.imagick ]) +``` -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: +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 ]) ``` +`php.withExtensions` provides extensions by wrapping a minimal php +base package, providing a `php.ini` file listing all extensions to be +loaded. You can access this package through the `php.unwrapped` +attribute; useful if you, for example, need access to the `dev` +output. The generated `php.ini` file can be accessed through the +`php.phpIni` attribute. + 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` @@ -73,7 +84,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 +96,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 +105,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 +116,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 ])' ``` |