- Can Patchwork safely redefine Laravel core functions like `Str::of()` or `Cache::remember()` for testing?
- Patchwork can redefine any function or method, including Laravel core helpers, but this risks destabilizing assumptions in your application. Use cautiously—prefer container binding overrides or facade mocking for Laravel-specific logic. Always test thoroughly in staging before production.
- How do I install Patchwork in a Laravel project without breaking autoloading or OPcache?
- Add it as a dev dependency via `composer require antecedent/patchwork --dev`. To avoid conflicts with Laravel’s autoloader, register patches *after* the framework boots (e.g., in a `PatchworkServiceProvider` or `registerShutdownFunction`). Disable OPcache in test environments or use `opcache_reset()` if needed.
- Will Patchwork work with Laravel’s service container or facade mocking? Can I combine them?
- Patchwork operates at a lower level than Laravel’s container or facades, so it can complement them. For example, use Patchwork to mock static methods or global functions while keeping container-bound services intact. However, avoid patching the same method via both systems to prevent conflicts or unpredictable behavior.
- Does Patchwork support Laravel 10+ and PHP 8.2+? Are there known compatibility issues?
- Patchwork’s last release (2025) suggests PHP 8.1+ support, but Laravel 10+ (PHP 8.2+) may require validation due to stricter type systems or OPcache changes. Test patches in a clean Laravel 10 environment and monitor for autoloading or bootstrap conflicts, especially if using `bootstrap/app.php` hooks.
- How can I scope patches to test environments only (e.g., `.env` flags or CI checks)?
- Use environment checks (e.g., `if (app()->environment('testing'))`) to conditionally apply patches in your `setUp()` or `beforeEach()` methods. For CI, set a custom env var like `PATCHWORK_ENABLED=true` and guard patching logic with `if (getenv('PATCHWORK_ENABLED'))`. Avoid enabling patches in production.
- What’s the performance impact of Patchwork in production? Will OPcache or JIT compilers mitigate this?
- Patchwork’s runtime rewrites bypass OPcache optimizations, so expect measurable overhead in production. Disable OPcache in test environments or use `opcache.reset()` to avoid caching patched code. For PHP 8.2+, JIT may partially offset costs, but benchmark under realistic loads—especially for high-traffic endpoints.
- Can Patchwork be used to debug or temporarily modify production behavior (e.g., rate-limiting a legacy API)?
- Yes, but proceed with extreme caution. Patchwork is not designed for production use—runtime modifications can introduce subtle bugs or security risks. For debugging, use feature flags or Laravel’s container overrides instead. If you must patch in production, isolate changes to non-critical paths and roll back immediately.
- How do I handle static analysis warnings (e.g., Psalm/PHPStan) when using Patchwork?
- Static analyzers may flag patched methods as undefined or unused. Suppress warnings with `@phpstan-ignore-next-line` or custom Psalm rules. Document patched methods in your codebase and exclude test directories from strict analysis. Patchwork’s runtime nature makes static analysis inherently limited.
- Are there safer alternatives to Patchwork for Laravel testing, like Mockery or partial mocks?
- For most Laravel use cases, Mockery or PHPUnit’s partial mocks suffice. Patchwork shines only for legacy code with static methods, global functions, or third-party SDKs where DI is impractical. If your testing needs are container-centric, prioritize Laravel’s built-in tools—reserve Patchwork for edge cases.
- How do I document or track patched methods in a Laravel project? What’s the deprecation path if a patch becomes permanent?
- Document patches in a `PATCHWORK.md` file or PHPDoc blocks above patched methods, noting their purpose and scope. For permanent changes, refactor the original code and remove the patch. Use a `PATCHWORK_DEPRECATED` env var to warn developers when patches are no longer needed, then gradually phase them out.