php: Get rid of the phpXXbase attributes, update docs

Since the introduction of php.unwrapped there's no real need for the
phpXXbase attributes, so let's remove them to lessen potential
confusion and clutter. Also update the docs to make it clear how to
get hold of an unwrapped PHP if needed.

2020-04-29 13:45:48 +02:00

3.9 KiB

Raw Blame History

PHP

User Guide

Using PHP

Overview

Several versions of PHP are available on Nix, each of which having a wide variety of extensions and libraries available.

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.

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.

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.

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 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:

php.withExtensions ({ enabled, all }:
  enabled ++ [ all.imagick ])

To exclude some, but not all, of the default extensions, you can filter the enabled list like this:

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:

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 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:

php.buildEnv {
  extensions = { all, ... }: with all; [ imagick opcache ];
  extraConfig = "memory_limit=256M";
}

Example setup for `phpfpm`

You can use the previous examples in a phpfpm pool called foo as follows:

let
  myPhp = php.withExtensions ({ all, ... }: with all; [ opcache imagick ]);
in {
  services.phpfpm.pools."foo".phpPackage = myPhp;
};

let
  myPhp = php.buildEnv {
    extensions = { all, ... }: with all; [ imagick opcache ];
    extraConfig = "memory_limit=256M";
  };
in {
  services.phpfpm.pools."foo".phpPackage = myPhp;
};

Example usage with `nix-shell`

This brings up a temporary environment that contains a PHP interpreter with the extensions imagick and opcache enabled:

nix-shell -p 'php.withExtensions ({ all, ... }: with all; [ imagick opcache ])'

3.9 KiB Raw Blame History

PHP