Log Fake Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package (timacdonald/log-fake) is a drop-in fake logger designed specifically for Laravel testing, replacing the default Monolog or Psr\Log\LoggerInterface implementations with a mockable, assertion-friendly logger (e.g., Log::shouldReceive('error')->once()).

  • Fit: Ideal for unit/integration tests where logging side effects (e.g., file I/O, external services) must be isolated. Poor fit for production (no real logging functionality).
  • Laravel Ecosystem: Leverages Laravel’s service container and logging facade (Log::), ensuring minimal boilerplate.

• Key Features:

  • PSR-3 Compliance: Implements Psr\Log\LoggerInterface, ensuring compatibility with Laravel’s logging stack.
  • Assertion Methods: Provides shouldReceive(), assertLogged(), etc., for PHPUnit/Pest assertions (e.g., verifying log calls).
  • Context Support: Captures log context (e.g., ['user_id' => 123]) for precise assertions.
  • Level Filtering: Allows mocking specific log levels (e.g., debug, error) independently.

Integration Feasibility

• Minimal Setup: Replace Laravel’s default logger in config/logging.php with the fake logger only in test environments (e.g., via phpunit.xml or Pest.php).

  // config/logging.php (test environment)
  'default' => env('LOG_CHANNEL', 'fake'),
  'fake' => [
      'driver' => 'fake',
      'via' => \TimacDonald\LogFake\FakeLogger::class,
  ],
  

• Dependency: Requires PHPUnit/Pest for assertions. No runtime overhead in production.

Technical Risk

• False Positives/Negatives:
  • Risk of missed log assertions if tests don’t verify all expected log calls (e.g., forgetting to assert Log::assertLogged('error')).
  • Solution: Enforce assertion checks in test suites (e.g., custom PHPUnit traits).
• Edge Cases:
  • Context Mismatches: Assertions fail if log context differs slightly (e.g., ['user_id' => 123] vs. ['user_id' => '123']).
  • Solution: Use assertLoggedWithContext() with flexible matchers.
• Laravel Version Compatibility:
  • Last release (2026) suggests active maintenance, but backward compatibility should be verified for older Laravel versions (e.g., <9.x).
  • Mitigation: Test with your Laravel version’s Psr\Log implementation.

Key Questions

1. Testing Strategy:
   • Will this replace existing log verification (e.g., file-based checks) or supplement it?
   • How will log levels (e.g., debug vs. error) be prioritized in assertions?
2. Performance:
   • Will fake logging slow down tests due to assertion overhead? (Benchmark with/without.)
3. CI/CD Impact:
   • How will flaky assertions (e.g., context mismatches) be handled in CI?
4. Alternatives:
   • Compare with Mockery or Laravel’s built-in testing helpers (e.g., expectsJob() for queues).
   • Is this worth the abstraction over simpler Log::spy() patterns?

Integration Approach

Stack Fit

• Laravel Testing Stack:
  • PHPUnit/Pest: Native support for assertions (e.g., assertLogged()).
  • Service Container: Fake logger can be bound conditionally (e.g., only in tests).
  • Monolog: Can coexist if fake logger wraps Monolog (though this package is standalone).
• Non-Laravel PHP:
  • Limited Fit: Designed for Laravel’s Log facade; requires manual PSR-3 mocking elsewhere.

Migration Path

1. Phase 1: Pilot in Unit Tests
   • Replace Log::info() checks with Log::shouldReceive('info')->once() in a single test file.
   • Verify assertions pass and no false negatives occur.
2. Phase 2: CI Validation
   • Run tests in CI to catch assertion flakiness (e.g., context mismatches).
   • Add pre-commit hooks to enforce assertion coverage.
3. Phase 3: Full Adoption
   • Update phpunit.xml/Pest.php to use the fake logger by default:

     <!-- phpunit.xml -->
     <env name="LOG_CHANNEL" value="fake"/>
     

   • Deprecate old log verification patterns (e.g., file checks).

Compatibility

• Laravel Versions:
  • Tested with Laravel 9+ (per 2026 release). For older versions, check composer.json constraints.
• Logging Drivers:
  • Works alongside other drivers (e.g., single, stack) if fake logger is the default.
  • Conflict Risk: If fake logger is not the default, logs may still hit real drivers (e.g., files).
• Third-Party Packages:
  • Packages using Log:: (e.g., spatie/laravel-logging) will transparently use the fake logger in tests.

Sequencing

1. Setup:
   • Install via Composer:

     composer require --dev timacdonald/log-fake
     

   • Publish config (if needed) or override config/logging.php.
2. Test Migration:
   • Start with critical test files (e.g., payment processing, error handling).
   • Gradually replace log assertions.
3. Monitor:
   • Track test runtime for regression (fake logger adds minimal overhead).
   • Watch for CI failures due to context mismatches.

Operational Impact

Maintenance

• Pros:
  • No Production Impact: Fake logger is test-only; zero runtime cost.
  • MIT License: No vendor lock-in.
• Cons:
  • Test-Specific Logic: Assertions may need updates if log formats change (e.g., new context keys).
  • Documentation: Requires team training on assertion patterns (e.g., assertLoggedWithContext()).

Support

• Debugging:
  • Easier: Fake logger provides clear assertion failures (e.g., "Expected 1 error log, got 0").
  • Harder: Debugging false negatives (e.g., missed assertions) requires test coverage tools (e.g., phpunit --coverage).
• Onboarding:
  • Low Barrier: Simple shouldReceive() syntax.
  • High Barrier: Context assertions require precise knowledge of log formats.

Scaling

• Test Suite Growth:
  • Pro: Reduces I/O overhead (no file/database logging in tests).
  • Con: Assertion complexity grows with log volume (e.g., 50 assertions for a complex flow).
• Parallel Testing:
  • Safe: Fake logger is stateless per test; no race conditions.
• Performance:
  • Negligible Overhead: Assertions are resolved at test teardown.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1 Hour: Learn shouldReceive() and assertLogged() basics.
  • 1 Day: Master context assertions and edge cases (e.g., nested contexts).
• Team Adoption:
  • Pilot Group: Start with 2–3 developers to document patterns.
  • Pair Programming: Review PRs to ensure consistent assertion styles.
• Tools:
  • PHPStorm/Pest: IDE support for Log:: assertions.
  • Mutation Testing: Use tools like infection to verify assertion robustness.