Download the PHP package me-shaon/laravel-resilience without Composer

Laravel Resilience

Laravel Resilience helps you verify how a Laravel app behaves when a real dependency becomes slow, times out, or fails.

Instead of replacing that dependency with a mock, it injects faults into the actual container-managed service or Laravel integration your code normally uses. That makes it useful for checking fallback behavior, degraded responses, retries, logs, jobs, and duplicate-side-effect protection in a more realistic way.

Why it is useful

Use this package when you want to:

• test failure handling against real Laravel wiring, not only mocks
• inject timeouts, exceptions, or latency into real dependency seams
• verify fallback behavior, degraded responses, logs, events, or jobs
• scan an existing codebase for areas that probably need resilience work
• scaffold draft resilience tests from actionable hotspots

In short:

• use mocks for fast unit-level feedback
• use Laravel Resilience for confidence that the real failure path works

Compatibility

• PHP 8.1+
• Laravel 10, 11, 12, and 13

Installation

Laravel package discovery registers the service provider and facade automatically.

If you want to customize the defaults:

Quick start

The easiest way to adopt the package is:

1. discover likely resilience-sensitive code
2. turn findings into suggestions
3. scaffold draft tests for the highest-value gaps
4. refine those drafts into real application-specific resilience tests

What each command does:

• resilience:discover finds likely resilience-sensitive code such as HTTP calls, queue dispatches, cache usage, storage writes, and direct client construction
• resilience:suggest turns findings into practical next actions such as adding a fallback test, extracting a dependency seam, or tightening duplicate-side-effect protection
• resilience:scaffold generates draft Pest tests for actionable hotspots and is safe to rerun

If you want the fuller walkthrough, CLI examples, report options, and longer explanations, read Usage Guide.

The HTML reports are useful when the CLI output gets too large:

A quick example

Application code:

Resilience test:

What this proves:

• the real application flow runs
• the real dependency seam is faulted
• your fallback path is exercised under failure
• the outcome is asserted in a readable way

Best fit

Laravel Resilience works best when your app already has clear dependency seams.

Best-supported patterns:

• dependencies resolved through Laravel container bindings
• contracts or interfaces for critical external services
• outbound integrations wrapped in service classes
• isolated side effects in jobs, actions, or dedicated services
• normal Laravel HTTP, mail, cache, queue, and storage entry points

Weakly supported patterns:

• direct new SomeSdkClient() calls inside controllers or jobs
• static third-party SDK calls with no container seam
• business logic and IO tightly coupled in the same class

Those areas can still be discovered and suggested, but they usually need some refactoring before fault injection becomes truly effective.

Main capabilities

Fault injection

You can fault container-managed services directly:

Supported fluent fault types for direct runtime injection:

• timeout()
• exception(Throwable $exception)
• latency(int $milliseconds)

Laravel-aware helpers are also available:

Named targets are supported too:

Assertions

The package includes readable assertions for common resilience outcomes:

• assertFallbackUsed()
• assertLogWritten()
• assertEventDispatched()
• assertJobDispatched()
• assertNoDuplicateSideEffects()
• assertDegradedButSuccessful()

Scenario runner

Scenarios let you define a named resilience drill and run it from Artisan:

Discovery, suggestions, and scaffolding

These commands help teams adopt resilience testing incrementally:

• resilience:discover finds likely resilience-sensitive code
• resilience:suggest prioritizes actionable follow-up work
• resilience:scaffold generates draft Pest tests under tests/Resilience/Generated

Scaffold behavior:

• writes a manifest to build/resilience-scaffold.json
• skips existing generated files in normal create mode
• avoids overwriting customized generated files in update mode
• only overwrites generated files when you explicitly use --mode=force

Safety defaults

Laravel Resilience is intentionally conservative:

• runtime activation is blocked in production by default
• scenario execution is only treated as safe by default in local and testing
• non-local scenario execution requires both RESILIENCE_ALLOW_NON_LOCAL_SCENARIOS=true and --confirm-non-local
• --dry-run lets you inspect a scenario without activating faults

Command reference

Further reading

If you want the deeper internals and longer examples, use the guides instead of growing the README:

• Usage Guide
• How Laravel Resilience Works
• Example: Well-Structured App
• Example: Messy Legacy App

Development

License

MIT. See LICENSE.md.