Include Interceptor Laravel Package

Getting Started

Install via Composer: composer require nikic/include-interceptor. Start by wrapping your entrypoint with the interceptor to capture all include/require calls:

use IceWind\Interceptor\IncludeInterceptor;

$interceptor = new IncludeInterceptor();
$interceptor->install();

// Your application or test bootstrapping logic here
require 'app.php';

$interceptor->uninstall();

In tests or CLI tools, you might use it to log or alter included paths for analysis:

$interceptor->onInclude(function ($type, $path, $resolvedPath) {
    error_log("Included {$type}: {$path} → {$resolvedPath}");
    return $resolvedPath; // return modified path or original to proceed
});

Implementation Patterns

• Coverage/Profiling Tools: Wrap the target script and collect a list of all included files for static analysis or coverage reporting (e.g., like PHPUnit’s coverage, but at include level).
• Custom Autoloading Fallbacks: Implement fallback resolution logic for non-Composer environments (e.g., legacy apps where autoloading isn’t available). Intercept missing files and map to custom paths.
• Sandboxing & Security: In eval-like execution contexts (e.g., plugin systems), intercept require calls to block access to sensitive paths (e.g., /etc/passwd) by returning false or throwing exceptions.
• Testing Helpers: Mock or override included files during unit tests—e.g., replace config.php with a test fixture by resolving to a different path in the callback.
• Dynamic Relocation: Run applications in phar or embedded environments where original paths differ; intercept and remap includes to match the new runtime layout.

Best practice: Keep callbacks fast and idempotent. Avoid heavy I/O or recursion (e.g., do not include inside the callback unless deliberate).

Gotchas and Tips

• Only intercepts include/require, not fopen or direct file reads: It won’t catch file_get_contents('config.php'), only explicit PHP include constructs.
• Order matters: Call install() before any file is included. If you include a file before installing, it’ll bypass the interceptor entirely.
• Uninstall when done: Calling uninstall() restores PHP’s default behavior. Skipping this may cause issues in long-running processes (e.g., ReactPHP, Swoole).
• Callback returns: Returning false from the callback skips the include entirely. Returning a string replaces the path. Omitting return defaults to using the resolved path.
• Thread safety: Not safe in multi-threaded SAPIs (e.g., IIS with Thread Safety). Works reliably in CLI and Apache mod_php (prefork MPM).
• Extension: Combine with autoloading: Pair with spl_autoload_register() for full coverage: use autoloading for classes, include-interceptor for procedural includes.
• Debug tip: Log include depth in callback (static $depth = 0; $depth++), and decrement on __FILE__-based checks to trace recursive includes.
• Last resort, but powerful: Avoid in production unless absolutely necessary—use only where reflection, testing, or modularization otherwise falls short (e.g., instrumenting unmodifiable legacy code).