Bedrock

https://roots.io/bedrock/docs
Admin
Bedrock is a WordPress boilerplate that provides easier configuration, an improved folder structure,...
Tokens:4,265
Snippets:45
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Navigate and Install Bedrock

Source: https://roots.io/bedrock/docs/bedrock-with-local

Commands to navigate to the correct directory within a Local site and install Bedrock using Composer. Assumes the user is in a Local site's directory and needs to reach the 'app/' folder.

```bash
# Navigate one folder up
$ cd ..

# or, navigate directly to the app/ folder
$ cd ~/Local\ Sites/bedrock/app
```

```bash
$ composer create-project roots/bedrock
```

--------------------------------

### Configure Multiple mu-plugins

Source: https://roots.io/bedrock/docs/composer

This JSON example illustrates how to configure multiple regular WordPress plugins to be installed as mu-plugins by adding their package names to the array associated with the `web/app/mu-plugins/{$name}/` key in `composer.json`.

```json
{
...
      "web/app/mu-plugins/{$name}/": [
        "type:wordpress-muplugin", 
        "wpackagist-plugin/akismet",
        "wpackagist-plugin/turn-comments-off"
      ],
...
}
```

--------------------------------

### Install Bedrock with Composer

Source: https://roots.io/bedrock/docs/installation

This command creates a new Bedrock project using Composer. Composer is a dependency manager for PHP and is required to install Bedrock and its dependencies.

```bash
composer create-project roots/bedrock
```

--------------------------------

### Install WP-CLI Valet Command

Source: https://roots.io/bedrock/docs/bedrock-with-valet

Installs the WP-CLI command for Valet integration, enabling management of Bedrock sites within the Valet environment. This command is essential for using Valet's features with Bedrock.

```bash
$ wp package install aaemnnosttv/wp-cli-valet-command:@stable
```

--------------------------------

### Enable Bedrock Multisite in Application Config

Source: https://roots.io/bedrock/docs/bedrock-with-valet

Enables multisite functionality in a Bedrock installation by defining the WP_ALLOW_MULTISITE constant. This is a required step before network setup in the WordPress admin.

```php
Config::define('WP_ALLOW_MULTISITE', true);
```

--------------------------------

### Install Bedrock with Composer

Source: https://roots.io/bedrock/docs/bedrock-with-devkinsta

Installs the Bedrock framework into the current directory using Composer. This command fetches the latest Bedrock version and its dependencies.

```bash
$ composer create-project roots/bedrock
```

--------------------------------

### Configure Bedrock Multisite for Subdomain Installs

Source: https://roots.io/bedrock/docs/bedrock-with-valet

Configures Bedrock for subdomain-based multisite installations. This includes defining multisite constants in `config/application.php` and setting the `DOMAIN_CURRENT_SITE` in the `.env` file.

```php
/**
 * Multisite
 */
Config::define('WP_ALLOW_MULTISITE', true);
Config::define('MULTISITE', true);
Config::define('SUBDOMAIN_INSTALL', true);
Config::define('DOMAIN_CURRENT_SITE', env('DOMAIN_CURRENT_SITE'));
Config::define('PATH_CURRENT_SITE', env('PATH_CURRENT_SITE') ?: '/');
Config::define('SITE_ID_CURRENT_SITE', env('SITE_ID_CURRENT_SITE') ?: 1);
Config::define('BLOG_ID_CURRENT_SITE', env('BLOG_ID_CURRENT_SITE') ?: 1);
```

--------------------------------

### Configure Composer Installers with Bedrock

Source: https://roots.io/bedrock/docs/mu-plugin-autoloader

This configuration snippet shows how to set up 'installer-paths' in Composer to manage WordPress plugin, theme, and mu-plugin installations within a Bedrock project. It demonstrates overriding package types for custom installations.

```json
{
  "installer-paths": {
    "web/app/mu-plugins/{$name}/": ["type:wordpress-muplugin", "roots/wp-stage-switcher"],
    "web/app/plugins/{$name}/": ["type:wordpress-plugin"],
    "web/app/themes/{$name}/": ["type:wordpress-theme"]
  }
}
```

--------------------------------

### Add Multisite URL Fixer with Composer

Source: https://roots.io/bedrock/docs/installation

This command installs the `roots/multisite-url-fixer` plugin using Composer. This plugin is necessary for subdomain multisite installations to ensure admin URLs function correctly. It is compatible with subdirectory installs but not strictly required for them.

```bash
composer require roots/multisite-url-fixer
```

--------------------------------

### Bedrock Environment Variables Configuration

Source: https://roots.io/bedrock/docs/bedrock-with-local

Example `.env` file content for a Bedrock site configured for Local. Sets database credentials and the home URL.

```ini
DB_NAME='local'
DB_USER='root'
DB_PASSWORD='root'

WP_HOME='https://bedrock.local'
```

--------------------------------

### Configure Bedrock Multisite for Subfolder Installs

Source: https://roots.io/bedrock/docs/bedrock-with-valet

Configures Bedrock for subfolder-based multisite installations. This involves defining multisite constants in `config/application.php` and setting the `DOMAIN_CURRENT_SITE` in the `.env` file, with `SUBDOMAIN_INSTALL` set to false.

```php
/**
 * Multisite
 */
Config::define('WP_ALLOW_MULTISITE', true);
Config::define('MULTISITE', true);
Config::define('SUBDOMAIN_INSTALL', false);
Config::define('DOMAIN_CURRENT_SITE', env('DOMAIN_CURRENT_SITE'));
Config::define('PATH_CURRENT_SITE', env('PATH_CURRENT_SITE') ?: '/');
Config::define('SITE_ID_CURRENT_SITE', env('SITE_ID_CURRENT_SITE') ?: 1);
Config::define('BLOG_ID_CURRENT_SITE', env('BLOG_ID_CURRENT_SITE') ?: 1);
```

--------------------------------

### Link Subdomains with Valet for Bedrock Multisite

Source: https://roots.io/bedrock/docs/bedrock-with-valet

Links specific subdomains to the main Bedrock multisite installation using Valet commands. This allows Valet to correctly route traffic to the various sub-sites within the network.

```bash
$ valet link test.bedrock-multisite
$ valet link site2.bedrock-multisite
```

--------------------------------

### Navigate to DevKinsta Site Path

Source: https://roots.io/bedrock/docs/bedrock-with-devkinsta

Changes the current directory to the specified site path within the DevKinsta environment. This is a prerequisite for installing Bedrock.

```bash
$ cd ~/DevKinsta/public/example
```

--------------------------------

### Configure Plugin Installation Path in composer.json

Source: https://roots.io/bedrock/docs/composer

This JSON snippet shows how to configure `installer-paths` in `composer.json` to force a specific plugin (e.g., Akismet) to be installed in the `mu-plugins` directory instead of the default `plugins` directory.

```json
{
  "extra": {
    "installer-paths": {
      "web/app/mu-plugins/{$name}/": ["type:wordpress-muplugin", "wpackagist-plugin/akismet"],
      "web/app/plugins/{$name}/": ["type:wordpress-plugin"],
      "web/app/themes/{$name}/": ["type:wordpress-theme"]
    },
    "wordpress-install-dir": "web/wp"
  },
... 
}
```

--------------------------------

### Install Bedrock Plugin Disabler with Composer

Source: https://roots.io/bedrock/docs/disable-plugins-based-on-environment

Installs the Bedrock Plugin Disabler package using Composer, a dependency manager for PHP. This is the first step to enable environment-specific plugin disabling.

```bash
$ composer require lukasbesch/bedrock-plugin-disabler

```

--------------------------------

### Nginx Multisite Subdomain Rewrites

Source: https://roots.io/bedrock/docs/server-configuration

Specific Nginx rewrite rules required for subdomain-based multisite installations in Bedrock.

```nginx
rewrite ^/(wp-.*.php)$ /wp/$1 last;
rewrite ^/(wp-(content|admin|includes).*) /wp/$1 last;

```

--------------------------------

### Nginx Multisite Subfolder Rewrites

Source: https://roots.io/bedrock/docs/server-configuration

Nginx rewrite rules for subfolder multisite installations in Bedrock, handling cases where the request filename does not exist.

```nginx
if (!-e $request_filename) {
  rewrite /wp-admin$ $scheme://$host$uri/ permanent;
  rewrite ^(/[^/]+)?(/wp-.*) /wp$2 last;
  rewrite ^(/[^/]+)?(/.*.php) /wp$2 last;
}

```

--------------------------------

### Disable WP Cron and Manual Cron Job Setup

Source: https://roots.io/bedrock/docs/wp-cron

This snippet shows how to disable Bedrock's internal WP Cron using an environment variable and provides a bash command to set up a recurring cron job that calls the WordPress wp-cron.php file. This is useful for managing background tasks in WordPress when the default WP Cron is disabled.

```bash
# Set DISABLE_WP_CRON environment variable to true to disable internal WP Cron.
# Then, set up a cron job to manually trigger wp-cron.php.
*/5 * * * * curl https://example.com/wp/wp-cron.php
```

--------------------------------

### Bedrock Folder Structure Overview

Source: https://roots.io/bedrock/docs/folder-structure

This snippet illustrates the standard folder structure of a Bedrock project. It outlines the purpose of key directories and files, including configuration, application code, vendor packages, and WordPress core.

```text
├── composer.json             # → Manage versions of WordPress, plugins & dependencies
├── config                    # → WordPress configuration files
│   ├── application.php       # → Primary WP config file (wp-config.php equivalent)
│   └── environments          # → Environment specific configs
│       ├── development.php   # → Development config
│       └── staging.php       # → Staging config
├── vendor                    # → Composer packages (never edit)
└── web                       # → Web root (document root on your webserver)
    ├── app                   # → wp-content equivalent
    │   ├── mu-plugins        # → Must use plugins
    │   ├── plugins           # → Plugins
    │   ├── themes            # → Themes
    │   └── uploads           # → Uploads
    ├── wp-config.php         # → Required by WP (never edit)
    ├── index.php             # → WordPress view bootstrapper
    └── wp                    # → WordPress core (never edit)

```

--------------------------------

### Create New Bedrock Site with Valet

Source: https://roots.io/bedrock/docs/bedrock-with-valet

Creates a new Bedrock-based WordPress site and registers it with Valet. This involves navigating to the Valet sites directory and using the 'wp valet new' command with the project type specified as 'bedrock'.

```bash
$ cd ~/Sites/valet
$ wp valet new bedrock --project=bedrock
```

--------------------------------

### Configure Lando Recipe for Bedrock (.lando.yml)

Source: https://roots.io/bedrock/docs/bedrock-with-lando

This snippet shows the `.lando.yml` configuration file used to define a Lando environment for a Bedrock WordPress project. It specifies the name, recipe, webroot, and PHP version for the application server.

```yaml
# .lando.yml
name: bedrock
recipe: wordpress
config:
  webroot: web
services:
  appserver:
    type: php:8.2 # Bedrock requires PHP >= 8.0

```

--------------------------------

### Configure Bedrock Environment Variables (.env)

Source: https://roots.io/bedrock/docs/bedrock-with-lando

This snippet illustrates the necessary database credentials and home URL settings for the `.env` file in a Bedrock project when using Lando. These variables are crucial for Lando to correctly connect to the database and define the site's home URL.

```env
DB_NAME='wordpress'
DB_USER='wordpress'
DB_PASSWORD='wordpress'
DB_HOST='database'

WP_HOME='https://bedrock.lndo.site'

```

--------------------------------

### Apache Configuration for Bedrock

Source: https://roots.io/bedrock/docs/server-configuration

Apache VirtualHost configuration for Bedrock, setting the document root and enabling mod_rewrite for WordPress routing.

```apache
<VirtualHost *:80>
        DocumentRoot /var/www/html/bedrock/web

        DirectoryIndex index.php index.html index.htm

        <Directory /var/www/html/bedrock/web>
            Options -Indexes

            # .htaccess isn't required if you include this
            <IfModule mod_rewrite.c>
                RewriteEngine On
                RewriteBase /
                RewriteRule ^index.php$ - [L]
                RewriteCond %{REQUEST_FILENAME} !-f
                RewriteCond %{REQUEST_FILENAME} !-d
                RewriteRule . /index.php [L]
            </IfModule>
        </Directory>
</VirtualHost>

```

--------------------------------

### Add WordPress Theme with Composer

Source: https://roots.io/bedrock/docs/composer

This command demonstrates how to add a WordPress theme from the WordPress Theme Directory using Composer. It utilizes the `wpackagist-theme` namespace followed by the theme's name.

```bash
$ composer require wpackagist-theme/twentytwentythree
```

--------------------------------

### WordPress .htaccess for Bedrock

Source: https://roots.io/bedrock/docs/server-configuration

The standard WordPress `.htaccess` file content, which can be placed in Bedrock's `web` folder to handle routing.

```apache
# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

```

--------------------------------

### Add Plugin Files to Git (Bash)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Stages all plugin files for commit in a Git repository. The '.' signifies all files in the current directory.

```bash
$ git add .

```

--------------------------------

### Push Changes and Tags to GitHub (Bash)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Pushes all local Git commits and tags to the remote GitHub repository. The `--tags` flag ensures tags are also pushed.

```bash
$ git push --tags

```

--------------------------------

### Clone Private GitHub Repository (Bash)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Clones an empty private GitHub repository for a WordPress plugin. Assumes SSH access to GitHub.

```bash
$ git clone git@github.com:YourGitHubUsername/example-plugin.git

```

--------------------------------

### Create composer.json for Plugin (JSON)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Defines the metadata for a WordPress plugin to be managed by Composer. Includes name, description, type, and PHP requirements.

```json
{
  "name": "YourGithubUsername/example-plugin",
  "description": "",
  "keywords": ["wordpress", "plugin"],
  "homepage": "https://github.com/YourGitHubUsername/example-plugin",
  "authors": [
    {
      "name": "Original Plugin Author's Name",
      "homepage": "https://originalpluginurl.com"
    }
  ],
  "type": "wordpress-plugin",
  "require": {
    "php": ">=8.0"
  }
}

```

--------------------------------

### Nginx Configuration for Bedrock

Source: https://roots.io/bedrock/docs/server-configuration

Standard Nginx configuration for Bedrock projects. It sets the document root to the `web` folder and includes a rule to prevent PHP execution in the uploads directory.

```nginx
server {
  listen 80;
  server_name example.com;

  root /srv/www/example.com/web;
  index index.php index.htm index.html;

  # Prevent PHP scripts from being executed inside the uploads folder.
  location ~* /app/uploads/.*.php$ {
    deny all;
  }

  location / {
    try_files $uri $uri/ /index.php?$args;
  }
}

```

--------------------------------

### Configure Bedrock Environment Variables

Source: https://roots.io/bedrock/docs/bedrock-with-devkinsta

Sets the necessary environment variables for Bedrock to connect to the local database and define the home URL. These variables are crucial for the site to function correctly.

```ini
DB_NAME='example'
DB_USER='root'
DB_PASSWORD='password'
DB_HOST='devkinsta_db'

WP_HOME='http://example.local'
```

--------------------------------

### Add WordPress Plugin with Composer

Source: https://roots.io/bedrock/docs/composer

This command demonstrates how to add a WordPress plugin from the WordPress Plugin Directory using Composer. It requires the `wpackagist-plugin` namespace followed by the plugin's name.

```bash
$ composer require wpackagist-plugin/akismet
```

--------------------------------

### Bedrock .htaccess for Managed Hosts

Source: https://roots.io/bedrock/docs/server-configuration

An alternative `.htaccess` file for Bedrock when the document root cannot be changed on managed WordPress hosts. It rewrites requests to the `web` folder.

```apache
RewriteEngine on

RewriteCond %{REQUEST_URI} !web/
RewriteRule ^(.*)$ /web/$1 [L]

```

--------------------------------

### Nginx Webroot Configuration Update

Source: https://roots.io/bedrock/docs/bedrock-with-local

Modification of the Nginx site configuration file (`site.conf.hbs`) in Local to set the correct server root for a Bedrock site. This involves appending `/web` to the existing root path.

```nginx
server {
    listen {{port}};
-   root   "{{root}}";
+   root   "{{root}}/web";

}
```

--------------------------------

### Configure Bedrock composer.json for Private Repo (JSON)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Adds a private Git repository definition to the Bedrock project's `composer.json` file. This allows Composer to fetch the private plugin.

```json
"repositories": [

  ...

    {
      "type": "vcs",
      "url": "git@github.com:YourGitHubUsername/example-plugin.git"
    }

  ...

],

```

--------------------------------

### Tag Plugin Release (Bash)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Creates a Git tag for a specific plugin version, following semantic versioning. This tag is used by Composer to identify the plugin version.

```bash
$ git tag 2.9.14

```

--------------------------------

### Update WordPress/Plugin Versions with Composer

Source: https://roots.io/bedrock/docs/composer

These commands show how to update WordPress core or specific plugins to their latest versions or to a particular version using `composer require`. The `-W` flag is used for updating WordPress core to pull in the latest compatible versions.

```bash
$ composer require roots/wordpress -W
$ composer require wpackagist-plugin/akismet
$ composer require roots/wordpress:6.1 -W
```

--------------------------------

### Update Bedrock Dependencies (Bash)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Instructs Composer to update all project dependencies, including the newly added private plugin, within the Bedrock directory.

```bash
composer update

```

--------------------------------

### Using env() for Environment Variables in PHP

Source: https://roots.io/bedrock/docs/environment-variables

Demonstrates how to access environment variables in PHP using the `env()` function provided by the env library. This function handles type coercion for variables like 'True' to boolean true. Bedrock recommends using this function for reading environment variables.

```php
getenv('WP_HOME')
$_SERVER['WP_HOME']
$_ENV['WP_HOME']

// Recommended usage with type coercion:
env('WP_HOME')
env('DB_PORT')
env('WP_DEBUG', false) // Example with default value
```

--------------------------------

### Update DevKinsta Site Config (Nginx)

Source: https://roots.io/bedrock/docs/bedrock-with-devkinsta

Modifies the Nginx server configuration file for a DevKinsta site to correctly point to the Bedrock webroot. This ensures that Nginx serves files from the correct directory.

```nginx
-root /www/kinsta/public/example;
+root /www/kinsta/public/example/bedrock/web;
```

--------------------------------

### Commit Plugin Changes to Git (Bash)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Commits staged changes to the Git repository. It's recommended to include version information in the commit message.

```bash
$ git commit .

```

--------------------------------

### Ignore Composer-Managed Folders in Git

Source: https://roots.io/bedrock/docs/composer

This configuration snippet shows how to update the `.gitignore` file to prevent Composer-managed plugin and mu-plugin folders from being ignored by Git, allowing them to be added to the repository.

```gitignore
!web/app/plugins/plugin-name
```

--------------------------------

### Require Private Plugin in Bedrock composer.json (JSON)

Source: https://roots.io/bedrock/docs/private-or-commercial-wordpress-plugins-as-composer-dependencies

Adds the private plugin to the `require` section of the Bedrock project's `composer.json`. The version number must match the Git tag.

```json
"require": {

  ...

    "YourGitHubUsername/example-plugin": "2.9.14",

  ...

},

```

--------------------------------

### Disable Plugins in Development Environment (PHP)

Source: https://roots.io/bedrock/docs/disable-plugins-based-on-environment

Configures the Bedrock environment to disable specific plugins, such as WP Rocket and WP Super Cache, during local development. This is achieved by defining the DISABLED_PLUGINS constant in the development environment configuration file.

```php
Config::define('DISABLED_PLUGINS', [
    'wp-rocket/wp-rocket.php',
    'wp-super-cache/wp-cache.php',
]);

```
Tokens:
Raw