Config Command Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require wp-cli/config-command
   

   Ensure WP-CLI is installed globally (wp --info to verify).

2. First Use Case: Generate a wp-config.php for a new WordPress install:

   wp config create --dbname=my_db --dbuser=my_user --dbpass=my_pass
   

   Verify the file:

   wp config list
   

3. Key Commands to Explore:

   • wp config get DB_NAME → Retrieve a specific value.
   • wp config add WP_DEBUG true --raw → Add a constant.
   • wp config edit → Manually edit the file.

Where to Look First

• README.md: For command syntax and examples.
• features/ directory: Behat tests for real-world usage patterns.
• tests/ directory: PHPUnit tests for edge cases and validation logic.

Implementation Patterns

Core Workflows

1. Environment Setup

• Dynamic Config Generation: Use wp config create with --extra-php to inject custom PHP snippets (e.g., custom constants, API endpoints):

  wp config create --dbname=test --dbuser=admin --extra-php <<PHP
  define('MY_CUSTOM_CONST', 'value');
  PHP
  

• Multi-Environment Handling: Combine with .env files for local/dev/prod separation:

  wp config add DB_PASSWORD "$(grep DB_PASSWORD .env | cut -d'=' -f2)" --raw
  

2. CI/CD Integration

• Automated Config Validation: Add to deployment scripts to verify wp-config.php exists and is valid:

  wp config list --format=json | jq '.[] | select(.key | test("DB_"))'
  

• Secrets Management: Use --prompt to securely input sensitive data (e.g., database passwords) without logging:

  wp config create --dbname=prod_db --prompt=dbpass
  

3. Local Development

• Toggle Debugging: Quickly enable/disable WP_DEBUG:

  wp config set WP_DEBUG true --raw
  

• Salts Rotation: Regenerate salts for security:

  wp config shuffle-salts
  

4. Custom Plugins/Themes

• Runtime Config Overrides: Use wp config add to inject theme/plugin-specific constants:

  wp config add MY_THEME_OPTIONS '{"color": "blue"}' --raw
  

• Conditional Logic: Check for config values in PHP:

  if (wp_config_is_true('WP_CACHE')) {
      // Enable caching logic
  }
  

Integration Tips

Laravel-Specific Patterns

1. Service Provider Bootstrapping: Load wp-config.php values into Laravel’s config:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       $wpConfig = shell_exec('wp config list --format=json');
       $wpConfig = json_decode($wpConfig, true);
       foreach ($wpConfig as $item) {
           config([$item['key'] => $item['value']]);
       }
   }
   

2. Artisan Command Integration: Extend Laravel’s CLI with WP-CLI commands:

   # In a custom Artisan command:
   $wpDebug = shell_exec('wp config is-true WP_DEBUG');
   if ($wpDebug) {
       $this->info('WP_DEBUG is enabled!');
   }
   

3. Environment-Specific Configs: Use wp config to override Laravel’s .env:

   # Sync Laravel's .env with wp-config.php
   wp config list DB_HOST DB_NAME | while read -r line; do
       key=$(echo $line | awk '{print $1}')
       value=$(echo $line | awk '{print $2}')
       sed -i "s/^${key}=.*/${key}=${value}/" .env
   done
   

4. Deployment Hooks: Trigger wp config commands in Laravel’s deploy.php (Deployer):

   task('deploy:wp-config', function () {
       run('wp config create --dbname={{ db_name }} --dbuser={{ db_user }} --dbpass={{ db_password }}');
       run('wp config add WP_ENV {{ env }} --raw');
   });
   

Gotchas and Tips

Pitfalls

1. File Permissions:

   • wp-config.php must be writable by the web server user (e.g., www-data or apache).
   • Fix: Run chmod 644 wp-config.php after generation.

2. Anchor Misplacement:

   • Using --anchor=EOF may append values to the end of the file, breaking WordPress’s parsing logic.
   • Tip: Prefer --anchor="/* That's all, stop editing!" for safety.

3. Raw Values vs. Quoted Strings:

   • --raw bypasses escaping, which can break syntax (e.g., unescaped quotes in JSON).
   • Example:

     # Bad: Breaks if value contains quotes
     wp config add MY_JSON '{"key": "value"}' --raw
     # Good: Escaped automatically
     wp config add MY_JSON '{"key": "value"}'  # No --raw
     

4. Case Sensitivity:

   • Constants/variables in wp-config.php are case-sensitive (e.g., WP_DEBUG ≠ wp_debug).
   • Debugging: Use wp config list to verify exact casing.

5. Multisite Conflicts:

   • Editing wp-config.php in a multisite network may require --config-file to target the correct wp-config.php (e.g., /path/to/network/wp-config.php).

6. PHP Version Incompatibility:

   • Older PHP versions (<7.2) may fail to parse wp-config.php with modern syntax (e.g., arrow functions in --extra-php).
   • Workaround: Use basic PHP syntax in --extra-php.

Debugging Tips

1. Validate Syntax:

   wp config list --format=json | jq -r '.[] | "define(\"' + .key + "', \'' + .value + '\'' + ');"'
   

   Copy the output to a temporary file and test with php -l temp.php.

2. Check Exit Codes:

   • Non-zero exit codes indicate errors (e.g., wp config add failing silently).
   • Debug: Redirect output to a file:

     wp config add WP_DEBUG true --raw 2> debug.log
     

3. Dry Runs:

   • Use --config-file=/tmp/wp-config.php to test changes on a copy before applying to production.

4. Log Parsing Errors:

   • Enable WordPress debugging in wp-config.php temporarily:

     wp config add WP_DEBUG_LOG true --raw
     wp config add WP_DEBUG_DISPLAY false --raw
     

Extension Points

1. Custom Commands: Extend the package by creating a subclass of WP_CLI\Config_Command:

   // src/Commands/CustomConfigCommand.php
   class CustomConfigCommand extends \WP_CLI\Config_Command {
       public function __construct() {
           parent::__construct();
           $this->add_hook('config:list', [$this, 'filter_list_output'], 10, 2);
       }
   
       public function filter_list_output($items, $args) {
           return array_filter($items, fn($item) => strpos($item['key'], 'MY_') === 0);
       }
   }
   

2. Pre/Post-Hooks: Use WordPress filters to intercept config operations:

   add_filter('wp_config_add_value', function($value, $name) {
       if ($name === 'WP_HOME') {
           return 'https://custom.url';
       }
       return $value;
   }, 10, 2);
   

3. Custom Formats: Override output formats (e.g., add ini format to wp config list):

   // Add to a service provider
   WP_CLI::add_hook('config:list:format:ini', function($items, $args) {
       $output = "[config]\n";
       foreach ($items as $item) {
           $output .= sprintf("%s = %s\n", $item['key'], $item['value']);
       }
       return $output;
   });
   

4. Backup/Restore: Create a backup before modifying wp-config.php:

   cp wp-config.php wp-config.php.bak
   wp config create --force  # Overwrite with new config
   

Pro Tips

1. Template-Based Generation: Use --extra-php with heredoc templates for complex configs