Global State Laravel Package

Getting Started

This package provides a GlobalStateSnapshot class to capture and restore PHP’s global state — including superglobals ($_GET, $_POST, etc.), $GLOBALS, static properties, and INI settings — which is essential for test isolation in PHPUnit or other test runners. Begin by installing it as a dev dependency:

composer require --dev sebastian/global-state

The primary use case is writing reliable, side-effect-free tests where mutable global state (e.g., database connections, cached values, global variables) must be reset between tests. The entry point is SebastianBergmann\GlobalState\Snapshot — instantiate it with Snapshot::snapshot() to capture the current state, and later call $snapshot->restore() to revert changes.

Implementation Patterns

• Test Setup/Teardown: Use Snapshot::snapshot() in setUp() or before critical assertions, then restore in tearDown() to enforce isolation.

  protected function setUp(): void
  {
      $this->snapshot = Snapshot::snapshot();
  }
  
  protected function tearDown(): void
  {
      $this->snapshot->restore();
  }
  

• Selective Restoration: For fine-grained control, pass arrays to Snapshot::snapshot() to specify only which state to snapshot/restore (e.g., Snapshot::snapshot(['globals' => ['$_GET', '$_POST']])). This avoids unnecessary overhead.
• Custom Static Property Support: Define classes whose static properties should be snapshotted via Snapshot::snapshot(['staticProperties' => ['App\MyClass::class']]).
• Integration with PHPUnit: While PHPUnit v10+ embeds this internally, explicitly using it in custom test bases (or legacy projects) gives more visibility and control. Also useful outside PHPUnit — e.g., in CLI scripts or long-running processes (like Swoole) needing state resets between requests.

Gotchas and Tips

• PHP Version Policy: Only support PHP 8.0–8.2 (v8.x) or 8.1–8.3 (v7.x) — v9 dropped PHP 8.3. Check version compatibility before upgrading PHP.
• Super-Global Behavior: $_SESSION and $_COOKIE are not snapshotted by default (due to side effects like session writes); use snapshotSuperGlobals() explicitly if needed, but be cautious — restoring session state can cause race conditions in concurrent tests.
• Performance Overhead: Snapshots capture everything by default; for speed, use selective arrays in snapshot() (e.g., ['globals' => ['$_ENV']]). Profile Snapshot::snapshot() — large $GLOBALS or complex objects can slow tests.
• Static Properties & Reflection: Only properties declared in the class are snapshotted — dynamic properties (e.g., $this->dynamic = 'value') may not behave as expected.
• PHPUnit Integration Caveat: If using PHPUnit ≥10, its built-in --process-isolation may suffice for simple cases; sebastian/global-state shines when you need fine-grained state control or non-PHPUnit test runners.
• Testing Tip: Always restore() in a try/finally if not using tearDown() to guarantee cleanup on early returns/failures:

  try {
      $snapshot = Snapshot::snapshot();
      // ... test logic
  } finally {
      $snapshot?->restore(); // safe even if $snapshot is null
  }