README

A PHP package streamlining the configuration of modern and secure WordPress instances using a standard set of environment variables.

Key Features

Designed for Composer based WordPress setups (e.g. Bedrock)
Static wp-config.php
Load environment variables from .env files with vlucas/phpdotenv
Gather facts from trusted proxies (e.g. Load Balancers)
Attach backing services using URLs (e.g. MySQL, SMTP)
Configure Multisite Networks using environment variables
Disable native WordPress features using flags (e.g. XML-RPC, comments, oEmbed)
Harden WordPress by default: Disable file modifications and hide version

Motivation

The standard setup of WordPress involves maintaining a wp-config.php file for setting basic configuration options, such as paths, the database connection, and security salts. Except for the actual configuration values, the source code of this file is repeated for each instance with little to no variation. Other common configurations, such as SMTP server credentials and disabling XML-RPC, must be handled separately, far away from wp-config.php, in a custom (child) theme or using multiple third-party plugins.

This package is designed to simplify the configuration process and lessen the maintenance workload for the majority of WordPress instances. It relies on a standard set of environment variables (see list below), rather than boilerplate PHP code, to configure an instance.

Getting Started

Setup Composer based WordPress project:

The easiest way to do so, is creating a new Bedrock project using Composer:
```
composer create-project roots/bedrock
```
Install this package via Composer:
```
composer require wierk/envpress
```

Set up environment variables:

Configure environment variables in the web server or PHP config (recommended for production) or, alternatively, add them to a file named .env in the root of the project (common for development).

Minimal set of environment variables to run a WordPress instance:

WP_HOME      = https://example.com
WP_SITEURL   = https://example.com/wp
DATABASE_URL = mysql://username:password@hostname:port/database

Set of env vars providing WordPress salts:

SALT_AUTH_KEY         = put your unique phrase here
SALT_SECURE_AUTH_KEY  = put your unique phrase here
SALT_LOGGED_IN_KEY    = put your unique phrase here
SALT_NONCE_KEY        = put your unique phrase here
SALT_AUTH_SALT        = put your unique phrase here
SALT_SECURE_AUTH_SALT = put your unique phrase here
SALT_LOGGED_IN_SALT   = put your unique phrase here
SALT_NONCE_SALT       = put your unique phrase here

Replace the content of wp-config.php with the following:

<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
\EnvPress\EnvPress::createWithBedrockDefaults(__DIR__)->bootstrap();
require_once ABSPATH . 'wp-settings.php';

Starting from the Bedrock boilerplate, the root config directory may now be removed.

Environment Variables

EnvPress sets up a WordPress instance using a collection of environment variables, listed in the following table. In cases where an environment variable is absent, the corresponding default value is used. These default values are selected to closely resemble a standard, unmodified WordPress installation to avoid unintentional changes. Env vars prefixed APP_ are explicitly reserved for the underlying application and will never be used by this package.

Backing Service URLs

Backing services such as databases, caching systems, or SMTP servers are attached using URLs. These URLs consolidate all the essential connection details, like host name, port, access credentials, and other relevant parameters, into a singular, manageable string.

In URLs, if a user name or password contains special characters ($&+,/:;=?@), they must be URL encoded.

Database URL/DSN

DATABASE_URL=mysql://${USER}:${PASS}@${HOST}:${PORT}/${DATABASE}?ssl-mode=REQUIRED

Query parameters:

ssl-mode - If set to REQUIRED, requires an encrypted connection and fails, if one cannot be established.

Mailer URL

MAILER_URL=smtp://${USER}:${PASS}@${HOST}:${PORT}?encryption=tls

Query parameters:

encryption - Define the encryption to use on the SMTP connection: tls (default) or ssl.
from - If present, force the from email address to a specified one, overwriting MAILER_FROM_ADDRESS.

Credits

Created and maintained by Wierk and contributors. Released under the MIT license.

wierk / envpress

Maintainers

Details