Garbage Collection

Also Known As

TL;DR

Explanation

PHP's primary GC is reference counting: each value tracks how many variables point to it; when the count reaches 0, the value is freed immediately. Problem: circular references (A → B → A) never reach 0. PHP's cycle collector (since 5.3) detects and frees circular reference groups. In PHP 8, the GC is more efficient. Long-running processes (queue workers, PHP-FPM long-lived workers) accumulate memory through leaks or slow GC; calling gc_collect_cycles() manually in batch jobs can reduce memory usage.

Diagram

flowchart TD
    subgraph Reference Counting
        OBJ[Object<br/>refcount=1] -->|assign to 2nd var| RC2[refcount=2]
        RC2 -->|unset 1st var| RC1[refcount=1]
        RC1 -->|unset all| RC0[refcount=0<br/>free immediately]
    end
    subgraph Cycle Collector
        A[Object A<br/>points to B] -->|circular ref| B[Object B<br/>points to A]
        B --> A
        RC0B[Neither reaches 0<br/>both stranded]
        CYCLE[Cycle Collector<br/>runs periodically] -->|detects cycle| FREE[Frees both]
    end
    style RC0 fill:#238636,color:#fff
    style FREE fill:#238636,color:#fff

Watch Out

Common Misconception

Why It Matters

Common Mistakes

• Not unsetting large arrays and objects after use in loops — reference count stays > 0 until scope ends.
• Circular references in event listeners — object A registers a listener on object B; both hold references to each other.
• Not calling gc_collect_cycles() in very long batch jobs — cycle collector runs automatically but not immediately.
• PHP generators as memory optimisation — they yield one item at a time, but the generator object itself stays in memory.

Avoid When

• Do not disable gc_disable() in long-running workers without a manual gc_collect_cycles() strategy — circular references accumulate silently until OOM.
• Avoid creating large object graphs with circular parent/child references when a simple array or flat structure would suffice.

When To Use

• Call gc_collect_cycles() explicitly after processing large batches of objects in long-running scripts to reclaim memory from circular references immediately.
• Use WeakReference for cache or observer registrations where the GC should be free to collect the target without the reference preventing it.

Code Examples

// Circular reference — not immediately freed:
class Node {
    public ?Node $parent = null;
    public array $children = [];
}
$root = new Node();
$child = new Node();
$root->children[] = $child;
$child->parent = $root; // Circular: root → child → root
unset($root, $child); // Reference count > 0 — not freed immediately
// Freed later by cycle collector — or manually: gc_collect_cycles()

// Break circular references explicitly:
function processTree(Node $root): void {
    foreach ($root->children as $child) processTree($child);
    // Break circular refs before returning:
    foreach ($root->children as $child) $child->parent = null;
    $root->children = [];
}
// Or use WeakReference for parent pointers — does not prevent GC
class Node {
    public ?WeakReference $parent = null; // Weak — GC can collect parent
}

Tags

🧠 Logic Engine

References

• https://www.php.net/manual/en/features.gc.php
• https://www.php.net/manual/en/class.weakreference.php
• https://www.php.net/manual/en/function.gc-collect-cycles.php