diff options
Diffstat (limited to 'doc/languages-frameworks/php.section.md')
| -rw-r--r-- | doc/languages-frameworks/php.section.md | 63 |
1 files changed, 48 insertions, 15 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 ]; }' ``` |