Bedrock Laravel Package

Getting Started

Bedrock is not a Laravel app, but it will feel familiar: Composer dependencies, .env-driven configuration, environment-specific config files, and a non-public application directory. Treat it as “Laravel-style project hygiene applied to WordPress.”

Minimal setup:

composer create-project roots/bedrock my-site
cd my-site
cp .env.example .env
# edit DB_*, WP_ENV, WP_HOME, WP_SITEURL, salts
composer install
wp core install --url=https://example.test --title="My Site" \
  --admin_user=admin [email protected]

Point your web server document root at web/, not the project root. Then install your first dependency-managed plugin:

composer require wpackagist-plugin/query-monitor
wp plugin activate query-monitor

Look first at:

• composer.json — installer paths for core, plugins, themes, mu-plugins.
• config/application.php — the real WordPress config, using Roots\WPConfig\Config.
• config/environments/development.php and production.php — per-environment constants.
• web/wp-config.php — a small shim; do not put secrets here.
• web/app/themes and web/app/plugins — your application code, not wp-content.
• wp-cli.yml — usually sets path: web/wp, so wp works from the project root.

First real use case: replace the “download a zip and upload it” workflow with composer require, activate with WP-CLI, and commit composer.json + composer.lock. That single loop is the day-to-day value.

Implementation Patterns

Composer as the plugin/theme/core manager.
Use WPackagist for public plugins and themes:

composer require wpackagist-plugin/woocommerce:^9.0
composer require wpackagist-theme/twentytwentyfour
wp plugin activate woocommerce

Pin versions where stability matters. Update deliberately:

composer update wpackagist-plugin/woocommerce --with-dependencies

Core updates are also Composer operations, depending on the roots/wordpress package version in composer.json.

Configuration layering.
Keep shared constants in config/application.php, and per-environment overrides in config/environments/{development,staging,production}.php. Use Config::define() rather than editing WordPress core or creating a traditional wp-config.php.

// config/environments/development.php
Config::define('WP_DEBUG', true);
Config::define('WP_DEBUG_LOG', true);
Config::define('WP_DEBUG_DISPLAY', false);
Config::define('SCRIPT_DEBUG', true);

Use .env for machine- or deployment-specific values, especially database credentials and salts. Never commit .env.

Application code placement.
For site-specific behavior, prefer a custom mu-plugin or a project plugin. Bedrock’s autoloader loads mu-plugins from web/app/mu-plugins, and Composer packages of type wordpress-muplugin are supported. For theme work, pair Bedrock with Sage + Acorn if you want Blade, service providers, Vite, and other Laravel-adjacent DX.

WP-CLI as your artisan.
Daily commands:

wp plugin list
wp theme list
wp db export backups/before-deploy.sql
wp cache flush
wp cron event run --due-now
wp eval 'var_dump(get_option("home"));'
wp core update-db

Run from the project root; wp-cli.yml should make WordPress discoverable. This is the closest analogue to Laravel’s Artisan workflow.

Deployment pattern.
Build dependencies during deploy, not in production interactively:

composer install --no-dev --optimize-autoloader
wp core update-db

Set environment variables through your host/platform rather than shipping .env. Persist web/app/uploads across releases with a shared directory or symlink. Keep composer.lock committed and run composer update only in development/CI, never as part of a production deploy.

CI checks.
Useful baseline:

composer validate
composer audit
composer install --no-interaction --prefer-dist
wp core verify-checksums

Add PHP linting and whatever theme/plugin tests you use. Bedrock itself is mostly structure and configuration, so CI should verify that Composer resolves and that WordPress boots with the expected environment.

Local development.
Use DDEV, Lando, Trellis, Valet, or Herd — just ensure the document root is web/. For Laravel developers, Sage/Acorn is the natural companion if you want Blade templates and a more Laravel-like theme architecture. Bedrock handles the project skeleton; Sage handles the frontend/theme layer.

Private/premium plugins.
Do not manually commit zips into web/app/plugins unless you accept that Composer will not manage them. Instead use a private Composer repository, a VCS/path repository with the correct wordpress-plugin package type, or a private installer package. Keep the installer paths in composer.json consistent.

Gotchas and Tips

• Document root must be web/. This is the most common Bedrock mistake. Serving the project root exposes .env, composer.json, and config files, and breaks WordPress routing.
• There is no normal wp-content directory. Content lives in web/app. Plugins that hardcode wp-content, WP_PLUGIN_DIR, or WP_CONTENT_DIR assumptions can behave strangely. Bedrock defines the standard constants, but poorly written plugins still break.
• Do not look for a traditional wp-config.php workflow. web/wp-config.php is a shim that loads config/application.php. Put configuration in config/, not in the web root.
• Dashboard file editing/installing is intentionally constrained. Expect to manage plugins, themes, and core through Composer. If a client needs to install plugins from wp-admin, that workflow conflicts with Bedrock’s model.
• Salts live in .env. Quote values containing spaces or special characters. Use a salts generator or WP-CLI where appropriate, then paste into .env. A missing or mismatched salt set causes login/session weirdness.
• WP_HOME and WP_SITEURL must match the actual scheme and host. Behind a reverse proxy or load balancer, HTTPS detection can fail and cause redirect loops or mixed-content issues. Set both to the public HTTPS URL and ensure forwarded-proto headers are handled.
• WP_ENV is Bedrock’s environment switch; some plugins check WP_ENVIRONMENT_TYPE. If a plugin behaves as production in development, set WP_ENVIRONMENT_TYPE explicitly in the environment config.
• WP-CLI path problems usually mean you ran it from the wrong directory or wp-cli.yml is missing/wrong. Check path: web/wp. Also ensure the CLI PHP version matches the web PHP version.
• Composer package type matters. A package must be typed as wordpress-plugin, wordpress-theme, wordpress-muplugin, or wordpress-core for installer paths to place it correctly. A manually downloaded plugin will not be updated by Composer and may be wiped by deployment cleanup.
• Plugin updates can overwrite customizations. Never edit vendor-managed plugins directly. Put customizations in an mu-plugin, a project plugin, or a child theme.
• Persist uploads and runtime files. web/app/uploads, cache directories, and log files should not be part of an immutable release artifact unless you intentionally handle them. Symlink or mount them.
• Debug logging lands under the content directory. With WP_DEBUG_LOG enabled, check web/app/debug.log. Do not enable WP_DEBUG_DISPLAY in production.
• Object-cache and advanced-cache drop-ins live in web/app. Caching plugins may place object-cache.php or advanced-cache.php there. Account for them in deploy scripts and backups.
• Composer updates are the main operational risk. Always commit composer.lock, update plugins in staging first, and use --with-dependencies when a plugin update requires a newer library. Run composer audit regularly.
• Extension points are simple but powerful: config/application.php for global constants/filters, environment files for per-environment behavior, mu-plugins for site logic, and composer.json extra.installer-paths for custom package layouts. Keep business logic out of config/ and out of WordPress core.