Local environment ​

Forme should play nicely with local PHP development environments like Valet, Mamp, Local, or your own installation.

The Forme codegen also provides ketch, a selection of useful cli commands to spin up a basic zero config docker environment.

You could also run your local dev in a Vagrant virtual machine - we won't be covering that use case for now, but you should be able to get a steer from the local setup and remote deployment instructions.

Bash ​

Many of the commands in these docs assume a working bash shell.

Newer versions of OS X have zsh as default rather than bash. They should be mostly compatible but there are a few differences, and we haven't tested our shell scripts with zsh. Even where OS X does have bash, it's often an old version which might be missing a few features.

You can install the latest version with Homebrew:

brew install bash
micro /etc/shells # Or edit with your favourite terminal editor

# add to last line
/usr/local/bin/bash

chsh -s /usr/local/bin/bash $USER # this will set for the current user.

# Quit terminal and restart
bash --version

Git ​

You should be running version 2.x of git. You most likely have this already if you do any development.

PHP ​

You should be running PHP 8.1 or higher on both server and command line. You should have php already if you've got a local development environment, but you need to make sure the right version is available in your terminal.

Composer ​

You'll need the latest version of composer 2.x available globally on the command line.

Composer is the defacto package manager for php libraries.

Node ​

You should also have node and npm available globally to use the code generation tool, preferably lts version 18.x aka hydrogen (others might work too, but we've never tested anything below 12/erbium). If you use nvm (which you should!) then you'll need to do something like:

nvm use lts/hydrogen

MySQL ​

Setting up MySQL is out of scope for these docs, but you should have that as part of whatever local development environment system you use.

A Local Web Server ​

Setting up your local web server is out of scope for these docs, but similarly to MySQL, Apache and/or Nginx should form part of whatever local development environment system you are using. You might also have HTTPs configured via DNSMasq or Acrylic.

Forme Codegen ​

Read more about that here!

Other development packages ​

We also recommend getting the following installed globally on your machine if they aren't already, since various codegen cli commands, as well as examples in these docs rely on them.

• wget
• curl
• wp cli
• git cliff
• psysh

What about Windows? ​

Windows isn't really fully supported or tested unfortunately. You should have relatively few problems running existing Forme projects in whatever web server environment you use, but things like Forme Codegen might not work quite as expected depending on your precise setup, and there might be other bugs.

Having said that, the issues we've seen tend to be mostly bash and file system related. We have previously got things up and running on Windows 10 using packages like Cmder, nvm-windows and valet-windows. This was with an earlier, alpha version of Forme.

Your best bet is probably going to be to get everything working within a WSL2 Ubuntu instance. For example, we have got things running smoothly with Ubuntu 18.04 in WSL2 using Forme's ketch docker setup. Essentially you need to install and run everything from within the WSL2 instance, and proceed exactly as you would do on a Ubuntu machine. You can run Docker Desktop on your host machine, or install docker within the WSL2 instance.

Your first step would be getting the above prerequisites in place either natively or within WSL depending on which route you choose. We've been using the Chocolatey package manager for native Windows dependencies, and obviously the built in apt-get within Ubuntu WSL.

To get docker installed, you should take a look at the documentation as well as Digital Ocean's Ubuntu tutorials for docker and docker-compose.

Good luck!