Weave Code
Include Interceptor Laravel Package
infection/include-interceptor
PHP stream wrapper that intercepts the file:// protocol to override the content of any included or autoloaded file at runtime. Register a mapping from original file to replacement, enable the interceptor, and includes/file_get_contents load the replacement instead.
Stream Wrapper: Include Interceptor. Allows to replace included (autoloaded) file with another one.
Frequently asked questions about Include Interceptor
- Can I use Infection/Include-Interceptor in Laravel for mutation testing with Infection?
- Yes, this package is specifically designed for Infection’s mutation testing needs. It replaces original files with mutants during test execution, allowing you to test how your code handles edge cases. Just install it as a dev dependency and register it in your test bootstrap file.
- How do I install Include-Interceptor in a Laravel project?
- Run `composer require --dev infection/include-interceptor:0.2.5` to install it as a development dependency. The `--dev` flag ensures it’s only included in test environments, avoiding production conflicts.
- Will this package interfere with Laravel’s filesystem or cached views?
- No, the stream wrapper only targets the `file://` protocol for included files, so it won’t affect Laravel’s filesystem drivers (local, S3) or compiled views in `bootstrap/cache`. It operates at a lower level than Laravel’s filesystem abstractions.
- How do I register the interceptor in Laravel’s test environment?
- Add the interceptor to your `phpunit.xml` under `<php><includePath>./vendor/infection/include-interceptor/bootstrap.php</includePath></php>` or register it manually in `tests/bootstrap.php` with `if (app()->environment('testing')) { IncludeInterceptor::enable(); }`.
- Does this work with Laravel’s Artisan commands or HTTP tests?
- Yes, but ensure the interceptor is enabled *before* any includes or `file_get_contents` calls are made. For HTTP tests, register it in your test setup, but avoid conflicts with `Http::fake()` by testing inclusion logic separately.
- Is Include-Interceptor compatible with Pest or PHPUnit parallel testing?
- The 0.2.5 release includes a lock constant fix to reduce race conditions, making it safer for parallel test execution. However, high-concurrency CI environments may still experience minor latency due to file locking.
- Can I use this to mock `final` classes in Laravel like `dg/bypass-finals` does?
- Yes, the same technique used in `dg/bypass-finals` applies here. You can intercept and modify the content of `final` classes at runtime, effectively bypassing their restrictions during testing.
- What’s the performance impact of using this in a large Laravel test suite?
- The overhead is minimal for typical use cases, but in suites with 100+ test files, you may notice slight delays due to stream wrapper registration and file locking. Benchmark in your CI to assess real-world impact.
- Are there alternatives to Include-Interceptor for Laravel mutation testing?
- For mutation testing, Infection itself is the primary alternative, but it relies on this interceptor under the hood. Other alternatives include custom stream wrappers or Xdebug-based solutions, though they lack Infection’s integration depth.
- How often is this package maintained, and is it safe for long-term use?
- The package saw a major update in 2026 (0.2.5), addressing critical race conditions. While maintenance is responsive, its niche focus means it’s best suited for test environments. Monitor the GitHub repo for updates, especially if using Laravel 9+.
Weaver
How can I help you explore Laravel packages today?