From 43ad6ccc85ab92bb148d42ddf95878070026cba0 Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Mon, 19 May 2025 10:49:41 +0100
Subject: [PATCH 01/11] Run deploy:vendors if composer file exists

---
 recipe/wordpress.php | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/recipe/wordpress.php b/recipe/wordpress.php
index 6d12fa4..1851354 100644
--- a/recipe/wordpress.php
+++ b/recipe/wordpress.php
@@ -2,7 +2,6 @@
 
 namespace Deployer;
 
-require_once 'recipe/wordpress.php';
 require_once __DIR__ . '/common.php';
 
 // Shared files that need to persist between deployments
@@ -36,3 +35,15 @@
         'shared/web/wp-content/uploads/' => 'web/wp-content/uploads'
     ],
 ]);
+
+// Deployment tasks
+desc('Deploys your project');
+task('deploy', [
+    'deploy:prepare',
+    'deploy:publish',
+]);
+
+// Test if root Composer file exists
+if (testLocally('[ -f ./composer.json ]')) {
+    after('deploy:prepare', 'deploy:vendors');
+}

From d8b316bf0108446dc8890f23ca232226737a8ee5 Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Mon, 19 May 2025 12:56:38 +0100
Subject: [PATCH 02/11] Only normalise logs if logs:app exists

---
 tasks/logs.php | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/tasks/logs.php b/tasks/logs.php
index 8ed8429..2c046df 100644
--- a/tasks/logs.php
+++ b/tasks/logs.php
@@ -10,9 +10,11 @@
 option('search', null, InputOption::VALUE_OPTIONAL, 'Only return lines that match the search string');
 
 // Backward compatibility
-before('logs:app', function () {
-    normaliseLogFilesSetting();
-});
+if (commandExist('logs:app')) {
+    before('logs:app', function () {
+        normaliseLogFilesSetting();
+    });
+}
 
 desc('List available log files');
 task('logs:list', function () {

From 050298daa705f8194fe52cb424d51b42a8cdd658 Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Mon, 19 May 2025 13:01:43 +0100
Subject: [PATCH 03/11] Require common recipe

---
 recipe/wordpress.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/recipe/wordpress.php b/recipe/wordpress.php
index 1851354..2706c2d 100644
--- a/recipe/wordpress.php
+++ b/recipe/wordpress.php
@@ -2,6 +2,7 @@
 
 namespace Deployer;
 
+require_once 'recipe/common.php';
 require_once __DIR__ . '/common.php';
 
 // Shared files that need to persist between deployments

From 52bf762157c3c5ab7634e34ec5a7884522c7e0ba Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Tue, 20 May 2025 09:15:12 +0100
Subject: [PATCH 04/11] Fixes to WordPress recipe

---
 docs/README.md            |  1 +
 docs/installation.md      |  2 ++
 docs/recipes/wordpress.md | 58 +++++++++++++++++++++++++++++++++++++++
 recipe/wordpress.php      | 11 +++++++-
 tasks/logs.php            |  8 ++----
 5 files changed, 74 insertions(+), 6 deletions(-)
 create mode 100644 docs/recipes/wordpress.md

diff --git a/docs/README.md b/docs/README.md
index e5314ce..2b34d12 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,7 @@ This package contains [Deployer](https://deployer.org/) recipes used to help dep
 
 ## Recipes
 
+* [WordPress](recipes/wordpress.md)
 * [Static site](recipes/static.md) - 
 * [Slack](recipes/slack.md) - send a notification to Slack when a deployment is complete
 
diff --git a/docs/installation.md b/docs/installation.md
index 81709e7..f487d34 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -53,6 +53,8 @@ For deploying WordPress websites.
 cp vendor/studio24/deployer-recipes/examples/wordpress.php ./deploy.php
 ```
 
+See [WordPress docs](recipes/wordpress.md).
+
 [Source](../recipe/wordpress.php)
 
 ### Laravel:
diff --git a/docs/recipes/wordpress.md b/docs/recipes/wordpress.md
new file mode 100644
index 0000000..d5fc36c
--- /dev/null
+++ b/docs/recipes/wordpress.md
@@ -0,0 +1,58 @@
+# WordPress
+
+Deploy a WordPress site.
+
+## Recipe
+
+You can copy an example deployment file:
+
+```
+cp vendor/studio24/deployer-recipes/examples/wordpress.php ./deploy.php
+```
+
+## Tasks
+
+The static site recipe has 2 new tasks it runs:
+
+### WordPress
+
+You can install WordPress on deployment to `wordpress_path` by adding this config variable:
+
+```
+set('wordpress_path', 'web/wordpress');
+```
+
+And add this task to run:
+
+```
+after('deploy:prepare', 'deploy:wordpress_install');
+```
+
+### Composer
+
+If `composer.json` exists in the project root, the `deploy:vendors` task is automatically run.
+
+You can also run Composer in sub-folders, however, please note it is recommended you only use one root `composer.json` file in your project.
+
+To run Composer in sub-folders add:
+
+```php
+// Custom (non-root) composer installs
+set('composer_paths', [
+    'web/wp-content/plugins/s24-wp-image-optimiser'
+]);
+```
+
+And add this task to run:
+
+```php
+// Custom (non-root) composer installs
+after('deploy:prepare', 'vendors-subpath');
+```
+
+## Configuration
+
+### Optional configuration
+
+* `wordpress_path`: directory to install WordPress to relative to the release_path
+
diff --git a/recipe/wordpress.php b/recipe/wordpress.php
index 2706c2d..d624d3c 100644
--- a/recipe/wordpress.php
+++ b/recipe/wordpress.php
@@ -37,6 +37,15 @@
     ],
 ]);
 
+// Install WordPress
+task('deploy:wordpress_install', function() {
+    $wordPressPath = get('wordpress_path', false);
+    cd('{{release_path}}');
+    run(sprintf('mkdir -p %s', $wordPressPath));
+    $stage = get('stage');
+    run(sprintf('WP_ENV=%s wp core download --skip-content --path=%s', $stage, $wordPressPath));
+});
+
 // Deployment tasks
 desc('Deploys your project');
 task('deploy', [
@@ -45,6 +54,6 @@
 ]);
 
 // Test if root Composer file exists
-if (testLocally('[ -f ./composer.json ]')) {
+if (file_exists('./composer.json')) {
     after('deploy:prepare', 'deploy:vendors');
 }
diff --git a/tasks/logs.php b/tasks/logs.php
index 2c046df..8ed8429 100644
--- a/tasks/logs.php
+++ b/tasks/logs.php
@@ -10,11 +10,9 @@
 option('search', null, InputOption::VALUE_OPTIONAL, 'Only return lines that match the search string');
 
 // Backward compatibility
-if (commandExist('logs:app')) {
-    before('logs:app', function () {
-        normaliseLogFilesSetting();
-    });
-}
+before('logs:app', function () {
+    normaliseLogFilesSetting();
+});
 
 desc('List available log files');
 task('logs:list', function () {

From ba6dad721ac1f6ced73f83b6b800a0df36b8b276 Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Tue, 20 May 2025 09:25:21 +0100
Subject: [PATCH 05/11] Add wp command

---
 docs/recipes/wordpress.md | 25 +++++++++++++++++++++++++
 recipe/wordpress.php      | 22 +++++++++++++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/docs/recipes/wordpress.md b/docs/recipes/wordpress.md
index d5fc36c..dd8cfde 100644
--- a/docs/recipes/wordpress.md
+++ b/docs/recipes/wordpress.md
@@ -28,6 +28,8 @@ And add this task to run:
 after('deploy:prepare', 'deploy:wordpress_install');
 ```
 
+Please note this requires WP CLI to exist on the server.
+
 ### Composer
 
 If `composer.json` exists in the project root, the `deploy:vendors` task is automatically run.
@@ -50,6 +52,29 @@ And add this task to run:
 after('deploy:prepare', 'vendors-subpath');
 ```
 
+## WP CLI
+If you need to call any [WP CLI](https://wp-cli.org/) commands this recipe includes the `wp()` function to allow you to do this.
+
+This requires WP CLI to exist on the server.
+
+Usage:
+
+```php
+wp('command');
+```
+
+E.g. to run `wp core version`
+
+```php
+wp('core version');
+```
+
+This automatically sets the current environment using the `stage` variable. You can pass this manually as the second param:
+
+```php
+wp('core version', 'staging');
+```
+
 ## Configuration
 
 ### Optional configuration
diff --git a/recipe/wordpress.php b/recipe/wordpress.php
index d624d3c..a4699c9 100644
--- a/recipe/wordpress.php
+++ b/recipe/wordpress.php
@@ -43,8 +43,28 @@
     cd('{{release_path}}');
     run(sprintf('mkdir -p %s', $wordPressPath));
     $stage = get('stage');
-    run(sprintf('WP_ENV=%s wp core download --skip-content --path=%s', $stage, $wordPressPath));
+    // @see https://developer.wordpress.org/cli/commands/core/download/
+    wp(sprintf('wp core download --skip-content --path=%s', $wordPressPath), $stage);
+    writeln('Downloaded WordPress version: ');
+    wp('core version');
 });
+/**
+ * Run WP CLI
+ *
+ * @param string $command wp command, e.g. core download
+ * @param ?string $stage environment, e.g. production. Defaults to the current stage name
+ * @return void
+ * @throws Exception\Exception
+ * @throws Exception\RunException
+ * @throws Exception\TimeoutException
+ */
+function wp(string $command, ?string $stage = null)
+{
+    if (null === $stage) {
+        $stage = get('stage', 'production');
+    }
+    run(sprintf('WP_ENV=%s wp %s', $stage, $command), real_time_output: true);
+}
 
 // Deployment tasks
 desc('Deploys your project');

From cb5aeb1dabab1f608128ed90996a4e21f70d4e6e Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Tue, 20 May 2025 09:32:35 +0100
Subject: [PATCH 06/11] expand docs

---
 docs/recipes/wordpress.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/recipes/wordpress.md b/docs/recipes/wordpress.md
index dd8cfde..ca2dec9 100644
--- a/docs/recipes/wordpress.md
+++ b/docs/recipes/wordpress.md
@@ -34,6 +34,10 @@ Please note this requires WP CLI to exist on the server.
 
 If `composer.json` exists in the project root, the `deploy:vendors` task is automatically run.
 
+You can check this by running `dep tree deploy` which will show you the tasks to be run.
+
+#### Composer in sub-folders
+
 You can also run Composer in sub-folders, however, please note it is recommended you only use one root `composer.json` file in your project.
 
 To run Composer in sub-folders add:

From 7893c5a1d6f33d81b59aa21ec1412f6d77cb9952 Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Wed, 2 Jul 2025 09:54:26 +0100
Subject: [PATCH 07/11] Update WP update strategy

---
 docs/recipes/wordpress.md | 43 +++++++++++++++++++--------------------
 1 file changed, 21 insertions(+), 22 deletions(-)

diff --git a/docs/recipes/wordpress.md b/docs/recipes/wordpress.md
index ca2dec9..658ace0 100644
--- a/docs/recipes/wordpress.md
+++ b/docs/recipes/wordpress.md
@@ -16,16 +16,30 @@ The static site recipe has 2 new tasks it runs:
 
 ### WordPress
 
-You can install WordPress on deployment to `wordpress_path` by adding this config variable:
+WordPress core is not in source control and should have auto-updating enabled on the server.  
+
+You can set the WordPress path via:
 
 ```
 set('wordpress_path', 'web/wordpress');
 ```
 
-And add this task to run:
+This will add `wordpress_path` to `shared_dirs` and `writable_dirs` automatically.
+
+If WordPress does not exist in this path, it installs it.
+
+It does not update WordPress on deployment.
+
+If you need to manually update WordPress run:
 
+```bash
+dep wp core update staging 
 ```
-after('deploy:prepare', 'deploy:wordpress_install');
+
+You can update to a specific version via:
+
+```bash
+dep wp core update --version=<version> staging 
 ```
 
 Please note this requires WP CLI to exist on the server.
@@ -36,25 +50,10 @@ If `composer.json` exists in the project root, the `deploy:vendors` task is auto
 
 You can check this by running `dep tree deploy` which will show you the tasks to be run.
 
-#### Composer in sub-folders
-
-You can also run Composer in sub-folders, however, please note it is recommended you only use one root `composer.json` file in your project.
+#### Multiple Composer files in a WordPress project
 
-To run Composer in sub-folders add:
-
-```php
-// Custom (non-root) composer installs
-set('composer_paths', [
-    'web/wp-content/plugins/s24-wp-image-optimiser'
-]);
-```
-
-And add this task to run:
-
-```php
-// Custom (non-root) composer installs
-after('deploy:prepare', 'vendors-subpath');
-```
+It is not recommended to have more than one composer.json file in a project. If you do have one, you should move the 
+dependencies into the root composer file.
 
 ## WP CLI
 If you need to call any [WP CLI](https://wp-cli.org/) commands this recipe includes the `wp()` function to allow you to do this.
@@ -81,7 +80,7 @@ wp('core version', 'staging');
 
 ## Configuration
 
-### Optional configuration
+### Required configuration
 
 * `wordpress_path`: directory to install WordPress to relative to the release_path
 

From 779f17a443c8d4d15449a239f3b5d4376f25faa4 Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Wed, 2 Jul 2025 13:39:43 +0100
Subject: [PATCH 08/11] Expand docs for WP recipe

---
 docs/recipes/wordpress.md | 75 ++++++++++++++++++++++++++++++++++-----
 recipe/wordpress.php      | 38 +++++++++++++++-----
 2 files changed, 97 insertions(+), 16 deletions(-)

diff --git a/docs/recipes/wordpress.md b/docs/recipes/wordpress.md
index 658ace0..6d7fc5b 100644
--- a/docs/recipes/wordpress.md
+++ b/docs/recipes/wordpress.md
@@ -2,7 +2,52 @@
 
 Deploy a WordPress site.
 
-## Recipe
+[Source](../../recipe/wordpress.php)
+
+## Background
+
+We manage our WordPress sites using the following directory structure:
+
+```
+├── config
+|   ├── wp-config.base.php
+|   ├── wp-config.local.php
+|   ├── wp-config.production.php
+|   ├── wp-config.staging.php
+|   └── wp-config.development.php
+├── docs
+└── web
+|   ├── content
+|   |   ├── cache
+|   |   ├── mu-plugins
+|   |   ├── plugins
+|   |   ├── themes
+|   |   └── uploads
+|   ├── wordpress
+|   └── wp-config.php
+└── README.md
+```
+
+WordPress is not in source control and is installed to `web/wordpress`
+
+Source controlled plugins and themes are in the `web/content` folder.
+
+Configuration is stored in the `config` folder:
+* `wp-config.base.php` - base WordPress settings common across all enviroments
+* `wp-config.local.php` - sensitive settings such as database passwords (excluded from source control)
+* `wp-config.production.php` - production WordPress settings
+* `wp-config.staging.php` - staging WordPress settings
+* `wp-config.development.php` - development WordPress settings
+
+Documentation is stored in the `docs` folder.
+
+## Installation
+
+### Requirements
+
+This recipe requires [WP CLI](https://wp-cli.org/) to exist on the remote server.
+
+### Recipe
 
 You can copy an example deployment file:
 
@@ -16,19 +61,35 @@ The static site recipe has 2 new tasks it runs:
 
 ### WordPress
 
-WordPress core is not in source control and should have auto-updating enabled on the server.  
+WordPress core is not in source control and should have auto-update enabled on the server.  
 
-You can set the WordPress path via:
+You can change the WordPress path via:
 
 ```
 set('wordpress_path', 'web/wordpress');
 ```
 
-This will add `wordpress_path` to `shared_dirs` and `writable_dirs` automatically.
+If you change it from the default, you will need to add this path to `shared_dirs` and `writable_dirs`.
+
+#### WordPress update strategy
 
-If WordPress does not exist in this path, it installs it.
+To let WordPress run updates automatically the `WP_AUTO_UPDATE_CORE` setting must exist in your config:
 
-It does not update WordPress on deployment.
+```
+// Minor updates are enabled, development, and major updates are disabled (recommended for production)
+define('WP_AUTO_UPDATE_CORE', 'minor');
+
+// Development, minor, and major updates are all enabled
+define('WP_AUTO_UPDATE_CORE', true);
+```
+
+It is also possible to configure this via [filters](https://developer.wordpress.org/advanced-administration/upgrade/upgrading/#configuration-via-filters).
+
+#### On deployment
+
+On deployment, if WordPress does not exist in this path, it installs it. If WordPress does exist, no core updates are made on deployment.
+
+#### Manually running WordPress updates
 
 If you need to manually update WordPress run:
 
@@ -42,8 +103,6 @@ You can update to a specific version via:
 dep wp core update --version=<version> staging 
 ```
 
-Please note this requires WP CLI to exist on the server.
-
 ### Composer
 
 If `composer.json` exists in the project root, the `deploy:vendors` task is automatically run.
diff --git a/recipe/wordpress.php b/recipe/wordpress.php
index a4699c9..6fe1f0e 100644
--- a/recipe/wordpress.php
+++ b/recipe/wordpress.php
@@ -5,6 +5,9 @@
 require_once 'recipe/common.php';
 require_once __DIR__ . '/common.php';
 
+// Path to WordPress core
+set('wordpress_path', 'web/wordpress');
+
 // Shared files that need to persist between deployments
 set('shared_files', [
     'config/wp-config.local.php'
@@ -13,14 +16,16 @@
 // Shared directories that need to persist between deployments
 set('shared_dirs', [
     '.well-known',
-    'web/wp-content/uploads',
-    'web/wp-content/cache',
+    'web/content/uploads',
+    'web/content/cache',
+    '{{wordpress_path}}',
 ]);
 
 // Writable directories
 set('writable_dirs', [
-    'web/wp-content/uploads',
-    'web/wp-content/cache'
+    'web/content/uploads',
+    'web/content/cache',
+    '{{wordpress_path}}',
 ]);
 
 // Deployment and HTTP users
@@ -33,21 +38,29 @@
 // Array of remote => local file locations to sync to your local dev environment
 set('sync', [
     'images' => [
-        'shared/web/wp-content/uploads/' => 'web/wp-content/uploads'
+        'shared/web/content/uploads/' => 'web/content/uploads'
     ],
 ]);
 
 // Install WordPress
 task('deploy:wordpress_install', function() {
     $wordPressPath = get('wordpress_path', false);
+
     cd('{{release_path}}');
     run(sprintf('mkdir -p %s', $wordPressPath));
     $stage = get('stage');
-    // @see https://developer.wordpress.org/cli/commands/core/download/
-    wp(sprintf('wp core download --skip-content --path=%s', $wordPressPath), $stage);
-    writeln('Downloaded WordPress version: ');
+
+    // Install WP if not already installed
+    if (!testWp('core is-installed --path=%s 2>/dev/null', $wordPressPath)) {
+        // @see https://developer.wordpress.org/cli/commands/core/download/
+        wp(sprintf('core download --skip-content --path=%s', $wordPressPath), $stage);
+        writeln('Downloaded WordPress version: ');
+    } else {
+        writeln('Skipping WordPress download, current installed version: ');
+    }
     wp('core version');
 });
+
 /**
  * Run WP CLI
  *
@@ -66,10 +79,19 @@ function wp(string $command, ?string $stage = null)
     run(sprintf('WP_ENV=%s wp %s', $stage, $command), real_time_output: true);
 }
 
+function testWp(string $command, ?string $stage = null)
+{
+    if (null === $stage) {
+        $stage = get('stage', 'production');
+    }
+    return test(sprintf('WP_ENV=%s wp %s', $stage, $command));
+}
+
 // Deployment tasks
 desc('Deploys your project');
 task('deploy', [
     'deploy:prepare',
+    'deploy:wordpress_install',
     'deploy:publish',
 ]);
 

From 9d909d85ca482f2670d1169a80b24f5761100d37 Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Fri, 4 Jul 2025 15:55:21 +0100
Subject: [PATCH 09/11] Set path for wp version

---
 recipe/wordpress.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/recipe/wordpress.php b/recipe/wordpress.php
index 6fe1f0e..1514c6a 100644
--- a/recipe/wordpress.php
+++ b/recipe/wordpress.php
@@ -58,7 +58,7 @@
     } else {
         writeln('Skipping WordPress download, current installed version: ');
     }
-    wp('core version');
+    wp(sprintf('core version --path=%s', $wordPressPath), $stage);
 });
 
 /**

From 8ad5927ef97480525f2be43464538b1f11a8a843 Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Wed, 9 Jul 2025 23:43:12 +0100
Subject: [PATCH 10/11] Move deploy vendors if exists to a task to correctly
 test this, fix WP installed test

---
 recipe/wordpress.php | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/recipe/wordpress.php b/recipe/wordpress.php
index 1514c6a..d9fd305 100644
--- a/recipe/wordpress.php
+++ b/recipe/wordpress.php
@@ -50,17 +50,28 @@
     run(sprintf('mkdir -p %s', $wordPressPath));
     $stage = get('stage');
 
-    // Install WP if not already installed
-    if (!testWp('core is-installed --path=%s 2>/dev/null', $wordPressPath)) {
+    // Is WP already installed?
+    if (test(sprintf('[ -f %s/wp-blog-header.php ]', $wordPressPath))) {
+        writeln('Skipping WordPress download, current installed version: ');
+    } else {
+        // Install WP
         // @see https://developer.wordpress.org/cli/commands/core/download/
         wp(sprintf('core download --skip-content --path=%s', $wordPressPath), $stage);
         writeln('Downloaded WordPress version: ');
-    } else {
-        writeln('Skipping WordPress download, current installed version: ');
     }
     wp(sprintf('core version --path=%s', $wordPressPath), $stage);
 });
 
+// Optionally install Composer vendors if composer.json exists in project root
+task('deploy:vendors_if_exists', function() {
+    if (test('[ -f {{release_path}}/composer.json ]')) {
+        writeln('Install vendors, composer.json found');
+        invoke('deploy:vendors');
+    } else {
+        writeln('Skipping, no composer.json found');
+    }
+});
+
 /**
  * Run WP CLI
  *
@@ -79,23 +90,12 @@ function wp(string $command, ?string $stage = null)
     run(sprintf('WP_ENV=%s wp %s', $stage, $command), real_time_output: true);
 }
 
-function testWp(string $command, ?string $stage = null)
-{
-    if (null === $stage) {
-        $stage = get('stage', 'production');
-    }
-    return test(sprintf('WP_ENV=%s wp %s', $stage, $command));
-}
 
 // Deployment tasks
 desc('Deploys your project');
 task('deploy', [
     'deploy:prepare',
+    'deploy:vendors_if_exists',
     'deploy:wordpress_install',
     'deploy:publish',
 ]);
-
-// Test if root Composer file exists
-if (file_exists('./composer.json')) {
-    after('deploy:prepare', 'deploy:vendors');
-}

From 6f53520d584a899a3f8479d26bf2b5883696112a Mon Sep 17 00:00:00 2001
From: Simon R Jones <simon@studio24.net>
Date: Tue, 15 Jul 2025 10:50:21 +0100
Subject: [PATCH 11/11] Simplify WP setup

---
 docs/recipes/wordpress.md | 53 +++++++++++++++++++++++++++++----------
 recipe/wordpress.php      |  3 +--
 2 files changed, 41 insertions(+), 15 deletions(-)

diff --git a/docs/recipes/wordpress.md b/docs/recipes/wordpress.md
index 6d7fc5b..066f065 100644
--- a/docs/recipes/wordpress.md
+++ b/docs/recipes/wordpress.md
@@ -9,12 +9,6 @@ Deploy a WordPress site.
 We manage our WordPress sites using the following directory structure:
 
 ```
-├── config
-|   ├── wp-config.base.php
-|   ├── wp-config.local.php
-|   ├── wp-config.production.php
-|   ├── wp-config.staging.php
-|   └── wp-config.development.php
 ├── docs
 └── web
 |   ├── content
@@ -25,19 +19,18 @@ We manage our WordPress sites using the following directory structure:
 |   |   └── uploads
 |   ├── wordpress
 |   └── wp-config.php
+├── composer.json
+├── .env
 └── README.md
 ```
 
-WordPress is not in source control and is installed to `web/wordpress`
+WordPress is not in source control and is installed to `web/wordpress`. This folder is set to be writable to support auto-updates to WordPress core.
 
 Source controlled plugins and themes are in the `web/content` folder.
 
-Configuration is stored in the `config` folder:
-* `wp-config.base.php` - base WordPress settings common across all enviroments
-* `wp-config.local.php` - sensitive settings such as database passwords (excluded from source control)
-* `wp-config.production.php` - production WordPress settings
-* `wp-config.staging.php` - staging WordPress settings
-* `wp-config.development.php` - development WordPress settings
+Configuration is stored in `web/wp-config.php`
+
+Sensitive or environment configuration values are stored in a `.env` file in the project root. 
 
 Documentation is stored in the `docs` folder.
 
@@ -55,6 +48,40 @@ You can copy an example deployment file:
 cp vendor/studio24/deployer-recipes/examples/wordpress.php ./deploy.php
 ```
 
+### Loading environment variables in wp-config
+
+Local environment variables set in `.env` can be loaded in your wp-config file. 
+
+First install [vlucas/phpdotenv](https://packagist.org/packages/vlucas/phpdotenv) and include the Composer autoloader.
+
+Set your local environment variables in `.env` via name and value pairs:
+
+```
+DB_NAME="wp_database"
+S3_BUCKET="devbucket"
+```
+
+This can be loaded in your wp-config file via:
+
+```php
+$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
+$dotenv->load();
+```
+
+You can then reference the environment values in wp-config via `$_ENV`. E.g.
+
+```php
+define('DB_NAME', $_ENV['DB_NAME']);
+```
+
+You can also refer to other environment variables in your `.env` file via `${NAME}`. E.g. 
+
+```
+BASE_DIR="/var/webroot/project-root"
+CACHE_DIR="${BASE_DIR}/cache"
+```
+
+
 ## Tasks
 
 The static site recipe has 2 new tasks it runs:
diff --git a/recipe/wordpress.php b/recipe/wordpress.php
index d9fd305..d0107cf 100644
--- a/recipe/wordpress.php
+++ b/recipe/wordpress.php
@@ -10,7 +10,7 @@
 
 // Shared files that need to persist between deployments
 set('shared_files', [
-    'config/wp-config.local.php'
+    '.env'
 ]);
 
 // Shared directories that need to persist between deployments
@@ -18,7 +18,6 @@
     '.well-known',
     'web/content/uploads',
     'web/content/cache',
-    '{{wordpress_path}}',
 ]);
 
 // Writable directories