handpressed/substratum

WordPress boilerplate configured and managed with Composer and PHP dotenv. Based on Roots Bedrock.

WordPress Substratum

WordPress boilerplate configured and managed with Composer and PHP dotenv. Based on Roots Bedrock., _(*1)

• WordPress Substratum
  • Features
  • Requirements
  • Prerequisites
  • Installation
  • Configuration
    • Themes
    • Plugins
    • Constants
  • Directory Structure
  • See Also
  • Credit

Features

• Improved directory structure
• Dependency management with Composer
• Easy WordPress configuration with environment and constants files
• Environment variables with PHP dotenv
• Enhanced security (separated web root and secure passwords with roots/wp-password-bcrypt)

Requirements

• PHP 7.4+
• Composer

Prerequisites

Install Composer:, _(*2)

$ curl -sS https://getcomposer.org/installer | php && mv composer.phar /usr/local/bin/composer

Installation

$ composer create-project handpressed/substratum {directory}

$ cd {directory}

Replace {directory} with the name of your new WordPress project, e.g. its domain name., _(*3)

Configuration

Open the .env file and add your new project's home URL (WP_HOME) and database credentials (DB_NAME, DB_USER, DB_PASSWORD). You can also define the database $table_prefix (default is wp_) if required., _(*4)

Set your project's vhost document root to /path/to/{directory}/web., _(*5)

Themes

Add themes in web/app/themes as you would for a normal WordPress install., _(*6)

Plugins

WordPress Packagist is already registered in the composer.json file so any plugins from the WordPress Plugin Directory can easily be required., _(*7)

To require a plugin, add it under the require directive in composer.json or use composer require <namespace>/<packagename> from the command-line. If it's from WordPress Packagist then the namespace is always wpackagist-plugin, e.g.:, _(*8)

$ composer require wpackagist-plugin/wp-optimize

Whenever you add a new plugin or update WordPress core, run composer update to install your new packages., _(*9)

The plugins and mu-plugins directories are .gitignored by default since Composer manages them. If you want to add plugins to those directories that aren't managed by Composer, you need to update .gitignore to whitelist them:, _(*10)

!web/app/plugins/plugin-name, _(*11)

Note: Some plugins may create files or directories outside of their given scope, or even make modifications to wp-config.php and other files in the app directory. These files should be added to your .gitignore file as they are managed by the plugins themselves, which are managed by Composer. Any modifications to wp-config.php that are required should be moved to conf/wp-constants.php., _(*12)

Constants

Put custom core, theme and plugin constants in conf/wp-constants.php., _(*13)

Directory Structure

├── composer.json             → Manage versions of WordPress, plugins and dependencies
├── .env                      → WordPress environment variables (WP_HOME, DB_NAME, DB_USER, DB_PASSWORD required)
├── conf                      → WordPress configuration files
│   ├── wp-constants.php      → Custom core, theme and plugin constants
│   ├── wp-env-config.php     → Primary WordPress config file (wp-config.php equivalent)
│   └── wp-salts.php          → Authentication unique keys and salts (auto generated)
├── vendor                    → Composer packages (never edit)
└── web                       → Web root (vhost document root)
    ├── app                   → wp-content equivalent
    │   ├── mu-plugins        → Must-use plugins
    │   ├── plugins           → Plugins
    │   ├── themes            → Themes
    │   └── uploads           → Uploads
    ├── index.php             → Loads the WordPress environment and template (never edit)
    ├── wp-config.php         → Required by WordPress - loads conf/wp-env-config.php (never edit)
    └── wp                    → WordPress core (never edit)

See Roots Bedrock documentation for further details., _(*14)

See Also

WordPress Multitenancy Boilerplate, _(*15)

Credit

Inspired by roots/bedrock and wpscholar/wp-skeleton., _(*16)