Note The package has been renamed in version 12, see the upgrade guide.

WordPlate

WordPlate is a boilerplate. It's like building any other WordPress website with themes and plugins. Just with sprinkles on top.

Features
Installation
Configuration
Plugins
Vite.js
Mail
Upgrade Guide
FAQ
Acknowledgements

Features

WordPress + Composer = ♥️

WordPress is installed using Composer which allows WordPress to be updated by running composer update.
Environment Files

Similar to Laravel, WordPlate puts environment variables within an .env file such as database credentials.
WordPress Packagist

With WordPress Packagist you may manage your WordPress plugins and themes with Composer.
Must-use plugins

Don't worry about client deactivating plugins, must-use plugins is enabled by default.
Vite.js

With Vite you can quickly get up and running to build and minify your CSS and JavaScript.
Debugging

Familiar debugging helper functions are integrated such as dump() and dd().
Clean UI

WordPlate takes control over the WordPress dashboard and provides a better UX for your clients.
Security

With the roots/wp-password-bcrypt package we've replaced WordPress outdated and insecure MD5-based password hashing with the modern and secure bcrypt.

Installation

To use WordPlate, you need to have PHP 8.0+ and MySQL 5.7+ installed on your machine.

WordPlate utilizes Composer to manage its dependencies. So, before using WordPlate, make sure you have Composer installed on your machine.

Install WordPlate by issuing the Composer create-project command in your terminal:

composer create-project --prefer-dist vinkla/wordplate blog

Update the database credentials in the .env file:

DB_NAME=database
DB_USER=username
DB_PASSWORD=password

Serve your application using the built-in web server in PHP (or your server of choice) from the public directory:

php -S localhost:8000 -t public/

Visit your application in the browser:

http://localhost:8000/ - Your website.
http://localhost:8000/wordpress/wp-admin - The administration dashboard.

Configuration

Public Directory

After installing WordPlate, you should configure your web server's document / web root to be the public directory. The index.php in this directory serves as the front controller for all HTTP requests entering your application.

Salt Keys

The next thing you should do after installing WordPlate is adding salt keys to your environment file.

Typically, these strings should be 64 characters long. The keys can be set in the .env environment file. If you have not copied the .env.example file to a new file named .env, you should do that now. If the salt keys isn't set, your user sessions and other encrypted data will not be secure.

If you're lazy like us, visit our salt key generator and copy the randomly generated keys to your .env file.

Environment Configuration

It is often helpful to have different configuration values based on the environment where the application is running. For example, you may wish to use a different database locally than you do on your production server.

To make this a cinch, WordPlate utilizes the Dotenv PHP package. In a fresh WordPlate installation, the root directory of your application will contain a .env.example file. If you install WordPlate via Composer, this file will automatically be renamed to .env. Otherwise, you should rename the file manually.

Your .env file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would get exposed.

Read more about environment variables in Laravel's documentation:

Plugins

WordPress Packagist

We've integrated WordPress Packagist which makes it possible to install plugins with Composer. WordPress Packagist mirrors the WordPress plugin and theme directories as a Composer repository.

Install the desired plugins using wpackagist-plugin as the vendor name. Packages are installed in the public/plugins directory.

composer require wpackagist-plugin/clean-image-filenames

This is an example of how your composer.json file might look like:

"require": {
    "wpackagist-plugin/clean-image-filenames": "^1.3"
}

Please visit WordPress Packagist for more information and examples.

Must Use Plugins

Must-use plugins (a.k.a. mu-plugins) are plugins installed in a special directory inside the content folder and which are automatically enabled on all sites in the installation.

To install plugins into into the mu-plugins directory, add the plugin name to the installer-paths in your composer.json file:

"installer-paths": {
    "public/mu-plugins/{$name}": [
        "type:wordpress-muplugin",
        "wpackagist-plugin/clean-image-filenames",
    ]
}

Install the plugin using wpackagist-plugin as the vendor name.

composer require wpackagist-plugin/clean-image-filenames

The plugin should now be installed in the public/mu-plugins directory.

Headache

Headache is an easy-to-swallow painkiller plugin for WordPress. It is included by default in WordPlate. It removes a lot of default WordPress stuff you just can't wait to get rid of. It removes meta tags such as feeds, version numbers and emojis.

Vite.js

Vite is a build tool that aims to provide a faster and leaner development experience for modern web projects. Vite is opinionated and comes with sensible defaults out of the box, but is also highly extensible via its Plugin API and JavaScript API with full typing support.

To get started with Vite, please visit the documentation.

# Start the dev server...
npm run dev

# Build for production...
npm run build

Mail

If you want to add custom SMTP credentials, you may add the following to your functions.php file:

// Register SMTP email with HTML support.
add_action('phpmailer_init', function (PHPMailer $mail) {
    $mail->isSMTP();
    $mail->SMTPAutoTLS = false;
    $mail->SMTPAuth = env('MAIL_USERNAME') && env('MAIL_PASSWORD');
    $mail->SMTPSecure = env('MAIL_ENCRYPTION', 'tls');
    $mail->Host = env('MAIL_HOST');
    $mail->Port = env('MAIL_PORT', 587);
    $mail->Username = env('MAIL_USERNAME');
    $mail->Password = env('MAIL_PASSWORD');
    return $mail;
});

add_filter('wp_mail_content_type', fn () => 'text/html');
add_filter('wp_mail_from_name', fn () => env('MAIL_FROM_NAME', 'Example'));
add_filter('wp_mail_from', fn () => env('MAIL_FROM_ADDRESS', 'hello@example.com'));

Then add the environment variables to your .env file:

MAIL_FROM_ADDRESS=
MAIL_FROM_NAME=
MAIL_HOST=
MAIL_PASSWORD=
MAIL_PORT=
MAIL_USERNAME=

If you're using a service such as MailHog locally, you'll need to turn of encryption:

MAIL_ENCRYPTION=null

Upgrade Guide

WordPlate has archived the wordplate/framework package and moved everything into the boilerplate repository instead. We keep this list for any old application out there which needs to be upgraded.

Upgrading from 11 to 12

Update the composer.json file:

"require": {
-   "wordplate/framework": "^11.1",
+   "composer/installers": "^2.1",
+   "johnpbloch/wordpress-core-installer": "^2.0",
+   "johnpbloch/wordpress-core": "^6.0",
+   "roots/bedrock-autoloader": "^1.0",
+   "roots/wp-password-bcrypt": "^1.1",
+   "symfony/http-foundation": "^6.0",
+   "symfony/var-dumper": "^6.0",
+   "vlucas/phpdotenv": "^5.4"
}

Replace your public/wp-config.php file with the one in this repository. Remember to save any custom constants defined in your wp-config.php file.
Add the src/helpers.php file from this repository and autoload it in the composer.json file:
```
+"autoload": {
+    "files": [
+        "src/helpers.php"
+    ]
+}
```
Run composer update in the root of your project.

Upgrading from 10 to 11

WordPlate now requires PHP 8.0 or later.
Bump the version number in the composer.json file to ^11.0.
Run composer update in the root of your project.

Upgrading from 9 to 10

WordPlate now requires PHP 7.4 or later.
Bump the version number in the composer.json file to ^10.0.
Rename WP_ENV to WP_ENVIRONMENT_TYPE in the environment file.
Rename WP_THEME to WP_DEFAULT_THEME in the environment file.
Rename WP_URL to WP_HOME in the environment file (if it exists).

If you're using the WP_CACHE environment variable you'll need to define it in the public/wp-config.php file:

$application->run();

+define('WP_CACHE', env('WP_CACHE', false));

$table_prefix = env('DB_TABLE_PREFIX', 'wp_');

Optional: Rename WP_PREFIX to DB_TABLE_PREFIX in the following files:
- .env
- .env.example
- public/wp-config.php
Run composer update in the root of your project.

Upgrading from 8 to 9

Bump the version number in the composer.json file to ^9.0.
Copy the public/mu-plugins/mu-plugins.php file into your project.
Update the public/.gitignore file to allow the new mu-plugins.php file:
```
-mu-plugins/
+mu-plugins/*
+!mu-plugins/mu-plugins.php
```
Run composer update in the root of your project.

Upgrading from 7 to 8

WordPlate now requires PHP 7.2 or later.
Bump the version number in the composer.json file to ^8.0.

Note: WordPlate 8.0 requires WordPress 5.3 or later.
Laravel's helper functions is now optional in WordPlate. If you want to use the functions, install the laravel/helpers package, with Composer, in the root of your project:
```
composer require laravel/helpers
```
Laravel's collections are now optional in WordPlate. If you want to use collections, install the tightenco/collect package, with Composer, in the root of your project:
```
composer require tightenco/collect
```
The mix helper function is now optional in WordPlate. If you want to use the function, install the ibox/mix-function package, with Composer, in the root of your project:
```
composer require ibox/mix-function
```
Replace any usage of asset, stylesheet_url and template_url functions with WordPress's get_theme_file_uri function.
Replace any usage of stylesheet_path and template_path functions with WordPress's get_theme_file_path function .
The base_path and template_slug functions have been removed.
Run composer update in the root of your project.

Upgrading from 6 to 7

Bump the version number in the composer.json file to ^7.0.

Note: WordPlate 7.0 requires WordPress 5.0 or later.
Update the realpath(__DIR__) to realpath(__DIR__.'/../') in the wp-config.php file.
If your public directory isn't named public, add the following line to the wp-config.php file:
```
$application->setPublicPath(realpath(__DIR__));
```
Run composer update in the root of your project.

Upgrading from 5 to 6

Bump the version number in the composer.json file to ^6.0.
Update the realpath(__DIR__.'/../') to realpath(__DIR__) in the wp-config.php file.
Run composer update in the root of your project.

Upgrading from 4 to 5

Bump the version number in the composer.json file to ^5.0.
Copy and paste the contents of the wp-config.php file into your application.

Note: Make sure you don't overwrite any of your custom constants.
Run composer update in the root of your project.

FAQ

Can I add WordPress constants to the environment file?

This is possible by updating the public/wp-config.php file after the WordPlate application have been created.

define('WP_DISABLE_FATAL_ERROR_HANDLER', env('WP_DISABLE_FATAL_ERROR_HANDLER', false));

+define('WP_ALLOW_MULTISITE', env('WP_ALLOW_MULTISITE', true));

Then you may add the constant to the .env file.

WP_DEFAULT_THEME=wordplate
+WP_ALLOW_MULTISITE=true

Can I rename the public directory?

If you want to rename the public directory you'll need to update the wp-config.php file in two places:

-realpath(__DIR__ . '/../public');
+realpath(__DIR__ . '/../public_html');

Please note that you also have to update your composer.json file with your new public directory path before you can run composer update again.

Can I rename the WordPress directory?

By default WordPlate will put the WordPress in public/wordpress. If you want to change this there are a couple of steps you need to go through. Let's say you want to change the default WordPress location to public/wp:

Update the wordpress-install-dir path in your composer.json file.
Update wordpress to wp in wordplate/public/.gitignore.
Update the last line in the public/index.php file to:
```
require __DIR__.'/wp/wp-blog-header.php';
```
Update the WP_DIR environment variable in the .env file to wp.
If you're using WP-CLI, update the path in the wp-cli.yml file to public/wp.
Remove the public/wordpress directory if it exist and then run composer update.

Can I rename the theme directory?

For most applications you may leave the theme directory as it is. If you want to rename the wordplate theme to something else you'll also need to update the WP_DEFAULT_THEME environment variable in the .env file.

Can I use WordPlate with Laravel Valet?

If you're using Laravel Valet together with WordPlate, you may use our local valet driver. Create a file named LocalValetDriver.php in the root of your project and copy and paste the class below:

<?php

declare(strict_types=1);

final class LocalValetDriver extends BasicValetDriver
{
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return is_dir($sitePath.'/public/wordpress');
    }
    
    /** @return false|string */
    public function isStaticFile(string $sitePath, string $siteName, string $uri): 
    {
        $staticFilePath = $sitePath . '/public' . $uri;

        if ($this->isActualFile($staticFilePath)) {
            return $staticFilePath;
        }

        return false;
    }

    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
    {
        $_SERVER['PHP_SELF'] = $uri;
        $_SERVER['SERVER_NAME'] = $_SERVER['HTTP_HOST'];

        if (strpos($uri, '/wordpress/') === 0) {
            if (is_dir($sitePath . '/public' . $uri)) {
                $uri = $this->forceTrailingSlash($uri);

                return $sitePath . '/public' . $uri . '/index.php';
            }

            return $sitePath . '/public' . $uri;
        }

        return $sitePath . '/public/index.php';
    }

    private function forceTrailingSlash(string $uri): string
    {
        if (substr($uri, -1 * strlen('/wordpress/wp-admin')) == '/wordpress/wp-admin') {
            header('Location: ' . $uri . '/');
            die;
        }

        return $uri;
    }
}

Acknowledgements

WordPlate wouldn't be possible without these amazing open-source projects.

License

The WordPlate package is open-sourced software licensed under the MIT license.

vermontdevil/wordplate