WordPress Boilerplate

Project: Part 1, Part 2, Part 3

---

Introduction

This Composer configuration sets up a base project structure, that includes a WordPress backend with a configuration plugin and a custom base theme.

While setting up the project, Composer creates a copy of a base Vue.js theme (app/themes/wordpress-theme-vue) with the same name as the root directory. Use the .env file in the root directory to define the environment variables and configure the backend system with the configuration plugin methods (app/mu-plugin/wordpress-theme-configuration), as usual, inside of the functions.php file, that is located in the theme directory.

Additionally, to load MU-Plugins from subdirectories Composer adds an autoloader for MU-Plugins (app/mu-plugin/wordpress-mu-plugin-autoloader.php). WordPress only looks for PHP files right inside the MU-Plugins directory, and not for files in subdirectories (unlike for normal plugins).

Note: Useful plugins and Composer scripts are available or editable inside the composer.json file.

Requirements

• Composer: ^2.*
• PHP: ^7.*
• Maria DB: ^10.* || MySQL: ^8.*
• Apache: ^2.4.*

⚠️ ACF Pro ⚠️

If you want to use ACF Pro and have an existing key, please update the "dist": {.. "url": "https:..&k=<<ACF_KEY>>.." } key inside of the composer.json file (~[25,89]). Replace <<ACF_KEY>> with your own key. If you won't use ACF Pro, you can delete the ACF Pro requirements with:

composer config --unset repositories.advanced-custom-fields/advanced-custom-fields-pro && composer remove advanced-custom-fields/advanced-custom-fields-pro

Maria DB

The requirements for the database are defined in the .env file. WordPress creates the database automatically if the database does not exist. Otherwise, WordPress loads the existing database.

WordPress Salts

The WordPress Salts in the .env file are fetched and placed automatically, for each project/installation.

JWT Authentication

The secret key in the .env file for JWT Authentication for WP REST API is created and placed automatically, for each project/installation.

Note: It is optional to use the custom WordPress REST API from the wordpress-theme-configuration MU-Plugin.

Docker

If you need a tiny Docker setup to test the project, checkout my Docker PHP:8.2-Apache MySQL repo.

Custom Hooks

To work with the custom hook directory, you need to set the hooksPath inside the git config, after each clone. To do so, you need to call the following command. Afterward, you can work with custom GutHub hooks inside the ./hooks directory.

git config core.hooksPath hooks

Getting Started!

If you need an example project to work with this configuration, please checkout my Getting Started! in Part 3.

---

Installation

Copy or fetch the composer.json file in your project root directory and run composer update to generate the required composer.lock file. Or install all the required files with the command composer install in your terminal, if the composer.lock file already exists. After the installation is done, edit the .env and .htaccess file and start creating your custom WordPress theme.

• copy-paste or fetch the composer.json file in your project root directory
• run composer update or composer install to generate the required files
• set up .env variables and the KITT_TLD and KITT_SLD constants in the .htaccess file

To fetch the composer.json file directly in your project root directory, you can use the following curl command.

curl --header "PRIVATE-TOKEN: <github_access_token>" "https://raw.githubusercontent.com/dark-kitt/wordpress-boilerplate/main/composer.json" > composer.json

Or save your private access token in a curl header file, e.g. ~/.curl/github and include your specific header into your command.

# ~/.curl/github
PRIVATE-TOKEN: <github_access_token>

curl -H @"$HOME/.curl/github" "https://raw.githubusercontent.com/dark-kitt/wordpress-boilerplate/main/composer.json" > composer.json

common composer cmds

composer install
composer update
# package control
composer require verdor/package
composer remove verdor/package

# add / remove repositories (type = vcs, composer ... etc)
composer config repositories.verdor/package type https://example.com/verdor/package.git
composer config --unset repositories.verdor/package

composer clear-cache
composer show -i (installed packages)

example vhosts.conf

# Tiny example vhosts config file
<VirtualHost *:80>
  ServerName api.example.kitt
  ServerAlias www.api.example.kitt
  ServerAdmin webmaster@localhost

  DocumentRoot /var/www/html/web
  <Directory /var/www/html/web>
    Options Indexes FollowSymlinks
    AllowOverride All
    Require all granted
  </Directory>

  ErrorLog ${APACHE_LOG_DIR}/error.log
  CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

<VirtualHost *:80>
  ServerName example.kitt
  ServerAlias www.example.kitt
  ServerAdmin webmaster@localhost

  DocumentRoot /var/www/html/web/app/themes
  <Directory /var/www/html/web/app/themes>
    Options Indexes FollowSymlinks
    AllowOverride All
    Require all granted
  </Directory>

  ErrorLog ${APACHE_LOG_DIR}/error.log
  CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
# Create custom local domain HTTPS
# NOTE: mkcert is required
# https://github.com/FiloSottile/mkcert
# Create ./ssl directory and run inside => mkcert localhost 127.0.0.1 ::1 example.kitt \*.example.kitt
# Add the new certificates => mkcert -install
# Don't forget to set up the local /etc/hosts file => 127.0.0.1 example.kitt api.example.kitt
# <VirtualHost *:443>
#   # example.kitt:8443
#   ServerName example.kitt
#   ServerAlias www.example.kitt

#   SSLEngine on
#   SSLCertificateFile /var/www/html/ssl/cert.pem
#   SSLCertificateKeyFile /var/www/html/ssl/key.pem

#   ServerAdmin webmaster@localhost
#   DocumentRoot /var/www/html/web/app/themes

#   ErrorLog ${APACHE_LOG_DIR}/error.log
#   CustomLog ${APACHE_LOG_DIR}/access.log combined
# </VirtualHost>

# <VirtualHost *:443>
#   # api.example.kitt:8443
#   ServerName api.example.kitt
#   ServerAlias www.api.example.kitt

#   SSLEngine on
#   SSLCertificateFile /var/www/html/ssl/cert.pem
#   SSLCertificateKeyFile /var/www/html/ssl/key.pem

#   ServerAdmin webmaster@localhost
#   DocumentRoot /var/www/html/web

#   ErrorLog ${APACHE_LOG_DIR}/error.log
#   CustomLog ${APACHE_LOG_DIR}/access.log combined
# </VirtualHost>

---

.env

Replace the existing default values with your specific project configuration. The WordPress Salts and the secret key for JWT Authentication for WP REST API are created and placed automatically (keys for each installation).

Note: The secret key for JWT Authentication for WP REST API is required for the custom WordPress REST API wordpress-theme-configuration MU-Plugin. If you won't use the custom WordPress REST API Method from the wordpress-theme-configuration MU-Plugin, you can ignore the secret key or use it on your own.

Note: Additionally, if you use the example Apache configuration above WP_HOME (http://example.dev) can not be equal to WP_SITEURL (http://api.example.dev/wp), because of the custom WordPress REST API, which is defined by the wordpress-theme-configuration MU-Plugin. The ENV_SITEURL (http://api.example.dev/) constant is used to configure other additional stuff.

Don't forget to edit the .htacces file (KITT_TLD and KITT_SLD constants).

Note: The WP_DEBUG_LOG constant is set to /storage/logs/wp_error.log. If you use Docker and want to see the WordPress error logs after you called the docker logs -f <container> >/dev/null command for php logs. Set the path to /dev/stderr and the WordPress error logs should be visible.

---

Scripts

composer htpasswd-www

or

composer htpasswd-web

The htpasswd-www or htpasswd-web script adds a .htpasswd file in the /www directory of the theme or in the /web directory of this project. Additionally, the scripts will also add a .htacces file with the required information to each directory, if it doesn't exist. If it exists htpasswd-www or htpasswd-web will only add the required information at the end of the file.

To edit the user and the password information, open the composer.json file and replace user and password with your specific login data inside of the htpasswd-www ([145,135]) or htpasswd-web ([140,79]) script.

Note: Don't push your .htpasswd and .htacces files with your local AuthUserFile information to the live server.

---

composer set-up-project

set-up-project creates .env, ./web/index.php, ./web/wp-config.php, ./web/.htaccess, ./web/media, ./web/storage, ./web/storage/cache, ./web/storage/logs and ./web/storage/lang, if they are don't exists. Additionally, the script will execute the clear-base-theme, clear-theme-configuration and clear-mu-autoloader scripts, if the plugins are installed.

---

composer default-env-file

creates the default .env in the root directory of this project. Note: If a .env file already exists, this script will overwrite the existing one.

---

composer default-index-file

creates the default index.php file in the /web/ directory of this project. Note: If an index.php file already exists, this script will overwrite the existing one.

---

composer default-wp-config-file

creates the default wp-config.php file in the /web/ directory of this project. Note: If a wp-config.php file already exists, this script will overwrite the existing one.

---

composer default-htaccess-file

creates the default .htaccess file in the /web/ directory of this project. Note: If a .htaccess file already exists, this script will overwrite the existing one.

---

composer default-base-theme-files

copies the base Vue.js theme in the same directory (app/themes/$name) with the name as the root directory. Afterwards, it creates all necessary default files for WordPress if they don't already exist.

---

composer clear-base-theme

deletes all Git and Composer data in the copy of the base Vue.js theme directory (app/themes/$name) if they exist.

---

composer clear-mu-autoloader

deletes the Autoloader MU-Plugin in the app/mu-plugin directory, but not the mu-plugin-autoloader.php file in the same directory.

---

composer clear-theme-configuration

deletes all Git and Composer data in the app/mu-plugin/wordpress-theme-configuration directory if they exist.

---

---

License

---

Includes

• Roots / WordPress
• Roots / wp-password-bcrypt
• PHP dotenv
• Advanced Custom Fields: Pro
• Advanced Custom Fields: Extended
• JWT Authentication for WP REST API
• dark-kitt / wordpress-theme-vue
• dark-kitt / wordpress-theme-configuration
• dark-kitt / wordpress-wp-mu-plugin-autoloader