Sympatch Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation: Add to composer.json:

   "require": {
       "dhorchler/sympatch-bundle": "dev-master"
   }
   

   Run:

   composer update dhorchler/sympatch-bundle
   

2. Enable Bundle: Register in app/AppKernel.php:

   new DHorchler\SympatchBundle\DHorchlerSympatchBundle(),
   

3. Create Patch File: Use Resources/patch/patches_examples.xml as a template. Save your patch file as Resources/patch/patches_[name].xml.

4. First Use Case: List available patches:

   php app/console patch --func=list
   

Implementation Patterns

Usage Patterns

1. Patching Workflow:

   • Define patches in XML files under Resources/patch/ (e.g., patches_custom.xml).
   • Use line numbers or before/after code fragments for precision.
   • Example XML structure:

     <patch>
         <file>src/Acme/DemoBundle/Controller/DefaultController.php</file>
         <location type="line">42</location>
         <patch>
             <before>public function indexAction() { ... }</before>
             <after>public function indexAction() { ... custom logic ... }</after>
         </patch>
     </patch>
     

2. Applying Patches:

   • Apply all patches:

     php app/console patch --func=apply
     

   • Apply a specific patch file:

     php app/console patch --file=patches_custom.xml
     

3. Deactivating Patches:

   • Disable patches temporarily (e.g., before composer update):

     php app/console patch --func=disable
     

   • Re-enable later:

     php app/console patch --func=enable
     

4. Vendor Patching:

   • Patch third-party libraries by targeting their files (e.g., vendor/symfony/symfony/src/Symfony/...).
   • Backup original files automatically (.org extension).

5. Debugging Patches:

   • Dry-run patches to preview changes:

     php app/console patch --func=apply --dry-run
     

Integration Tips

• Version Control: Commit patch files (Resources/patch/) to track changes across deployments.
• CI/CD Pipelines: Automate patch application in deployment scripts (e.g., post-clone hooks).
• Collaboration: Share patch files with clients for minor fixes without codebase access.

Gotchas and Tips

Pitfalls

1. Discontinued Maintenance:

   • The bundle is discontinued; use at your own risk. Consider alternatives like php-patch or custom scripts.
   • No active bug fixes or Symfony 5+ compatibility.

2. XML Complexity:

   • Malformed XML breaks patching. Validate against patches_examples.xml.
   • Avoid special characters in patch content (e.g., unescaped <, >).

3. File Permissions:

   • Ensure write access to patched files (e.g., vendor/, src/).
   • Backups (.org files) may fail if disk space is limited.

4. Composer Conflicts:

   • Patching vendor files can cause issues during composer update. Always:
     1. Disable patches (--func=disable).
     2. Update dependencies.
     3. Re-enable patches (--func=enable).

5. Line Number Sensitivity:

   • Patches tied to line numbers break if the file changes. Prefer before/after fragments for stability.

Debugging

• Verify Patches: Use --func=listall to confirm loaded patches before applying.
• Check Backups: Inspect .org files for correctness if patches fail.
• Log Output: Enable verbose mode for detailed errors:

  php app/console patch --func=apply --verbose
  

Extension Points

1. Custom Patch Storage: Override the default Resources/patch/ location via config (if supported).
2. Pre/Post-Patch Hooks: Extend the bundle’s console command to run scripts before/after patching.
3. Alternative Formats: Convert XML patches to YAML/JSON for easier maintenance (post-processing).

Tips

• Backup Strategy: Regularly back up .org files to a version control system.
• Patch Naming: Use descriptive names (e.g., patches_fix_login_bug.xml).
• Testing: Test patches in a staging environment before production.
• Alternatives: For modern Laravel/Symfony, consider:
  • Laravel: Use php artisan patch with custom scripts or envoy.
  • Symfony: Explore Patchwork or Rector.