Global State Laravel Package

Product Decisions This Supports

• Test Reliability for Legacy Systems: Justifies adoption for Laravel projects with legacy codebases heavily reliant on global state (e.g., $_SESSION, $_SERVER) or third-party libraries that pollute globals, where flaky tests block CI/CD pipelines.
• Migration from Custom Solutions: Enables replacement of ad-hoc global state management (e.g., manual $_GET resets, register_shutdown_function hacks) with a maintainable, community-backed solution, reducing technical debt.
• Multi-Tenant or Stateful Testing: Critical for products with complex state transitions (e.g., SaaS platforms, workflow engines) where test isolation requires snapshotting beyond PHPUnit’s defaults (e.g., static caches, singleton services).
• Performance-Critical Test Suites: Supports roadmap goals for parallel test execution by enabling fine-grained state restoration (e.g., snapshotting only $_ENV instead of all superglobals), reducing contention in CI environments.
• Compliance/Regulatory Testing: Validates for industries requiring deterministic test outputs (e.g., fintech, healthcare) where global state pollution could mask critical bugs in production-like environments.

When to Consider This Package

Adopt when:

• Your Laravel tests modify superglobals ($_GET, $_POST, $_SERVER, $_ENV) or static properties in a way that causes test pollution (e.g., TestCase A breaks TestCase B).
• You’re maintaining legacy PHP code (pre-PHPUnit 10) or using non-PHPUnit test runners (e.g., Pest, custom scripts) where built-in isolation is insufficient.
• Your team lacks discipline for dependency injection (e.g., relying on $_SESSION for stateful services) and needs a "safety net" for global state.
• You require selective snapshotting (e.g., only $_ENV or specific static classes) to optimize test performance in large suites.
• Your PHP version is 8.0–8.2 (for v8.x) or 8.1–8.3 (for v7.x); avoid if using PHP 8.3+ with v9.x (dropped support).

Avoid when:

• Your codebase follows Laravel best practices (dependency injection, service container mocking) with minimal global state usage—PHPUnit’s built-in isolation (--process-isolation) suffices.
• You’re using PHPUnit ≥10 with default test isolation; explicit sebastian/global-state adds unnecessary complexity.
• Your tests intentionally share state (e.g., integration tests with database transactions) where snapshotting would mask expected side effects.
• You need real-time global state (e.g., $_SERVER['REQUEST_TIME']) that shouldn’t be restored to past values.
• Your team lacks test ownership culture—this package won’t fix poor test design (e.g., testing private methods, unmocked globals).

How to Pitch It (Stakeholders)

For Executives: *"This package solves a hidden bottleneck in our test suite: global state pollution is causing flaky tests, slowing down releases, and increasing debugging costs. By adopting sebastian/global-state, we can:

• Eliminate test failures caused by shared global variables (e.g., $_SESSION, $_ENV) between test cases.
• Reduce CI costs by enabling parallel test execution with fine-grained state isolation.
• Future-proof our tests for legacy systems while maintaining compliance with strict testing standards (e.g., fintech, healthcare). The upfront cost is minimal—a Composer dependency and minor test refactoring—with ROI in fewer blocked merges and faster feedback loops."*

For Engineering Leaders: *"This is a low-risk, high-reward tool for teams struggling with:

1. Flaky tests from global state leaks (e.g., $_GET modified by one test breaking another).
2. Legacy code that can’t be easily refactored to avoid globals.
3. Performance bottlenecks in large test suites due to full process isolation.

Key benefits:

• Drop-in replacement for custom global state hacks (e.g., unset($_SESSION) in tearDown()).
• Selective snapshotting to optimize test speed (e.g., snapshot only $_ENV instead of all superglobals).
• Works outside PHPUnit (e.g., Pest, custom scripts) where isolation is needed.
• Backed by PHPUnit’s core team—battle-tested in PHP’s testing ecosystem.

Trade-offs:

• Requires PHP 8.0–8.3 (check compatibility with our stack).
• Not a silver bullet—won’t fix poorly designed tests (e.g., testing private methods via globals). Recommendation: Pilot with the most flaky test files first to measure impact."*

For Developers: *"If you’ve ever seen a test pass locally but fail in CI because $_SESSION or $_SERVER was left dirty, this package is for you. It lets you:

• Snapshot and restore any global state (superglobals, statics, INI settings) with one line:

  $snapshot = Snapshot::snapshot(['globals' => ['$_GET', '$_POST']]);
  // ... test logic ...
  $snapshot->restore(); // boom, clean slate.
  

• Avoid boilerplate like manually resetting $_ENV or clearing static caches.
• Use it selectively—only snapshot what you need to speed up tests.

Gotchas:

• PHP 8.3? v9.x drops support—stick to v8.x if using PHP 8.3.
• $_SESSION? Be careful—restoring it can cause race conditions in concurrent tests.
• Performance: Snapshotting everything is slow; use arrays to limit scope (e.g., ['globals' => ['$_ENV']]).

Start here:

composer require --dev sebastian/global-state

Then wrap your test logic in snapshots. Works with PHPUnit, Pest, or raw scripts."*