feat(pantheon): add support for root-level WordPress installations

[thejimbirch]

Description

Teamwork Ticket(s): Pantheon Root-Level WordPress Support

• Was AI used in this pull request?

As a developer working on legacy Pantheon WordPress sites, I need to support root-level WordPress installations (without a webroot subdirectory) so that older sites can use this DDEV add-on without restructuring their entire codebase.

This PR adds comprehensive support for Pantheon sites that have WordPress installed at the application root level instead of in a web/ subdirectory. This is common for older Pantheon sites or sites migrated from other hosting providers. The changes introduce a configurable DOCROOT environment variable that can be set to an empty string for root-level installations, and updates all commands, nginx configuration, and scripts to handle both modern (web/) and legacy (root) directory structures.

Acceptance Criteria

• Configuration wizard (ddev project-configure) prompts for document root with clear guidance for modern vs. legacy sites
• Empty/blank docroot input correctly configures for root-level WordPress installation
• All commands handle both web/ subdirectory and root-level WordPress paths correctly:
  • project-init checks mu-plugins at correct path
  • project-wp uses correct docroot path
  • theme-activate references correct theme path
  • refresh-pantheon.sh navigates to correct directory
• Nginx configuration template uses {{DOCROOT}} placeholder that gets replaced with actual path during project-configure
• Nginx root directive correctly set to /var/www/html for empty docroot or /var/www/html/web for configured subdirectory
• install.yaml post-install actions handle wp-config.php and mu-plugins at correct paths for both configurations
• Documentation clearly explains modern vs. legacy site configurations with troubleshooting guidance
• Existing projects with web/ subdirectory continue working without changes (backward compatible)
• New integration test validates root-level WordPress configuration end-to-end

Assumptions

• Legacy Pantheon sites with root-level WordPress have wp-config.php, wp-content/, wp-includes/, and wp-admin/ at the repository root
• Modern Pantheon sites continue using web/ as the recommended docroot
• The DOCROOT environment variable can be set to empty string ("") or omitted entirely to indicate root-level installation
• Users running ddev project-configure will be prompted to enter the correct docroot for their site structure
• Empty string input (just pressing Enter) or explicitly entering "." will be normalized to empty docroot

Steps to Validate

Test 1: New Project with Root-Level WordPress (Legacy)

1. Create a new test directory and initialize DDEV:

   mkdir test-root-wp && cd test-root-wp
   ddev config --project-name=test-root --project-type=wordpress --docroot="" --create-docroot

2. Install the add-on:

   ddev add-on get kanopi/ddev-kanopi-wp

3. Run configuration wizard and select Pantheon:

   ddev project-configure
   # When prompted for docroot, press Enter without input or type "." 

4. Verify .ddev/config.yaml shows docroot: "" or docroot:
5. Verify .ddev/nginx_full/nginx-site.conf has root /var/www/html; (no subdirectory)
6. Start DDEV and verify nginx serves from correct path:

   ddev start
   ddev exec "grep 'root /var/www/html;' /etc/nginx/sites-enabled/nginx-site.conf"

Test 2: New Project with web/ Subdirectory (Modern - Default)

1. Create a new test directory with web/ subdirectory:

   mkdir test-web-wp && cd test-web-wp
   ddev config --project-name=test-web --project-type=wordpress --docroot=web --create-docroot

2. Install the add-on and configure for Pantheon:

   ddev add-on get kanopi/ddev-kanopi-wp
   ddev project-configure
   # When prompted for docroot, enter "web" or accept default

3. Verify .ddev/config.yaml shows docroot: web
4. Verify nginx uses /var/www/html/web as root

Test 3: Existing Project Migration (Backward Compatibility)

1. Use an existing project already configured with web/ subdirectory
2. Upgrade add-on to this version
3. Verify project continues working without any changes

Test 4: Integration Test Suite

Run the new integration test:

bats tests/test.bats -f "pantheon root-level wordpress configuration"

Affected URL

Local DDEV test environments

Deploy Notes

Configuration Files Changed

• .ddev/config.yaml: New DOCROOT environment variable for Pantheon projects (empty string for root, "web" for subdirectory)
• .ddev/scripts/load-config.sh: Added DOCROOT export for Pantheon provider with empty string default
• .ddev/nginx_full/nginx-site.conf: Changed from hardcoded /var/www/html/web to template placeholder {{DOCROOT}} that gets replaced during configuration

Commands Modified

• commands/host/project-configure: Added docroot prompt for Pantheon projects, normalizes empty/dot input, updates nginx configuration with correct root path
• commands/host/project-init: Handles mu-plugins path based on DOCROOT configuration
• commands/host/project-wp: Determines correct docroot path for WordPress installation
• commands/web/theme-activate: Uses configured DOCROOT for theme path resolution
• scripts/refresh-pantheon.sh: Navigates to correct directory based on DOCROOT value

Installation Actions Modified

• install.yaml: All post-install and removal actions updated to handle empty DOCROOT:
  • wp-config.php path detection and modification
  • Pantheon mu-plugin conflict handling
  • Path normalization for root-level WordPress

Testing Added

• tests/test.bats: New test case "pantheon root-level wordpress configuration" validates complete workflow for empty docroot

Documentation Updates

• README.md: Added Docroot column to hosting provider comparison table
• CLAUDE.md: Updated Pantheon section with root-level WordPress support note
• docs/providers/pantheon.md: Added comprehensive section on WordPress installation locations, configuration examples, troubleshooting 404 errors, and migration guidance

Post-Deployment Actions Required

For New Projects:

1. Run ddev project-configure to set up DOCROOT variable
2. When prompted for document root:
   • Modern sites: Enter "web" (recommended)
   • Legacy sites: Press Enter without input for root-level WordPress
3. Run ddev restart to apply nginx configuration changes

For Existing Projects:

1. Existing projects with web/ subdirectory continue working without changes
2. Optionally run ddev project-configure to explicitly set DOCROOT in environment variables
3. No database updates required
4. No composer or npm dependencies added

Breaking Changes

None - this is a backward-compatible enhancement. Existing projects with web/ subdirectory continue working without modification.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com