Bypass Finals Laravel Package

Getting Started

1. Install via Composer: composer require --dev dg/bypass-finals
2. In your test bootstrap file (e.g., tests/bootstrap.php), add:

   require_once __DIR__ . '/../vendor/autoload.php';
   (new \BypassFinals\Loader)->register();
   

3. First use case: Write a test that mocks a final class — e.g., a framework service like Symfony\Component\HttpFoundation\Request (if declared final) or a vendor utility class — just as you would any regular class:

   $mock = $this->createMock(FinalClass::class);
   

Implementation Patterns

• Bootstrap early: Register BypassFinals\Loader before class autoloading begins (ideally in phpunit.xml’s bootstrap attribute or at top of tests/bootstrap.php).
• Selective coverage: Only run tests with bypass enabled in CI/test environments; never in production (e.g., wrap in if (PHP_SAPI === 'cli') or CI-specific flag).
• Mixed mocking tools: Use alongside PHPUnit, Mockery, or Pest — e.g., with Mockery:

  $mock = mock(FinalClass::class . '@mock')->makePartial();
  

• Integration with code coverage: Bypassed code remains testable in coverage reports (verify via Xdebug/PCOV + bypass-finals doesn’t interfere with coverage collection).

Gotchas and Tips

• Runtime overhead: Parsing and rewriting bytecode adds minimal overhead — acceptable in tests/CI but avoid in production.
• Memory limits: Heavy use with large codebases may increase memory usage (set memory_limit = -1 for CI if needed).
• Extensions compatibility: Conflicts possible with opcache or JIT; disable opcache in test environment (opcache.enable=0) to avoid stale bytecode.
• Final methods only: While final classes and methods are supported, property readonly is only bypassed in PHP 8.1+; earlier versions ignore readonly entirely.
• Debugging: If mocks fail unexpectedly, verify Loader::register() ran before the class was loaded — add debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2) in __construct to trace load order.
• Extension point: You can customize rewriter behavior by extending BypassFinals\Rewriter, though the package’s internal API is unstable (no BC guarantees).