doc/languages-frameworks/php.section.md

   1 # PHP {#sec-php}
   2
   3 ## User Guide {#ssec-php-user-guide}
   4
   5 ### Overview {#ssec-php-user-guide-overview}
   6
   7 Several versions of PHP are available on Nix, each of which having a
   8 wide variety of extensions and libraries available.
   9
  10 The different versions of PHP that nixpkgs provides are located under
  11 attributes named based on major and minor version number; e.g.,
  12 `php81` is PHP 8.1.
  13
  14 Only versions of PHP that are supported by upstream for the entirety
  15 of a given NixOS release will be included in that release of
  16 NixOS. See [PHP Supported
  17 Versions](https://www.php.net/supported-versions.php).
  18
  19 The attribute `php` refers to the version of PHP considered most
  20 stable and thoroughly tested in nixpkgs for any given release of
  21 NixOS - not necessarily the latest major release from upstream.
  22
  23 All available PHP attributes are wrappers around their respective
  24 binary PHP package and provide commonly used extensions this way. The
  25 real PHP 7.4 package, i.e. the unwrapped one, is available as
  26 `php81.unwrapped`; see the next section for more details.
  27
  28 Interactive tools built on PHP are put in `php.packages`; composer is
  29 for example available at `php.packages.composer`.
  30
  31 Most extensions that come with PHP, as well as some popular
  32 third-party ones, are available in `php.extensions`; for example, the
  33 opcache extension shipped with PHP is available at
  34 `php.extensions.opcache` and the third-party ImageMagick extension at
  35 `php.extensions.imagick`.
  36
  37 ### Installing PHP with extensions {#ssec-php-user-guide-installing-with-extensions}
  38
  39 A PHP package with specific extensions enabled can be built using
  40 `php.withExtensions`. This is a function which accepts an anonymous
  41 function as its only argument; the function should accept two named
  42 parameters: `enabled` - a list of currently enabled extensions and
  43 `all` - the set of all extensions, and return a list of wanted
  44 extensions. For example, a PHP package with all default extensions and
  45 ImageMagick enabled:
  46
  47 ```nix
  48 php.withExtensions ({ enabled, all }:
  49   enabled ++ [ all.imagick ])
  50 ```
  51
  52 To exclude some, but not all, of the default extensions, you can
  53 filter the `enabled` list like this:
  54
  55 ```nix
  56 php.withExtensions ({ enabled, all }:
  57   (lib.filter (e: e != php.extensions.opcache) enabled)
  58   ++ [ all.imagick ])
  59 ```
  60
  61 To build your list of extensions from the ground up, you can simply
  62 ignore `enabled`:
  63
  64 ```nix
  65 php.withExtensions ({ all, ... }: with all; [ imagick opcache ])
  66 ```
  67
  68 `php.withExtensions` provides extensions by wrapping a minimal php
  69 base package, providing a `php.ini` file listing all extensions to be
  70 loaded. You can access this package through the `php.unwrapped`
  71 attribute; useful if you, for example, need access to the `dev`
  72 output. The generated `php.ini` file can be accessed through the
  73 `php.phpIni` attribute.
  74
  75 If you want a PHP build with extra configuration in the `php.ini`
  76 file, you can use `php.buildEnv`. This function takes two named and
  77 optional parameters: `extensions` and `extraConfig`. `extensions`
  78 takes an extension specification equivalent to that of
  79 `php.withExtensions`, `extraConfig` a string of additional `php.ini`
  80 configuration parameters. For example, a PHP package with the opcache
  81 and ImageMagick extensions enabled, and `memory_limit` set to `256M`:
  82
  83 ```nix
  84 php.buildEnv {
  85   extensions = { all, ... }: with all; [ imagick opcache ];
  86   extraConfig = "memory_limit=256M";
  87 }
  88 ```
  89
  90 #### Example setup for `phpfpm` {#ssec-php-user-guide-installing-with-extensions-phpfpm}
  91
  92 You can use the previous examples in a `phpfpm` pool called `foo` as
  93 follows:
  94
  95 ```nix
  96 let
  97   myPhp = php.withExtensions ({ all, ... }: with all; [ imagick opcache ]);
  98 in {
  99   services.phpfpm.pools."foo".phpPackage = myPhp;
 100 };
 101 ```
 102
 103 ```nix
 104 let
 105   myPhp = php.buildEnv {
 106     extensions = { all, ... }: with all; [ imagick opcache ];
 107     extraConfig = "memory_limit=256M";
 108   };
 109 in {
 110   services.phpfpm.pools."foo".phpPackage = myPhp;
 111 };
 112 ```
 113
 114 #### Example usage with `nix-shell` {#ssec-php-user-guide-installing-with-extensions-nix-shell}
 115
 116 This brings up a temporary environment that contains a PHP interpreter
 117 with the extensions `imagick` and `opcache` enabled:
 118
 119 ```sh
 120 nix-shell -p 'php.withExtensions ({ all, ... }: with all; [ imagick opcache ])'
 121 ```
 122
 123 ### Installing PHP packages with extensions {#ssec-php-user-guide-installing-packages-with-extensions}
 124
 125 All interactive tools use the PHP package you get them from, so all
 126 packages at `php.packages.*` use the `php` package with its default
 127 extensions. Sometimes this default set of extensions isn't enough and
 128 you may want to extend it. A common case of this is the `composer`
 129 package: a project may depend on certain extensions and `composer`
 130 won't work with that project unless those extensions are loaded.
 131
 132 Example of building `composer` with additional extensions:
 133 ```nix
 134 (php.withExtensions ({ all, enabled }:
 135   enabled ++ (with all; [ imagick redis ]))
 136 ).packages.composer
 137 ```
 138
 139 ### Overriding PHP packages {#ssec-php-user-guide-overriding-packages}
 140
 141 `php-packages.nix` form a scope, allowing us to override the packages defined within. For example, to apply a patch to a `mysqlnd` extension, you can simply pass an overlay-style function to `php`’s `packageOverrides` argument:
 142
 143 ```nix
 144 php.override {
 145   packageOverrides = final: prev: {
 146     extensions = prev.extensions // {
 147       mysqlnd = prev.extensions.mysqlnd.overrideAttrs (attrs: {
 148         patches = attrs.patches or [] ++ [
 149           …
 150         ];
 151       });
 152     };
 153   };
 154 }
 155 ```