Installation

Requirements

Mantle has two system requirements to run:

• PHP to be at least running 8.2. Mantle supports PHP 8.2 to 8.4 as of Mantle v1.4.
• WordPress to be at least 6.5.

How Can I Use Mantle?

Mantle supports two different modes of operation:

1. This is the most common setup: As a plugin/theme framework for a WordPress site. It normally lives in wp-content/plugins/mantle. and uses alleyinteractive/mantle as the starter package for this mode.

2. In isolation in an existing code base. The Mantle framework provides all it's own default configuration and service providers and doesn't require most of the code in alleyinteractive/mantle to function. This mode is useful for integrating Mantle into an existing code base and using one of it's features like queue or routing without setting up the rest of the application.

   For more information on this mode, see the Using Mantle in Isolation section.

Installing Mantle on a Site with Mantle Installer

Mantle sites should live in wp-content/plugins/{site-slug}/ inside a WordPress project. The Mantle Installer can install Mantle on a new or existing WordPress application. The installer can be installed via a PHP PHAR or globally using Composer (PHAR is recommended).

Via PHAR 📦

Download the latest PHAR release of the Mantle installer from the latest releases page. You can use the PHAR directly or move to a $PATH directory. Here's a quick example of how to do all of that:

# Download the latest PHAR release.
gh release download --clobber --pattern= '*.phar' --repo=alleyinteractive/mantle-installer

# Make the PHAR executable.
chmod +x mantle-installer.phar

# Optionally move it to a directory in your PATH for global usage.
sudo mv mantle-installer.phar /usr/local/bin/mantle

This example uses the gh CLI from GitHub to download the latest release. You can also download the PHAR manually from the latest release page.

From here, you can run the mantle command from anywhere on your system.

Via Composer 🛠 ️

Download the Mantle installer using Composer.

composer global require alleyinteractive/mantle-installer

Once installed the mantle new command will create a fresh Mantle installation wherever you specify. It can also install WordPress for you or install Mantle into an existing WordPress installation.

mantle new my-site

Manual Installation

Alternatively, you can install a Mantle site using Composer, replacing my-site with your site's slug.

cd wp-content/plugins/

composer create-project alleyinteractive/mantle my-site \
  --remove-vcs \
  --stability=dev \
  --no-cache \
  --no-interaction

Starter Template for wp-content-based Projects

Alley's create-wordpress-project starter template can be used as a starting point for using Mantle on a wp-content-rooted project. create-wordpress-project includes a configuration script to help you setup your project and install plugins and themes. It also supports installing Mantle as a plugin out of the box.

Using Mantle in Isolation

Mantle supports the use of the framework and its features in complete isolation, without the need of the starter code in alleyinteractive/mantle. Using the Application Bootloader, you can instantiate the Mantle framework in one line and use it's features in any code base.

bootloader()->boot();

tip

For more information on the Bootloader, see the Bootloader documentation.

For example, if you want to use Mantle's Queue feature in an existing code base, you can do so by booting the framework and then using the dispatch() helper (see the queue documentation for more information).

// Boot the application.
bootloader()->boot();

// Dispatch an anonymous job.
dispatch( function () {
  // Do something expensive here.
} );

Calling the bootloader is all you need to use Mantle in isolation -- no other files or directories need to be created. If you want to enhance your experience, you can copy files down from alleyinteractive/mantle as needed to your code base.