From c549e9f9d69c7e3a1730e836c14bd4c55edd86a7 Mon Sep 17 00:00:00 2001
From: Elis Hirwing <elis@hirwing.se>
Date: Thu, 30 Apr 2020 13:48:05 +0200
Subject: [PATCH 1/3] doc: Add PHP section

---
 doc/languages-frameworks/index.xml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 9364c764bbf9..a6f56d791c54 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -21,6 +21,7 @@
  <xi:include href="node.section.xml" />
  <xi:include href="ocaml.xml" />
  <xi:include href="perl.xml" />
+ <xi:include href="php.section.xml" />
  <xi:include href="python.section.xml" />
  <xi:include href="qt.xml" />
  <xi:include href="r.section.xml" />

From d2cb49c248daad8decb0caa77a76aa09aec2d9de Mon Sep 17 00:00:00 2001
From: Elis Hirwing <elis@hirwing.se>
Date: Fri, 1 May 2020 09:15:47 +0200
Subject: [PATCH 2/3] doc/php: Fix headline conflicts

---
 doc/languages-frameworks/php.section.md | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/doc/languages-frameworks/php.section.md b/doc/languages-frameworks/php.section.md
index 101f7b043fff..30c05b3b6143 100644
--- a/doc/languages-frameworks/php.section.md
+++ b/doc/languages-frameworks/php.section.md
@@ -1,10 +1,8 @@
-# PHP
+# PHP {#sec-php}
 
-## User Guide
+## User Guide {#ssec-php-user-guide}
 
-### Using PHP
-
-#### Overview
+### Overview {#ssec-php-user-guide-overview}
 
 Several versions of PHP are available on Nix, each of which having a
 wide variety of extensions and libraries available.
@@ -36,7 +34,7 @@ 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
+### Installing PHP with extensions {#ssec-php-user-guide-installing-with-extensions}
 
 A PHP package with specific extensions enabled can be built using
 `php.withExtensions`. This is a function which accepts an anonymous
@@ -89,7 +87,7 @@ php.buildEnv {
 }
 ```
 
-##### Example setup for `phpfpm`
+#### Example setup for `phpfpm` {#ssec-php-user-guide-installing-with-extensions-phpfpm}
 
 You can use the previous examples in a `phpfpm` pool called `foo` as
 follows:
@@ -113,7 +111,7 @@ in {
 };
 ```
 
-##### Example usage with `nix-shell`
+#### Example usage with `nix-shell` {#ssec-php-user-guide-installing-with-extensions-nix-shell}
 
 This brings up a temporary environment that contains a PHP interpreter
 with the extensions `imagick` and `opcache` enabled:

From e31a68ddba141e11f1569ae4d2cd0fb1a87fd5e4 Mon Sep 17 00:00:00 2001
From: Elis Hirwing <elis@hirwing.se>
Date: Fri, 1 May 2020 09:33:04 +0200
Subject: [PATCH 3/3] doc/php: Add example for installing composer with extra
 extensions

---
 doc/languages-frameworks/php.section.md | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/doc/languages-frameworks/php.section.md b/doc/languages-frameworks/php.section.md
index 30c05b3b6143..763beeb59358 100644
--- a/doc/languages-frameworks/php.section.md
+++ b/doc/languages-frameworks/php.section.md
@@ -62,7 +62,7 @@ To build your list of extensions from the ground up, you can simply
 ignore `enabled`:
 
 ```nix
-php.withExtensions ({ all, ... }: with all; [ opcache imagick ])
+php.withExtensions ({ all, ... }: with all; [ imagick opcache ])
 ```
 
 `php.withExtensions` provides extensions by wrapping a minimal php
@@ -94,7 +94,7 @@ follows:
 
 ```nix
 let
-  myPhp = php.withExtensions ({ all, ... }: with all; [ opcache imagick ]);
+  myPhp = php.withExtensions ({ all, ... }: with all; [ imagick opcache ]);
 in {
   services.phpfpm.pools."foo".phpPackage = myPhp;
 };
@@ -119,3 +119,19 @@ with the extensions `imagick` and `opcache` enabled:
 ```sh
 nix-shell -p 'php.withExtensions ({ all, ... }: with all; [ imagick opcache ])'
 ```
+
+### Installing PHP packages with extensions {#ssec-php-user-guide-installing-packages-with-extensions}
+
+All interactive tools use the PHP package you get them from, so all
+packages at `php.packages.*` use the `php` package with its default
+extensions. Sometimes this default set of extensions isn't enough and
+you may want to extend it. A common case of this is the `composer`
+package: a project may depend on certain extensions and `composer`
+won't work with that project unless those extensions are loaded.
+
+Example of building `composer` with additional extensions:
+```nix
+(php.withExtensions ({ all, enabled }:
+  enabled ++ (with all; [ imagick redis ]))
+).packages.composer
+```