WordPress environments

php bones must run inside a working WordPress install. Any local dev environment that serves WordPress over PHP ≥ 8.1 will work. The options below are the ones we use and test against — pick whichever best matches your OS and workflow.

At a glance

wp-env (recommended for plugin development)

@wordpress/env is the official tool from the WordPress core team. It spins up a Docker-based WordPress and automatically mounts the plugin folder it runs from.

# From inside your WP Bones plugin folder
npx wp-env start

That’s it. The plugin is already active at http://localhost:8888 . Default admin credentials: admin / password.

Customize via a .wp-env.json in the plugin root:

{
  "core": "WordPress/WordPress#6.7",
  "phpVersion": "8.3",
  "plugins": ["."],
  "themes": []
}

Run WP-CLI inside the container: npx wp-env run cli wp plugin list. To run php bones inside the container: npx wp-env run cli php bones.

Laravel Valet (best on macOS)

Valet  serves projects over .test domains using Nginx + dnsmasq directly on the host. No VM, no containers, native PHP — the fastest iteration loop if you’re on macOS or Linux.

# Homebrew prerequisites
brew install php composer mysql node yarn
 
# One-time Valet setup
composer global require laravel/valet
valet install
 
# Park a folder — every sibling directory becomes <folder>.test
mkdir -p ~/Sites && cd ~/Sites
valet park
 
# Install WordPress inside ~/Sites/wpbones via WP-CLI
wp core download --path=wpbones
cd wpbones
wp config create --dbname=wpbones --dbuser=root --dbpass=
wp db create
wp core install --url=wpbones.test --title="WPBones" --admin_user=admin --admin_email=you@example.com

Drop a WP Bones plugin into wp-content/plugins/ — it is immediately available at http://wpbones.test/wp-admin. This is the environment we use for all framework development.

Local (by WP Engine)

Local  is a desktop app that provisions full WordPress stacks with a few clicks. Perfect if you don’t want to touch the CLI.

1. Install Local from localwp.com .
2. Create a new site — pick PHP ≥ 8.1.
3. Click “Go to site folder” from the Local sidebar → drop the plugin into app/public/wp-content/plugins/.
4. Run php bones ... from Local’s built-in shell (Open Site Shell).

DDEV

DDEV  is a Docker-based local dev platform with first-class WordPress support and a very active community. Great when you want something stronger than wp-env but less manual than raw Docker Compose.

mkdir wpbones && cd wpbones
ddev config --project-type=wordpress --docroot=.
ddev start
ddev wp core download
ddev wp core install --url=https://wpbones.ddev.site --title=WPBones \
  --admin_user=admin --admin_email=you@example.com --admin_password=admin

Run the bones CLI inside the container: ddev exec "cd wp-content/plugins/<your-plugin> && php bones".

Lando

Lando  also wraps Docker, with a per-project .lando.yml that teammates check into git for identical stacks regardless of OS.

# .lando.yml
name: wpbones
recipe: wordpress
config:
  php: '8.3'
  webroot: .

lando start
lando wp core install --url=wpbones.lndo.site --title=WPBones \
  --admin_user=admin --admin_email=you@example.com

Run lando php bones ... to execute the bones CLI inside the container.

WordPress Playground

Playground  runs WordPress entirely in the browser via WASM. No install, no server — perfect for quick demos, issue reproductions, or trying a boilerplate.

Every WP Bones boilerplate ships with a Playground blueprint — see the Playground link on each boilerplate page. You can’t php bones from Playground (no shell), but you can test the runtime behavior of an already-built plugin.

Docker Compose (full control)

If the wrappers above feel too opinionated and you want to pin every version yourself, the official WordPress image + a MariaDB container is enough.

# docker-compose.yml
services:
  db:
    image: mariadb:11
    environment:
      MARIADB_ROOT_PASSWORD: root
      MARIADB_DATABASE: wpbones
  wp:
    image: wordpress:php8.3-apache
    ports: ['8080:80']
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: root
      WORDPRESS_DB_PASSWORD: root
      WORDPRESS_DB_NAME: wpbones
    volumes:
      - ./wp-content/plugins:/var/www/html/wp-content/plugins

docker compose up -d
docker compose exec wp bash -c "cd wp-content/plugins/<your-plugin> && php bones"

Vagrant

Still viable for VM-based workflows. The original WP Bones VM is at gfazioli/VagrantUbuntu  and is kept as a reference for anyone who prefers full-VM isolation. For new projects we recommend wp-env, Valet, or Local first — they boot faster and use far fewer resources.

Troubleshooting

• php bones says “WordPress not loaded” — you’re running it outside the plugin folder, or the environment doesn’t bootstrap WP. Run it from the plugin root inside your WP shell.
• PHP version mismatch — check php -v in the same shell you use to run php bones. On macOS with multiple PHP installs, brew link php@8.3 or valet use php@8.3 helps.
• yarn build fails with Node warnings — bump to Node 18+. WP Bones v2 builds with @wordpress/scripts 31, which requires Node 18.