Checksum Command Laravel Package

## Getting Started

### Minimal Steps
1. **Installation**: No additional installation required—this package ships with WP-CLI. For the latest version (v2.3.7), ensure you're using the latest WP-CLI:
   ```bash
   wp package update --all

Or install directly:

wp package install git@github.com:wp-cli/checksum-command.git

2. First Use Case: Verify WordPress core files against official checksums:

   wp core verify-checksums
   

   • For plugins, verify a specific plugin (e.g., Akismet):

     wp plugin verify-checksums akismet
     

   • Verify all plugins:

     wp plugin verify-checksums --all
     

3. Where to Look First:

   • Command Reference: Focus on the two primary commands:
     • wp core verify-checksums
     • wp plugin verify-checksums
   • Options: Pay attention to flags like --version, --locale, --exclude, and --format for granular control.
     • Note: The --exclude parameter now trims whitespace from values (fixed in v2.3.7), so trailing spaces in exclusion lists are no longer problematic.
   • Output Formats: Use --format=json or --format=csv for programmatic integration (e.g., CI/CD pipelines).

Implementation Patterns

Usage Patterns

1. Core File Integrity Checks:

   • Post-Update Verification: Run after updating WordPress to ensure no files were tampered with:

     wp core verify-checksums --version=$(wp core version)
     

   • Root Directory Scan: Include non-WordPress root files (e.g., .env, wp-config.php) with --include-root:

     wp core verify-checksums --include-root --exclude="wp-config.php,.env"
     

     • Note: Ensure exclusion lists are clean—whitespace is now automatically trimmed (v2.3.7).

2. Plugin-Specific Workflows:

   • Selective Verification: Target high-risk plugins (e.g., WooCommerce, Jetpack):

     wp plugin verify-checksums woocommerce jetpack --strict
     

   • Version Pinning: Verify plugins against a specific version (useful for rollbacks):

     wp plugin verify-checksums akismet --version=5.0
     

   • Exclusion Lists: Skip plugins with known false positives (e.g., custom-coded plugins):

     wp plugin verify-checksums --all --exclude="custom-plugin, my-theme"  # Whitespace trimmed automatically
     

3. Automation in CI/CD:

   • JSON Output for Scripting: Pipe results to a script for further processing:

     wp plugin verify-checksums --all --format=json | jq '.[] | select(.message != null)'
     

   • Failure Handling: Exit with non-zero status on mismatches:

     wp core verify-checksums || exit 1
     

4. Debugging and Maintenance:

   • Insecure Mode: Bypass TLS issues in restricted environments (use cautiously):

     wp plugin verify-checksums --insecure
     

   • Must-Use Plugins: Include/exclude must-use plugins:

     wp plugin verify-checksums --exclude-mu-plugins
     

Integration Tips

1. Laravel-Specific Adaptations:

   • Artisan Task Wrapper: Create a custom Artisan command to integrate checksum verification into Laravel’s deployment workflow:

     // app/Console/Commands/VerifyWordPressChecksums.php
     namespace App\Console\Commands;
     
     use Illuminate\Console\Command;
     use Symfony\Component\Process\Process;
     use Symfony\Component\Process\Exception\ProcessFailedException;
     
     class VerifyWordPressChecksums extends Command
     {
         protected $signature = 'wp:verify-checksums {--core|--plugins}';
         protected $description = 'Verify WordPress core or plugin checksums';
     
         public function handle()
         {
             $process = new Process(['wp', 'core', 'verify-checksums']);
             if ($this->option('plugins')) {
                 $process = new Process(['wp', 'plugin', 'verify-checksums', '--all']);
             }
     
             $process->run();
             if (!$process->isSuccessful()) {
                 throw new ProcessFailedException($process);
             }
     
             $this->info($process->getOutput());
         }
     }
     

   • Deployment Hook: Trigger checksum verification post-deploy in app/Providers/AppServiceProvider:

     public function boot()
     {
         if (app()->environment('production')) {
             \Artisan::call('wp:verify-checksums', ['--core' => true]);
         }
     }
     

2. Custom Checksum Sources:

   • Extend the package to fetch checksums from private repositories (e.g., GitHub Enterprise) by overriding WpOrgApi:

     // app/Services/CustomChecksumService.php
     namespace App\Services;
     
     use WP_CLI\Utils;
     
     class CustomChecksumService
     {
         public function verifyChecksums(string $path, array $expectedChecksums): array
         {
             // Custom logic to fetch/checksums from your source
             return Utils\get_checksums($path, $expectedChecksums);
         }
     }
     

3. Logging and Alerts:

   • Log checksum results to Laravel’s log system:

     \Log::info('Checksum verification results', [
         'output' => $process->getOutput(),
         'return_code' => $process->getReturnCode(),
     ]);
     

   • Integrate with monitoring tools (e.g., Laravel Horizon) to alert on checksum failures.

Gotchas and Tips

Pitfalls

1. Locale/Version Mismatches:

   • Issue: Running wp core verify-checksums without --locale or --version may fail if the installed WordPress version/locale differs from the default checksum source.
   • Fix: Always specify --locale and --version explicitly:

     wp core verify-checksums --locale=en_US --version=$(wp core version)
     

2. False Positives:

   • Issue: Customized files (e.g., wp-config.php, readme.html) or plugins with dynamic content (e.g., version.php) may trigger false mismatches.
   • Fix: Use --exclude to skip known false positives. Note: Whitespace in exclusion values is now trimmed automatically (v2.3.7):

     wp core verify-checksums --exclude="wp-config.php, readme.html"  # Works as expected
     

3. Network Restrictions:

   • Issue: TLS handshake failures in restricted environments (e.g., corporate networks) block checksum downloads.
   • Fix: Use --insecure as a last resort (acknowledge MITM risks):

     wp plugin verify-checksums --insecure
     

4. Must-Use Plugins:

   • Issue: Must-use plugins (mu-plugins) are excluded by default in wp plugin verify-checksums.
   • Fix: Explicitly include them if needed (not recommended for security-sensitive environments):

     wp plugin verify-checksums --exclude-mu-plugins=false
     

5. PHP Version Compatibility:

   • Issue: Older PHP versions (<7.4) may fail due to strict type checks or deprecated functions.
   • Fix: Ensure PHP 7.4+ is used, or pin to a compatible version of checksum-command.

6. Exclusion List Quirks:

   • Issue: Previously, trailing whitespace in --exclude values could cause unexpected behavior.
   • Fix: Updated in v2.3.7—whitespace is now trimmed automatically. Example:

     wp plugin verify-checksums --exclude="custom-plugin, my-plugin "  # Works as "custom-plugin, my-plugin"
     

Debugging Tips

1. Verbose Output:

   • Use --debug with WP-CLI to diagnose issues:

     WP_CLI_DEBUG=1 wp plugin verify-checksums --debug
     

2. Manual Checksum Comparison:

   • Download checksums manually to verify the package’s behavior:

     curl -O https://downloads.wordpress.org/release/core.md5
     

   • Compare with local files:

     md5sum -c core.md5
     

3. Testing Edge Cases:

   • Test with plugins known to have checksum quirks (e.g., Hello Dolly):

     wp plugin verify-checksums hello --strict
     

4. CI/CD Debugging:

   • Capture output in CI for debugging:

     # .github/workflows/ci.yml
     steps:
       - run: wp plugin verify-checksums