diff options
author | talyz <kim.lindberger@gmail.com> | 2020-04-03 18:56:12 +0200 |
---|---|---|
committer | talyz <kim.lindberger@gmail.com> | 2020-04-05 16:46:05 +0200 |
commit | b5c59cebc6194684545fcd9c272d91d9af6ec8e9 (patch) | |
tree | f14c5ec266382de0d0fdc6cff577216b4771dbe5 | |
parent | b4d289a7ae319a3f19935a3a3820c876caa83b33 (diff) | |
download | nixpkgs-b5c59cebc6194684545fcd9c272d91d9af6ec8e9.tar nixpkgs-b5c59cebc6194684545fcd9c272d91d9af6ec8e9.tar.gz nixpkgs-b5c59cebc6194684545fcd9c272d91d9af6ec8e9.tar.bz2 nixpkgs-b5c59cebc6194684545fcd9c272d91d9af6ec8e9.tar.lz nixpkgs-b5c59cebc6194684545fcd9c272d91d9af6ec8e9.tar.xz nixpkgs-b5c59cebc6194684545fcd9c272d91d9af6ec8e9.tar.zst nixpkgs-b5c59cebc6194684545fcd9c272d91d9af6ec8e9.zip |
php: Document withExtensions + general improvements
-rw-r--r-- | doc/languages-frameworks/php.section.md | 63 | ||||
-rw-r--r-- | pkgs/top-level/php-packages.nix | 8 |
2 files changed, 52 insertions, 19 deletions
diff --git a/doc/languages-frameworks/php.section.md b/doc/languages-frameworks/php.section.md index 18d4ee83709..cc98c760aec 100644 --- a/doc/languages-frameworks/php.section.md +++ b/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 ]; }' ``` diff --git a/pkgs/top-level/php-packages.nix b/pkgs/top-level/php-packages.nix index bb4a5a946c1..b6e8c6be2e8 100644 --- a/pkgs/top-level/php-packages.nix +++ b/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"; |