diff options
author | Elis Hirwing <elis@hirwing.se> | 2020-03-22 15:33:48 +0100 |
---|---|---|
committer | talyz <kim.lindberger@gmail.com> | 2020-04-05 16:45:04 +0200 |
commit | e4cee802ad2adbfd586e919bfe9712bdee07e371 (patch) | |
tree | 126fbe4e5841426a148cc29c98ba38820a13f6b6 /doc | |
parent | 0dc95728bac36c3711009e0611b7b31c402a959e (diff) |
doc/php: Add initial documentation for PHP
Diffstat (limited to 'doc')
-rw-r--r-- | doc/languages-frameworks/php.section.md | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/doc/languages-frameworks/php.section.md b/doc/languages-frameworks/php.section.md new file mode 100644 index 000000000000..9924946a45c1 --- /dev/null +++ b/doc/languages-frameworks/php.section.md @@ -0,0 +1,75 @@ +# 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 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`. + +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). + +As for packages we have `php.packages` that contains a bunch of +attributes where some are suitable as extensions (notable example: +`php.packages.imagick`). And some are more suitable for command +line use (notable example: `php.packages.composer`). + +We have a special section within `php.packages` called +`php.packages.exts` that contain certain PHP modules that may not +be part of the default PHP derivation (example: +`php.packages.exts.opcache`). + +The `php.packages.exts.*` attributes are official extensions which +originate from the mainline PHP project, while other extensions within +the `php.packages.*` attribute are of mixed origin (such as `pecl` +and other places). + +The different versions of PHP that nixpkgs fetch 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 different kinds of things you could install: + - A command line utility. Simply refer to it via + `php*.packages.*`, and it automatically comes with the necessary + PHP environment, certain extensions and libraries around it. + - A PHP interpreter with certain extensions available. The `php` + attribute provides `php.buildEnv` that allows you to wrap the PHP + derivation with an additional config file that makes PHP import + additional libraries or dependencies. + +##### Example setup for `phpfpm` + +Example to build a PHP with `imagick` and `opcache` enabled, and +configure it for the "foo" `phpfpm` pool: + +```nix +let + myPhp = php.buildEnv { exts = pp: with pp; [ imagick exts.opcache ]; }; +in { + services.phpfpm.pools."foo".phpPackage = myPhp; +}; +``` + +##### Example usage with `nix-shell` + +This brings up a temporary environment that contains a PHP interpreter +with `imagick` and `opcache` enabled. + +```sh +nix-shell -p 'php.buildEnv { exts = pp: with pp; [ imagick exts.opcache ]; }' +``` |