Global State Laravel Package

Product Decisions This Supports

• Test Reliability & Isolation: Eliminates flaky tests caused by global state pollution (e.g., $_SESSION, $_SERVER, static variables) in PHP-based applications, critical for CI/CD pipelines and regression testing.
• Laravel-Specific Test Optimization: While Laravel’s built-in TestCase abstracts much of this, this package enables granular control for legacy codebases or custom test runners (e.g., PestPHP, custom CLI tools) where Laravel’s defaults fall short.
• Roadmap for Legacy Systems: Accelerates migration of monolithic PHP apps to Laravel by providing a drop-in solution for isolating tests in pre-existing codebases with heavy global state dependencies.
• Performance-Critical Testing: Reduces test execution time by selectively snapshotting only necessary state (e.g., $_ENV for config-heavy tests) instead of full process isolation (e.g., --process-isolation in PHPUnit).
• Security & Compliance: Ensures deterministic test environments for financial/healthcare applications where global state leaks could introduce vulnerabilities or compliance risks.

When to Consider This Package

Adopt when:

• Your tests modify or rely on global state (e.g., $_GET, $_SESSION, static variables, $GLOBALS) and exhibit flakiness.
• You’re using PHPUnit <10 or need fine-grained state control beyond PHPUnit’s built-in isolation (e.g., selective superglobal snapshots).
• Your Laravel tests interact with legacy code or third-party libraries that pollute global state (e.g., old plugins, non-Laravel dependencies).
• You require state snapshotting outside PHPUnit (e.g., in CLI scripts, Swoole workers, or custom test runners like PestPHP).
• Your PHP version is 8.0–8.2 (for v8.x) or 8.1–8.3 (for v7.x); avoid if targeting PHP 8.3+ (v9.x drops support).

Avoid when:

• Your tests already use Laravel’s TestCase with default isolation (no global state pollution).
• You’re using PHPUnit ≥10 with --process-isolation and don’t need selective state control.
• Your application avoids global state entirely (preferred architecture; use dependency injection instead).
• You’re on PHP 8.3+ and require v9.x (risk of compatibility issues).
• Your team lacks test discipline—reliance on global state snapshotting often signals poor test design (e.g., unmocked dependencies, side-effect-heavy code).

How to Pitch It (Stakeholders)

For Executives: "This package solves a critical but invisible problem: flaky tests. In PHP applications—especially those migrating to Laravel—global variables like $_SESSION or static caches can corrupt test environments, wasting engineering time on false failures. By snapshotting and restoring state between tests, we eliminate this noise, accelerating CI/CD cycles and reducing risk in releases. It’s a low-cost, high-impact fix for legacy systems or complex integrations where Laravel’s defaults aren’t enough. Think of it as ‘undo’ for your tests—guaranteeing consistency without rewriting code."

For Engineering/DevOps: *"Problem: Global state leaks between tests cause intermittent failures, slowing down development and CI. Solution: sebastian/global-state lets us capture and restore PHP’s superglobals, static properties, and INI settings with one line of code. Unlike PHPUnit’s process isolation (which is heavy), this gives us selective control—only snapshot what we need (e.g., $_ENV for config tests) and skip the rest. It’s battle-tested by PHPUnit itself and integrates seamlessly with Laravel’s testing stack. Trade-offs:

• Pros: Faster than process isolation, works outside PHPUnit, supports legacy code.
• Cons: Requires discipline to avoid overusing global state (long-term goal: refactor away from it). Ask: Should we adopt this for our [legacy system]/[specific test suite] to stabilize our test suite?"*

For Developers: *"Need to test code that touches $_SERVER, $_SESSION, or static variables? This package lets you snapshot the state before a test and restore it afterward, ensuring isolation without rewriting the code under test. Example:

// In your test’s setUp():
$this->snapshot = Snapshot::snapshot(['globals' => ['$_GET']]);

// Later, restore:
$this->snapshot->restore();

Why not just use --process-isolation? Because it’s slower and heavier—this gives you fine-grained control (e.g., skip snapshotting $_SESSION if you don’t need it). Gotchas:

• Only snapshots declared static properties (not dynamic ones).
• Avoid snapshotting $_SESSION/$_COOKIE unless you handle race conditions.
• PHP 8.3? Use v8.x (v9.x drops 8.3 support). Start small: Use it in one problematic test suite first, then expand."*