WordPress Local Plugin/Theme Development Setup

composer.json

"repositories": [
		{
			"type": "path",
			"url": "/var/www/code/WP-Plugin-Event-Card",
			"options": {
				"symlink": true
			}
		},
    ...

docker-compose.override.yml

# Adding this docker-compose.override.yml to your site allows the docker container to see sibling directories of your local site
# This file should be gitignored and should not be committed to the repo
# You'll have to restart your docker container after adding this file
services:
  web:
    volumes:
      # Mount parent directory containing all sibling projects for local development
      - ../:/var/www/code # This assumes all your local theme and plugin directories/repos are siblings to the site repo/directory

LOCAL-THEME-PLUGIN-DEVELOPMENT-README.md

Local Theme & Plugin Development Setup

This guide explains how to set up local development for WordPress themes and plugins using Docker and Composer, allowing you to override remote packages with local development versions.

Directory Structure

Your local development setup should follow this structure:

~/Folder-Name-Not-Important/        # Your main code directory
├── WP-GCU-News-v2/                 # This project
├── WP-Theme-GCU-News/              # Local theme repository
├── WP-Plugin-Blog-Posts/           # Local plugin repository
├── WP-Plugin-Event-Card/           # Local plugin repository
├── WP-Theme/                       # Local Base theme repository
└── [Other WP projects...]          # Other WordPress projects

Setup Instructions

1. Create Docker Compose Override

Create a docker-compose.override.yml file in your project root to add the volume mount for local development:

version: "3"

services:
  web:
    volumes:
      # Mount parent directory containing all sibling projects for local development
      - ../:/var/www/code

Important:

• This file is gitignored, so each developer creates their own
• The ../:/var/www/code mount makes all sibling directories available inside the Docker container at /var/www/code/
• Docker Compose automatically merges this with the main docker-compose.yml

2. Configure Composer for Local Packages

Add path repositories to your composer.json repositories section. Place these at the top of the repositories array so they take priority over remote repositories:

{
  "repositories": [
    {
      "type": "path",
      "url": "/var/www/code/WP-Theme-GCU-News",
      "options": {
        "symlink": true
      }
    },
    {
      "type": "path",
      "url": "/var/www/code/WP-Plugin-Blog-Posts",
      "options": {
        "symlink": true
      }
    },
    // ... your existing remote repositories
  ]
}

That's it! Composer will automatically use your local packages when they match the package names in your require section, regardless of the version constraints.

3. Directory Structure Mapping

The Docker container maps directories as follows:

Host Path	Container Path	Purpose
./ (current project)	/var/www/html	Main WordPress project
../ (parent directory)	/var/www/code	Access to sibling projects
../WP-Theme-GCU-News	/var/www/code/WP-Theme-GCU-News	Local theme repository

Usage

Installing Local Packages

1. Ensure your local repositories exist in the expected locations
2. Start the Docker stack if not already running:

just up

3. Install/update packages using the just command:

# Install all packages
just composer install

# Update packages
just composer update

# Install specific package
just composer "require gce/gce-base-gcu-news"

Composer will automatically use your local packages instead of downloading from remote repositories.

Verifying Local Package Installation

Check that your local packages are being used:

# Check installed packages
just composer show

# Verify specific package source (verbose output)
just composer "show gce/gce-base-gcu-news -v"

Local packages will show a source type of path instead of dist.

Switching Between Local and Remote

To temporarily use remote packages:

1. Comment out or remove the path repository from composer.json
2. Run just composer update

To switch back to local:

1. Restore the path repository
2. Run just composer update

Troubleshooting

Package Not Found Errors

If you get errors like:

The `url` supplied for the path (/var/www/code/WP-Theme-GCU-News) repository does not exist

Solutions:

1. Verify the local repository exists in your Code directory
2. Check the path in composer.json matches the actual directory name
3. Ensure the directory contains a valid composer.json file

Container Can't Access Sibling Directories

If the container can't find /var/www/code/:

1. Ensure you have created the docker-compose.override.yml file with the volume mount
2. Restart the container: just down && just up
3. Check container mounts: just composer "exec ls -la /var/www/code"

Package Version Conflicts

If you get version constraint conflicts:

1. Clear composer cache: just composer clear-cache
2. Delete vendor directory and reinstall: just composer "exec rm -rf vendor" && just composer install
3. If the local package version doesn't satisfy constraints, you may need to update the version in your local package's composer.json

Quick Start Guide

For developers setting up this project for the first time:

# 1. Clone the project
git clone [repository-url] WP-GCU-News-v2
cd WP-GCU-News-v2

# 2. Create docker-compose.override.yml for local development (if needed)
# See step 1 in setup instructions above

# 3. Initial setup (includes composer install)
just init

# 4. If you have local packages, add them to composer.json and update
just composer update

For ongoing development:

# Start the stack
just up

# Install/update packages
just composer install
just composer update

# Stop the stack
just down

Developer Setup Checklist

• Code directory structure matches expected layout
• Local repositories exist and contain valid composer.json files
• Created docker-compose.override.yml with parent directory mount (../:/var/www/code)
• Composer repositories section includes path repositories with correct paths
• Container can access /var/www/code directory

Example Complete Configuration

docker-compose.override.yml:

version: "3"

services:
  web:
    volumes:
      # Mount parent directory containing all sibling projects for local development
      - ../:/var/www/code

composer.json repositories section:

"repositories": [
  {
    "type": "path",
    "url": "/var/www/code/WP-Theme-GCU-News",
    "options": {
      "symlink": true
    }
  },
  {
    "type": "composer",
    "url": "https://wpackagist.org",
    "only": ["wpackagist-plugin/*", "wpackagist-theme/*"]
  }
]

This setup provides a seamless development experience where local packages are automatically used when available, similar to npm's yalc functionality.