Starting a new plugin or theme project ​

Create the project ​

The most straight forward way to create a new plugin or theme project is with the code generation cli. Let's say you want to create a new plugin called "Hello World". Firstly cd into wherever you want the repo to be, then:

forme new plugin HelloWorld

This will create a new directory called hello-world-plugin with all the necessary boiler plate code and initialise the git repo for you. Check out the development workflow section too for further details on the various dev tools available.

Vendor Name Space ​

As a default the cli will put the project into the generic App vendor namespace. If you need something else, you can use the --vendor option.

forme new plugin HelloWorld --vendor=FooBar

View Engine ​

Forme supports Blade, Twig, Plates and Plates 4 view engines. The default is currently Plates 4, but you can use the --view option to select one of blade, twig, plates or plates-4.

forme new theme HelloWorld --view=blade

Host Aliases ​

You might have different Github users (e.g a work and personal one) and might have assigned different host aliases to them in your git config. If you need to pass a host in to access an alternative git hub account, you can use the --host option.

forme new plugin HelloWorld --host=work

If all has worked you should see something like this:

🎉 Created a new Forme plugin project! You can cd into hello-world-plugin and get coding!

Congratulations!

Without cli ​

If you don't fancy using the cli or are struggling to install it for whatever reason, you can download the latest boilerplate release from github, unzip and follow the instructions below.

You'll need to search and replace the following strings (including file names):

Replace Me, replace-me, ReplaceMe, replace_me, VendorSpace

You can do this in your editor or this can be automated with gulp:

npm i
npx gulp --name="Theme Name" # whatever you want to call it

If you use gulp, vendor namespace will be "App" by default, you will usually want to change that.

npx gulp --name="Theme Name" --vendor="FooBar"

The --host and --view options can also be set in the same way as for the codegen cli.

npx gulp --name="Theme Name" --vendor="FooBar" --host="work" --view="blade"

You'll want to delete the gulpfile, npm package files and node_modules directory after running the above, since they will no longer be needed.

rm gulpfile.js package.json package-lock.json
rm -rf node_modules

You should then install the actual project package.json, which gives you access to all the webpack encore goodness. This one is in the repo as package.json.stub.

mv package.json.stub package.json
npm i

You can initialise git cliff to create your changelog configuration.

git-cliff --init

You should run composer install in the project folder to install all the local depedendencies. Note that this won't actually be imported and used by your main WordPress installation, this is so that dev cli tools (e.g. phpstan and captain hook) will be available within the project.

composer install

You should then do your git init and initial git commit.

And finally, you should initialise Captain Hook to make sure default git hooks are installed.

composer hooks

The Forme CodeGen new command follows this exact same process but does everything automatically. It's obviously much easier to use that!

Symlinks FTW ​

Before you actually start coding, you'll want to get your plugin or theme actually working within your WordPress installation, and you'll most likely find symlinking (aka symbolic linking) is the cleanest way of achieving this.

You might be tempted to place your project directly in the plugins or themes folder, and that would work just fine, but it's much easier to keep track of projects if they're all in one place, rather than trying to work on multiple git repos hidden away within multiple WordPress installations on your machine.

Your project repos can be anywhere you like on your machine, so you could put them all in a directory called ~/development or ~/sites or ~/projects or wherever you prefer to keep your dev projects stored.

# ~/projects/
.
├── foo-bar-laravel-app/
├── my-awesome-plugin/
├── my-awesome-theme/
├── vue-thing-repo/
└── zardoz-game/

To symlink a specific project into a WordPress installation, you then need to do something like:

ln -s full/path/to/hello-world-plugin full/path/to/wordpress/site/wp-content/plugins/

or even easier with the codegen shortcut

# you need to run this from the base installation directory
forme base link full/path/to/hello-world-plugin

Now as far as your file system is concerned, your repo is in its original location, and in the plugin folder. Neat, huh?

You can read more on symlinks here (they're as old as the hills!):

Symlinks on Wikipedia

Run Composer ​

You can now run composer install from the WordPress installation public folder and any third party libs that the plugin needs (i.e. those that are defined in its composer.json) should get downloaded and installed into the WordPress project's vendor directory. If this is the first time you've added a Forme project to this particular WordPress installation, it will also grab the core framework package.

Activate the plugin ​

You can now visit your WordPress site admin and activate the plugin. It doesn't do a lot right now but it's a solid starting point.

Themes ​

The process is pretty similar for themes, you need to replace plugin with theme at every step. When you activate the theme you should be presented with a very basic/vanilla Bootstrap 5 vibe. We'll look at both theme and plugin development in a bit more detail further in this guide.