Local WordPress Installation ​

This will explain how to set up a local WordPress installation to work with Forme. This assumes you have already set up your local development environment.

To begin with, set up a fresh database to use for your project.

Forme Base ​

Our recommended set up method is to use Forme Base, which is our base project server boilerplate.

Make sure your local environment is set up first then run:

# with forme codegen
forme base new project-name

# or with composer
composer create-project forme/base project-name

This will:

1. Install the latest version of WordPress into the public folder (requires wp cli, curl or wget)
2. Add the wp-packagist composer repository
3. Install the wikimedia merge plugin so that we can pull in plugin and theme dependencies into the main vendor folder
4. Add the correct installer paths for plugins and themes if pulled in via composer
5. Install ACF (not the pro version)
6. Install the Symfony var-dumper component
7. Install Whoops error Pages
8. Install WP debug bar
9. Initialise wp-config.php, including prompting for your DB credentials, adding the FORME_PRIVATE_ROOT const, setting WP_ENV to development and requiring autoload. (requires wp cli)
10. Create a blank .env file
11. Include package.json with a basic workspaces configuration

You will then want to:

• Edit .env if need be
• Composer require any existing plugins or themes you need, or symlink local work into wp-content and composer update
• git init and then keep this in version control during development
• set up your wordpress site as usual in your browser or via wp-cli

You might need to delete composer.lock before installing any plugins or themes which depend on the merge plugin feature for the first time.

Valet Driver ​

If you use Valet for local development, we've got a driver for that. You should cp this into your local valet configuration if you haven't already:

cp utils/FormeServerValetDriver.php ~/.config/valet/Drivers/FormeServerValetDriver.php

If you're using Valet Linux your Valet configuration is in ~/.valet and your drivers are therefore in ~/.valet/Drivers/. You will need to edit the driver slightly to remove namespacing and types since the implementation is quite far behind the upstream project as at today's date (2024-06-04)

Wikimedia Merge Plugin ​

The wikimedia/composer-merge-plugin plugin is configured to look for plugins and themes who's directory name ends in -plugin and -theme respectively. This is currently the default naming pattern for forme plugin and theme projects.

It matches naively so if you happen to be using a third party plugin or theme whose directory name ends in -plugin or -theme that contains a composer.json that you don't want to merge, you should change its directory name to something else.

Without Base ​

If you don't want to use Base and prefer to do things more manually, you should first create an empty directory for your site.

Then start with this composer.json and copy it to the root directory of your site.

To initialise the project and also install the latest version of WordPress, run:

composer create-project

This will install WordPress, plus all the basic required packages and plugins, including the various dev utilities. It will also prompt you for DB credentials and sort out your wp-config.php settings, and a blank .env file.

composer.json ​

The composer file includes a few useful scripts, some of which will run on create project. These will:

1. Install the latest version of WordPress into the public folder (requires wp cli, curl or wget)
2. Initialise wp-config.php, including prompting for your DB credentials, adding the FORME_PRIVATE_ROOT const, setting WP_ENV to development and requiring autoload. (requires wp cli)
3. Create a blank .env file

This means that as long as you have either wget, curl or wp cli installed, WordPress will get installed in the public directory. The vendor folder stays in the root directory, which is necessary for security in a live environment. We can use the same composer file when we deploy.

The composer file also includes:

• necessary settings for wp-packagist
• the wikimedia merge plugin so that we can pull in plugin and theme dependencies into the main vendor folder
• correct installer paths for plugins and themes if pulled in via composer
• the ACF dependency - we include this dependency here rather than in the core framework library as you might want to change this to ACF pro, which isn't available via the WordPress plugin directory.

plus a few useful debugging utilities including:

• Symfony var-dumper component - use dump() instead of var_dump() to get pretty debugging output.
• Whoops - nicely formatted user friendly error pages ftw
• WP debug bar - A WP plugin with some very useful debugging output

You can find out more about debugging here.

Without WordPress ​

If you don't need to install WordPress because you've already installed it some other way, you can just run:

composer install

wp-config.php ​

If you didn't use the automated configuration, you'll need to edit public/wp-config.php manually.

Straight after ABSPATH, you should define FORME_PRIVATE_ROOT. In a classic WP install, this is one up from your public folder (i.e. one up from ABSPATH).

# Local
define('FORME_PRIVATE_ROOT', ABSPATH . '../');

You should require the autoload just after that definition:

require_once FORME_PRIVATE_ROOT . 'vendor//autoload.php';

You can also set env to development if relevant:

define('WP_ENV', 'development');

The framework uses this to determine whether Whoops should be enabled.

Bedrock ​

With Base and the suggested set up above, we're not trying to manage WordPress itself via Composer - the philosophy is to try to stick mostly to the traditional WordPress file and folder strucuture. If you do want to manage WordPress with composer, you should take a look at Bedrock.

If you're running a Bedrock WordPress install, you will have to copy over the relevant/missing merge-plugin, require and require-dev bits below into the default Bedrock composer.json .

"require": {
        ...
        "wikimedia/composer-merge-plugin": "^2.0",
        "wpackagist-plugin/advanced-custom-fields": "^5.9"
    },
    "require-dev": {
        ...
        "symfony/var-dumper": "^5.1",
        "wpackagist-plugin/debug-bar": "^1.0",
        "filp/whoops": "^2.9"
    },
    "merge-plugin": {
            "include": [
                "web/app/plugins/*-plugin/composer.json",
                "web/app/themes/*-theme/composer.json"
            ],
            "recurse": true,
            "replace": false,
            "merge-dev": false
}

Bedrock already has an autoload configured so you don't need to worry about that.

WP_ENV is set in .env rather than wp-config, Forme uses the same syntax as Bedrock so will recognise whatever you have set there.

Finally, the best place to set FORME_PRIVATE_ROOT is in config/application.php straight after the $root_dir definition, since it's essentially the same thing plus a trailing slash.

/**
 * Private root dir for Forme
 */
define('FORME_PRIVATE_ROOT', $root_dir . '/');

Adding external packages ​

You can now edit the composer file or composer require any plugins, themes and libraries that you need at the root level, in the same way as you would do in any non-WordPress php project.

After the first install, you should use composer install, composer require or composer update commands a usual.