Capturing variables by reference in PHP closures allows the closure to modify external variables from the parent scope, achieved using the & symbol in the use clause; 2. This enables mutable state within closures, making them suitable for counters, accumulators, shared context in callbacks, and pipeline stages; 3. A common pitfall is unintended side effects when multiple closures share the same referenced variable; 4. Loop-related issues occur when closures capture loop variables by reference, causing all closures to reflect the final value, which can be fixed by using value capture or isolating the variable per iteration; 5. Best practice is to use reference capture only when necessary, preferring value capture for safer and more predictable code.

When working with closures in PHP, one of the more subtle but powerful features is capturing variables by reference. This allows closures to not just read, but actually modify external variables from their defining scope — even after that scope has otherwise finished executing. This capability unlocks mutable state in closures, making them far more flexible than simple anonymous functions.

Let’s break down how this works and why it matters.

What Is Variable Capture in PHP Closures?

In PHP, when you define a closure (an anonymous function), it can "capture" variables from the parent scope using the use keyword.

By default, these variables are captured by value, meaning the closure gets a copy:

$counter = 0;
$increment = function () use ($counter) {
    $counter  ;
};

$increment();
echo $counter; // Still 0 — the closure modified its own copy

But if you want the closure to actually affect the original variable, you need to capture it by reference, using the & symbol:

$counter = 0;
$increment = function () use (&$counter) {
    $counter  ;
};

$increment();
echo $counter; // Now outputs 1 — the original was modified

This small change makes a big difference: the closure now shares access to the same variable, not a copy.

Why Mutating Captured State Matters

Capturing by reference enables closures to maintain and modify mutable state, which is essential for patterns like:

• Counters and accumulators
• Callbacks that need to track progress
• Event handlers with shared context
• Deferred computations that depend on changing data

For example, imagine processing a list of items and wanting to log how many succeeded:

$successCount = 0;
$errorLog = [];

$processItem = function ($item) use (&$successCount, &$errorLog) {
    if (rand(0, 1)) {
        $successCount  ;
    } else {
        $errorLog[] = "Failed processing {$item}";
    }
};

array_map($processItem, ['A', 'B', 'C', 'D']);
echo "Successes: $successCount\n"; // e.g., Successes: 2
print_r($errorLog);

Without references, $successCount and $errorLog would remain unchanged outside the closure.

Common Pitfalls and Best Practices

While powerful, capturing by reference can make code harder to reason about if overused. Here are a few things to watch out for:

• Unintended side effects: If multiple closures share a reference, changing it in one affects all.

  $value = 10;
  $add5 = function () use (&$value) { $value  = 5; };
  $subtract3 = function () use (&$value) { $value -= 3; };
  
  $add5();
  $subtract3();
  echo $value; // 12

• Timing issues: The closure sees the current value of the variable when it runs, not when it was defined. This is especially important in loops.

  ?? This common mistake doesn't work as expected:

  $functions = [];
  for ($i = 0; $i < 3; $i  ) {
      $functions[] = function () use (&$i) { echo $i . "\n"; };
  }
  // All closures output 3, because $i is 3 after the loop

  ? Fix: bind each value separately:

  for ($i = 0; $i < 3; $i  ) {
      $functions[] = function () use ($i) { echo $i . "\n"; }; // by value
  }

  Or, if you need reference behavior per iteration, copy into a local:

  for ($i = 0; $i < 3; $i  ) {
      $index = $i;
      $functions[] = function () use (&$index) { echo $index . "\n"; };
  }

Real-World Use Case: Middleware or Pipeline Stages

A practical example is building a pipeline where each stage modifies a shared context:

$context = ['data' => 'start', 'processed' => false];

$stages = [
    function () use (&$context) {
        $context['data'] .= ' -> validated';
    },
    function () use (&$context) {
        $context['processed'] = true;
        $context['data'] .= ' -> transformed';
    },
    function () use (&$context) {
        $context['data'] .= ' -> logged';
    }
];

foreach ($stages as $stage) {
    $stage();
}

print_r($context);
// Output:
// Array
// (
//     [data] => start -> validated -> transformed -> logged
//     [processed] => 1
// )

This pattern is common in frameworks, testing utilities, or configuration builders.

Capturing by reference in PHP closures isn’t just a syntax trick — it’s a way to create stateful, cooperative functions that can evolve shared data over time. Used wisely, it makes closures a powerful tool for encapsulating logic that needs to remember or influence its environment.

Just remember: with great power comes great responsibility. Always ask: Does this closure really need to mutate the outer variable? If not, stick to value capture for safer, more predictable code.

Basically, it's not complex — but it's easy to misuse.

The above is the detailed content of Capturing by Reference: Unlocking Mutable State in PHP Closures. For more information, please follow other related articles on the PHP Chinese website!