Download the PHP package wierk/envpress without Composer

EnvPress

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
• Apply role and capability changes based on env vars
• 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

1. Setup Composer based WordPress project:

   The easiest way to do so, is creating a new Bedrock project using Composer:

2. Install this package via Composer:

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

   Set of env vars providing WordPress salts:

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

   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.

Connect Backing Services via 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

Query parameters:

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

Mailer URL

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.

Patching Roles and Capabilities

The WP_ROLES_PATCH environment variable allows role and capability changes to be defined using a JSON-encoded structure. Each top-level key is a role name, and each value describes changes for that role. Patches are applied only once per unique configuration using an internal hash.

Supported role object attributes:

• display_name - Optional display name used when creating a new role (see add_role)
• add_cap - Capability or array of capabilities to add and grant (see WP_Role::add_cap)
• remove_cap - Capability or array of capabilities to remove (see WP_Role::remove_cap)
• deny_cap - Capability or array of capabilities to add and explicitly deny (relevant for multi-role users)
• remove_role - Set to true to delete the role entirely (see remove_role)

Example:

This adds the capabilities create_users and list_users to the editor role, removes delete_users, and deletes the unused role.

Credits

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