Wordpress Core Installer Laravel Package

Getting Started

Minimal Steps to First Use

1. Add to composer.json:

   {
       "require": {
           "johnpbloch/wordpress-core-installer": "^2.0"
       },
       "extra": {
           "installer-paths": {
               "wp/": ["type:wordpress-core"]
           }
       }
   }
   

   • Replace wp/ with your desired WordPress root directory (e.g., wordpress/).

2. Initialize WordPress Core:

   composer require wordpress/wordpress:^5.0
   

   • This installs WordPress core outside vendor/ into the specified directory (e.g., wp/).

3. Configure wp-config.php:

   • Move wp-config.php to your WordPress root (e.g., wp/wp-config.php).
   • Update WP_CONTENT_DIR and WP_CONTENT_URL to point to a custom location (e.g., ../wp-content):

     define('WP_CONTENT_DIR', dirname(__DIR__) . '/wp-content');
     define('WP_CONTENT_URL', '/wp-content');
     

4. Symlink wp-content (Optional but Recommended):

   ln -s ../wp-content wp/wp-content
   

   • Ensures wp-content is outside the WordPress core directory and preserved during updates.

5. Verify Installation:

   • Run composer install and check that WordPress files are installed in wp/ but wp-content remains untouched.

First Use Case: Laravel + WordPress Hybrid

If integrating with Laravel (e.g., for a headless WordPress setup):

1. Directory Structure:

   /project-root
     ├── laravel/          # Laravel app
     ├── wp/               # WordPress core (managed by this package)
     └── wp-content/       # Shared or separate wp-content
   

2. Laravel Routing: In laravel/routes/web.php, proxy WordPress requests:

   Route::prefix('wp')->group(function () {
       require __DIR__ . '/../wp/wp-load.php';
   });
   

3. Composer Workflow:
   • Use composer update wordpress/wordpress to update WordPress core without touching wp-content.
   • Laravel’s vendor/ remains separate, avoiding conflicts.

Implementation Patterns

Core Workflow: Composer-Driven WordPress Updates

1. Installation:

   composer require wordpress/wordpress:^5.0
   

   • WordPress core is installed to wp/ (or custom path via wordpress-install-dir in extra).

2. Updates:

   composer update wordpress/wordpress
   

   • Only updates WordPress core; wp-content is preserved due to symlinking.

3. Custom Paths: Override default wp/ location in composer.json:

   "extra": {
       "wordpress-install-dir": "custom-wordpress-path"
   }
   

Laravel Integration Patterns

Pattern 1: WordPress as a Submodule

• Use Case: Laravel serves as an API frontend to WordPress (e.g., REST API).
• Steps:
  1. Install WordPress in /wp using this package.
  2. Configure Laravel’s index.php to route /wp* to WordPress:

     if (file_exists($wp = __DIR__ . '/../wp/wp-load.php')) {
         require $wp;
     }
     

  3. Use Laravel’s Route::prefix('wp') for WordPress admin routes.

Pattern 2: Shared wp-content

• Use Case: WordPress plugins/themes are shared between Laravel and WordPress.
• Steps:
  1. Symlink Laravel’s storage/app/wp-content to WordPress:

     ln -s ../../laravel/storage/app/wp-content wp/wp-content
     

  2. Configure wp-config.php:

     define('WP_CONTENT_DIR', dirname(__DIR__) . '/laravel/storage/app/wp-content');
     

Pattern 3: CI/CD Pipeline

• Use Case: Automate WordPress core updates in GitHub Actions.
• Example Workflow:

  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: actions/setup-php@v3
        - run: composer install --prefer-dist --no-dev
        - run: composer update wordpress/wordpress
        - run: php laravel/artisan config:clear
  

Advanced: Multi-Environment Deployments

1. Environment-Specific Config: Use Laravel’s env() to dynamically set WordPress paths:

   define('WP_CONTENT_DIR', base_path('wp-content-' . env('APP_ENV')));
   

2. Composer Environment Variables: Override paths per environment in composer.json:

   "extra": {
       "wordpress-install-dir": {
           "wordpress/wordpress": {
               "dev": "wp-dev",
               "prod": "wp-prod"
           }
       }
   }
   

Gotchas and Tips

Pitfalls

1. Symlink Issues:

   • Problem: wp-content symlinks may break if Laravel’s storage/ is excluded from Git or not writable.
   • Fix: Ensure wp-content is a relative symlink (not absolute) and test permissions:

     ln -s ../wp-content wp/wp-content  # Relative path
     chmod -R 755 wp/wp-content
     

2. Composer Autoload Conflicts:

   • Problem: WordPress and Laravel may both define classes (e.g., WP_Query vs. Laravel’s QueryBuilder).
   • Fix: Use Laravel’s ClassLoader to exclude WordPress files:

     $loader = require __DIR__ . '/../vendor/autoload.php';
     $loader->addPsr4('App\\', __DIR__ . '/../laravel/app');
     $loader->addPsr4('WordPress\\', __DIR__ . '/../wp/wp-includes');
     

3. WordPress Updates Breaking Laravel:

   • Problem: WordPress core updates may modify wp-includes/load.php, breaking Laravel’s bootstrap.
   • Fix: Test updates in a staging environment and use composer why-not wordpress/wordpress to debug constraints.

4. GPL License Conflicts:

   • Problem: GPL-2.0 may conflict with Laravel’s MIT license if used in proprietary projects.
   • Fix: Review GPL compatibility or use a permissive alternative like wp-php.

5. Stale Package Maintenance:

   • Problem: Last release in 2020; may not support PHP 8.x or Composer v2 features.
   • Fix: Fork the package and update dependencies (e.g., composer.json):

     "require": {
         "composer/composer": "^2.0",
         "php": "^8.0"
     }
     

Debugging Tips

1. Verify Installation:

   composer show wordpress/wordpress
   ls -la wp/  # Check if WordPress files exist
   

2. Check Symlinks:

   ls -la wp/wp-content  # Should point to ../wp-content
   

3. Composer Debug:

   composer diagnose
   composer why wordpress/wordpress
   

4. WordPress Bootstrap Issues:

   • If Laravel fails to load WordPress, check:
     • wp/wp-load.php exists.
     • No PHP errors in wp/wp-config.php.
     • Permissions on wp/ directory (chmod -R 755 wp/).

Extension Points

1. Custom Installer Logic: Extend the installer by creating a custom Composer plugin:

   namespace App\Composer;
   
   use Composer\Plugin\PluginInterface;
   use Composer\IO\IOInterface;
   use Composer\Composer;
   
   class WordPressCustomizer implements PluginInterface {
       public function activate(Composer $composer, IOInterface $io) {
           // Hook into WordPress installation
       }
   }
   

2. Post-Install Scripts: Use Composer’s post-install-cmd to run Laravel migrations after WordPress install:

   "scripts": {
       "post-install-cmd": [
           "php laravel/artisan migrate --force",
           "php laravel/artisan wp:setup"  // Custom Artisan command
       ]
   }
   

3. Dynamic Paths: Use Laravel’s config() to set WordPress paths dynamically:

   define('WP_CONTENT_DIR', config('wordpress.content_dir'));
   

   Configure in .env:

   WORDPRESS_CONTENT_DIR=/path