Ga naar inhoud

WordPress Development

Table of Contents

Overview

At Lemone, we primarily use the Roots stack for WordPress development: - Bedrock: Modern WordPress stack with better organization - Sage: WordPress starter theme with modern tooling - Trellis: Ansible-based deployment tool

For Roots-specific documentation, see WordPress Roots Stack.

Project Setup

Complete setup process for a new WordPress project using the Roots stack.

Prerequisites

Tools needed: - PHP 8.0+ - Composer - Node.js & Yarn - Lando (for local development) - Git

Optional: Tiged (copies repositories without git references): 

yarn global add tiged

1. GitLab Setup

Create project repository:

  1. Create a group for the company (if it doesn't exist)
  2. Create new project on codepot.nl
  3. Use same name as Tresorit folder
  4. Create branch named develop
  5. Set default branch to develop in settings
  6. Invite team members
  7. Clone the project locally
  8. Create a board for issue tracking
  9. Download .gitlab folder from boilerplate to project root
  10. Import standard WordPress project issues

2. Tresorit Setup

Organize design files:

  1. Create 06-develop folder in Tresorit project
  2. Copy design/Sketch files to develop folder (extend filename with your name)
  3. Create separate assets.sketch file for assets

3. Install Bedrock

Create project structure:

# Create project folder
mkdir my-project
cd my-project

# Install Bedrock
composer create-project roots/bedrock site

4. Install Trellis

Set up deployment tool:

# Clone Trellis (in project root, not in site/)
degit https://github.com/roots/trellis

# Delete .github folder from Trellis
rm -rf trellis/.github

5. Configure Bedrock

Install essential plugins:

cd site

# Install Acorn (Laravel components for WordPress)
composer require roots/acorn

# Install Soil (WordPress plugin to clean up markup)
composer require roots/soil

# Install Sage SVG (easy SVG usage)
composer require log1x/sage-svg

Configure Soil:

Edit site/web/app/themes/your-theme/app/setup.php and add:

add_theme_support('soil-js-to-footer');

6. Install Sage Theme

Create theme:

cd site/web/app/themes

# Remove default theme
rm -rf twentytwentythree

# Install Sage with your theme name
composer create-project roots/sage your-theme-name

cd your-theme-name

# Install dependencies
yarn

Configure theme:

  1. Update style.css with theme name and details
  2. Add screenshot: screenshot.png (project design preview)
  3. Install Sass support (Sage comes with Tailwind by default): 
    yarn add @roots/bud-sass @roots/bud-postcss --dev

Build theme:

# First build
yarn build

# Development with live reload
yarn dev

7. Add Lando

Create .lando.yml in site/ folder:

name: my-project
recipe: wordpress

config:
  php: "8.2"
  via: nginx
  webroot: web
  xdebug: "debug,develop,trace"

services:
  database:
    type: mariadb:10.6
  pma:
    type: phpmyadmin
    hosts:
      - database

Configure environment:

Edit site/.env:

# Copy this file to .env for development with Lando

DB_NAME=wordpress
DB_USER=wordpress
DB_PASSWORD=wordpress
DB_HOST=database

WP_ENV=development

WP_HOME=http://my-project.lndo.site
WP_SITEURL=${WP_HOME}/wp

Setup:

  1. Duplicate .env to .env.lando-dev
  2. Add !.env.lando-dev to .gitignore in site/ folder
  3. Update bud.config.js proxy URL to match Lando URL: 
    .proxy('http://my-project.lndo.site')

8. Start Development Environment

cd site

# Update Composer dependencies
lando composer update

# Start Lando
lando start

# Wait for containers to start

9. WordPress Installation

Access site at http://my-project.lndo.site and complete installation:

  1. Language: Nederlands (or your preferred language)
  2. Site Title: PROJECT NAME
  3. Username: admin
  4. Password: admin
  5. Email: admin@site.local
  6. Search Engine Visibility: Discourage search engines (checked)

Post-installation:

  1. Log in to WordPress admin
  2. Appearance → Themes → Activate your new Sage theme
  3. Settings → General:
  4. Check timezone
  5. Settings → Reading:
  6. Set homepage and posts page to static pages

10. Finalize

# Commit all changes
git add .
git commit -m "chore: initial WordPress project setup"
git push origin develop

Local Admin User

Creating Admin User via WP-CLI

If you need to create or recreate a local admin user:

lando wp user create admin admin@site.local --role=administrator --user_pass=admin

Login credentials: - Username: admin - Password: admin

Resetting Admin Password

If you need to reset an existing admin password:

lando wp user update admin --user_pass=admin

Common Issues

Sage 9: file_get_contents Error (WordPress 6.3+)

Error message:

Notice: file_get_contents(): Read of 8192 bytes failed with errno=21 Is a directory in /app/web/wp/wp-includes/functions.php on line 4570

Notice: Error when decoding a JSON file at path /app/web/app/themes/theme/resources: Syntax error in /app/web/wp/wp-includes/functions.php on line 4578

Cause: WordPress 6.3+ looks for theme.json but Sage 9 uses a different structure.

Fix: Add this filter to your functions.php:

add_filter(
  "theme_file_path",
  function ($path, $file) {
    if ($file === "theme.json") {
      return false;
    }
    return $path;
  },
  0,
  2
);

Resources: - Roots Discourse: Sage 9 warnings after WP 6.3 update

Lando Not Starting

Check: 1. Docker is running 2. No port conflicts (80, 443, 3306) 3. Run lando rebuild -y to rebuild containers

Theme Not Compiling

Check: 1. Node version compatibility (use Node 18+) 2. Run yarn install to ensure dependencies are up to date 3. Clear cache: yarn bud clean 4. Check bud.config.js for syntax errors

Database Connection Error

Check: 1. Lando is running: lando start 2. .env file has correct database credentials: 

DB_HOST=database  # Not localhost!
DB_NAME=wordpress
DB_USER=wordpress
DB_PASSWORD=wordpress

Best Practices

  1. Use Composer for plugins - Install via WPackagist when possible
  2. Commit composer.lock - Ensures consistent dependencies across environments
  3. Never commit .env - Use .env.example as template
  4. Use Bedrock directory structure - Keep WordPress core in web/wp/
  5. Follow Conventional Commits - Use semantic commit messages
  6. Test locally first - Always test changes in Lando before deploying

See Also