Wordpress Core Installer Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require metabolism/wordpress-core-installer johnpbloch/wordpress-core
   

   Ensure composer/installers (≥2.0) is also installed (auto-included via metabolism/wordpress-core-installer).

2. Configure composer.json Add the installer-paths entry under extra to define where WordPress should be installed:

   {
     "extra": {
       "installer-paths": {
         "web/edition/": ["type:wordpress-core"]
       }
     }
   }
   

   • Replace web/edition/ with your target directory (relative to project root).

3. First Use Case Run:

   composer install
   

   WordPress core files will now be installed to web/edition/ automatically.

Implementation Patterns

Workflow Integration

1. Multi-Environment Setups Use environment-specific composer.json files (e.g., composer.dev.json, composer.prod.json) to override installer-paths:

   // composer.prod.json
   {
     "extra": {
       "installer-paths": {
         "public_html/": ["type:wordpress-core"]
       }
     }
   }
   

2. Custom WordPress Version Specify a version constraint in require:

   {
     "require": {
       "johnpbloch/wordpress-core": "6.4.*"
     }
   }
   

3. Post-Install Hooks Use Composer’s post-install-cmd or post-update-cmd to run scripts (e.g., database setup, theme activation):

   {
     "scripts": {
       "post-install-cmd": [
         "php artisan wordpress:setup --path=web/edition/"
       ]
     }
   }
   

Laravel-Specific Patterns

1. Service Provider Integration Dynamically detect WordPress paths in a Laravel service provider:

   use Metabolism\WordpressCoreInstaller\Installer;
   
   public function boot()
   {
       $installer = new Installer();
       $wordpressPath = $installer->getInstallPath('web/edition/');
       config(['wordpress.path' => $wordpressPath]);
   }
   

2. Artisan Commands Extend Laravel’s Artisan to interact with WordPress:

   // app/Console/Commands/WordpressCommand.php
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use Metabolism\WordpressCoreInstaller\Installer;
   
   class WordpressCommand extends Command
   {
       protected $signature = 'wordpress:info';
       protected $description = 'Show WordPress installation details';
   
       public function handle()
       {
           $installer = new Installer();
           $path = $installer->getInstallPath('web/edition/');
           $this->info("WordPress installed at: {$path}");
       }
   }
   

3. Environment Configuration Use Laravel’s .env to override paths:

   WORDPRESS_PATH=web/edition
   

   Then access it via:

   $path = env('WORDPRESS_PATH');
   

Gotchas and Tips

Pitfalls

1. Path Resolution Conflicts

   • Ensure installer-paths keys are absolute relative paths (no ./ or ../). Example:

     "web/edition/"  // Correct
     "./web/edition" // Fails
     

   • Debug Tip: Use composer show -i to verify installed paths.

2. Composer Installers Version Mismatch

   • If using composer/installers:^1.0, downgrade to ~1.0 or upgrade to ~2.0 (as of v1.1.2 of this package).
   • Fix: Run composer require composer/installers:^2.0.

3. WordPress Core Updates

   • Updates via Composer only modify core files, not wp-config.php or wp-content/. Back up manually or use a script:

     composer update johnpbloch/wordpress-core --with-all-dependencies
     

4. Permissions Issues

   • WordPress requires writable directories (e.g., wp-content/). Set permissions post-install:

     chmod -R 755 web/edition/
     chown -R www-data:www-data web/edition/  # Adjust user/group as needed
     

Debugging

1. Verify Installation Check if the installer is registered:

   composer show metabolism/wordpress-core-installer
   

   Look for installer-paths in the output.

2. Enable Composer Debug Mode Run Composer with -vvv to trace installation:

   composer install -vvv
   

3. Check for Overrides Conflicts may arise if multiple packages define installer-paths. Use:

   composer config extra.installer-paths
   

   To inspect merged configurations.

Extension Points

1. Custom Installer Logic Extend the installer by subclassing Metabolism\WordpressCoreInstaller\Installer:

   namespace App\Installers;
   
   use Metabolism\WordpressCoreInstaller\Installer as BaseInstaller;
   
   class CustomWordpressInstaller extends BaseInstaller
   {
       public function getInstallPath($path)
       {
           $path = parent::getInstallPath($path);
           // Add custom logic (e.g., append subdirectory)
           return $path . 'custom/';
       }
   }
   

   Register it in composer.json:

   {
     "extra": {
       "installer-classes": {
         "type:wordpress-core": "App\\Installers\\CustomWordpressInstaller"
       }
     }
   }
   

2. Pre/Post-Install Scripts Use Composer scripts to automate post-install tasks:

   {
     "scripts": {
       "post-install-cmd": [
         "@php artisan config:clear",
         "@php artisan cache:clear"
       ]
     }
   }
   

3. CI/CD Integration For GitHub Actions/GitLab CI, ensure composer install runs in a clean environment:

   # .github/workflows/deploy.yml
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install --no-dev --optimize-autoloader
         - run: chmod -R 755 web/edition/