PHP Memory Management Explained: Internals, Leaks & Optimization

<?php
declare(strict_types=1);

/**
 * Demonstrates how PHP handles zval internals through observable behaviour.
 * We can't inspect raw zvals from userland, but xdebug_debug_zval() exposes
 * the refcount and is_ref flag — the two most important zval properties.
 *
 * Run with: php -d extension=xdebug.so ZvalInspection.php
 * (xdebug must be installed; the output below is what you'll see)
 */

// --- Integer: no heap allocation in PHP 7+ ---
$temperature = 42;
// Integers fit inside the zval union directly — no malloc, refcount=1 logically
echo "=== Integer (stack value) ===\n";
xdebug_debug_zval('temperature');  // refcount=1, is_ref=false

// --- String: heap-allocated, refcount starts at 1 ---
$cityName = 'London';
echo "\n=== String after first assignment ===\n";
xdebug_debug_zval('cityName');     // refcount=1, is_ref=false

// --- Copy-on-Write: assigning to a new variable does NOT copy the string yet ---
$copiedCity = $cityName;
echo "\n=== After $copiedCity = $cityName (CoW — same string, refcount bumped) ===\n";
xdebug_debug_zval('cityName');     // refcount=2, is_ref=false — SHARED, not copied!

// --- Mutation triggers the actual copy ---
$copiedCity = strtoupper($copiedCity); // 'LONDON' — a new string is created here
echo "\n=== After mutating copiedCity (CoW copy triggered) ===\n";
xdebug_debug_zval('cityName');     // refcount=1, is_ref=false — back to exclusive
xdebug_debug_zval('copiedCity');   // refcount=1, is_ref=false — new string

// --- Reference (&): forces is_ref=true, bypasses CoW ---
$originalScore = 100;
$scoreAlias = &$originalScore;    // now BOTH point to a zend_reference wrapper
echo "\n=== After creating a reference ===\n";
xdebug_debug_zval('originalScore'); // refcount=2, is_ref=true

echo "\noriginalScore: $originalScore, scoreAlias: $scoreAlias\n";
$scoreAlias += 50;                 // modifies the shared reference — no copy!
echo "After modifying alias — originalScore: $originalScore\n"; // 150

<?php
declare(strict_types=1);

/**
 * Demonstrates Copy-on-Write (CoW) memory behaviour with a large dataset.
 * Shows how PHP avoids copying until it absolutely must, and what breaks CoW.
 */

function getMemoryUsageMB(): float
{
    return round(memory_get_usage(true) / 1024 / 1024, 2);
}

// --- Build a large array (simulates loading records from DB) ---
$productCatalogue = [];
for ($i = 0; $i < 100_000; $i++) {
    $productCatalogue[] = [
        'id'    => $i,
        'name'  => 'Product ' . $i,
        'price' => mt_rand(100, 9999) / 100,
    ];
}

$beforeCopy = getMemoryUsageMB();
echo "Memory after building catalogue: {$beforeCopy} MB\n";

// --- CoW: assigning to a new variable does NOT duplicate the array in memory ---
$catalogueSnapshot = $productCatalogue;  // refcount bumped to 2 — no malloc
$afterCoWAssign = getMemoryUsageMB();
echo "Memory after CoW assign (expect near zero increase): {$afterCoWAssign} MB\n";
echo "Increase: " . ($afterCoWAssign - $beforeCopy) . " MB\n";

// --- Triggering a real copy: mutating the snapshot separates the two arrays ---
$catalogueSnapshot[0]['price'] = 0.01;  // 'SALE!' — this forces the full array copy
$afterMutation = getMemoryUsageMB();
echo "\nMemory after mutating snapshot (full copy created): {$afterMutation} MB\n";
echo "Increase: " . ($afterMutation - $beforeCopy) . " MB\n";

// --- Passing to a read-only function: still uses CoW, no copy ---
function countExpensiveProducts(array $catalogue, float $threshold): int
{
    // We only READ the array — CoW means no copy happened when $catalogue was received
    return count(array_filter(
        $catalogue,
        fn(array $product): bool => $product['price'] > $threshold
    ));
}

$expensiveCount = countExpensiveProducts($productCatalogue, 50.00);
$afterReadOnlyCall = getMemoryUsageMB();
echo "\nExpensive products over $50: {$expensiveCount}\n";
echo "Memory after read-only function call: {$afterReadOnlyCall} MB (CoW — no spike)\n";

// --- Danger: unintentionally breaking CoW with & in foreach ---
echo "\n--- CoW-breaking pattern: foreach with reference ---\n";
$beforeRef = getMemoryUsageMB();
foreach ($productCatalogue as &$product) {  // & forces a write-separation for every element!
    // Even if we never mutate $product, this still breaks CoW on the iterated array
    // because PHP can't know in advance whether we will write.
}
unset($product); // ALWAYS unset the dangling reference after a reference-foreach!
$afterRef = getMemoryUsageMB();
echo "Memory with reference foreach: {$afterRef} MB\n";
echo "Lesson: avoid foreach-by-reference unless you genuinely need to mutate in place.\n";

<?php
declare(strict_types=1);

/**
 * Demonstrates circular reference memory leaks and how PHP's cyclic
 * garbage collector rescues us — plus the WeakReference escape hatch.
 */

function getMemoryKB(): int
{
    return (int)(memory_get_usage() / 1024);
}

// --- 1. THE LEAK: two objects referencing each other ---
class OrderItem
{
    public string $productName;
    public ?Order $parentOrder = null; // back-reference — the cycle-forming link

    public function __construct(string $productName)
    {
        $this->productName = $productName;
    }
}

class Order
{
    public int $orderId;
    /** @var OrderItem[] */
    public array $items = [];

    public function __construct(int $orderId)
    {
        $this->orderId = $orderId;
    }

    public function addItem(OrderItem $item): void
    {
        $item->parentOrder = $this;  // CYCLE: $item -> $order -> $items[n] -> $item
        $this->items[] = $item;
    }
}

// Disable GC so we can see the raw leak in isolation
gc_disable();

$memBefore = getMemoryKB();

for ($iteration = 0; $iteration < 5_000; $iteration++) {
    $order = new Order($iteration);
    $order->addItem(new OrderItem('Widget A'));
    $order->addItem(new OrderItem('Widget B'));
    // $order goes out of scope here — but because of the cycle,
    // refcounts never reach 0, so NOTHING is freed.
    unset($order);
}

$memAfterLeak = getMemoryKB();
echo "=== Cyclic Leak (GC disabled) ===\n";
echo "Memory before loop: {$memBefore} KB\n";
echo "Memory after 5000 leaked cycles: {$memAfterLeak} KB\n";
echo "Leaked: " . ($memAfterLeak - $memBefore) . " KB\n";

// --- 2. THE RESCUE: run the cyclic garbage collector manually ---
$cyclesCollected = gc_collect_cycles(); // walks root buffer, frees unreachable cycles
$memAfterGC = getMemoryKB();
echo "\nCycles collected: {$cyclesCollected}\n";
echo "Memory after gc_collect_cycles(): {$memAfterGC} KB\n";
echo "Freed by GC: " . ($memAfterLeak - $memAfterGC) . " KB\n";

gc_enable(); // restore normal operation

// --- 3. THE BETTER FIX: WeakReference breaks the cycle structurally ---
class OrderV2
{
    public int $orderId;
    /** @var OrderItemV2[] */
    public array $items = [];

    public function __construct(int $orderId)
    {
        $this->orderId = $orderId;
    }

    public function addItem(OrderItemV2 $item): void
    {
        // WeakReference does NOT increment the refcount of the Order object
        // so the cycle is broken — when external refs drop, Order is freed immediately
        $item->parentOrderRef = WeakReference::create($this);
        $this->items[] = $item;
    }
}

class OrderItemV2
{
    public string $productName;
    public ?WeakReference $parentOrderRef = null; // does NOT hold a strong ref

    public function __construct(string $productName)
    {
        $this->productName = $productName;
    }

    public function getParentOrderId(): ?int
    {
        $parentOrder = $this->parentOrderRef?->get(); // returns null if Order was GC'd
        return $parentOrder?->orderId;
    }
}

$memBeforeV2 = getMemoryKB();
for ($iteration = 0; $iteration < 5_000; $iteration++) {
    $order = new OrderV2($iteration);
    $order->addItem(new OrderItemV2('Widget A'));
    $order->addItem(new OrderItemV2('Widget B'));
    unset($order); // Order's refcount hits 0 immediately — freed without GC!
}
$memAfterV2 = getMemoryKB();
echo "\n=== WeakReference fix ===\n";
echo "Memory before loop: {$memBeforeV2} KB\n";
echo "Memory after 5000 iterations (no leak): {$memAfterV2} KB\n";
echo "Net change: " . ($memAfterV2 - $memBeforeV2) . " KB (should be near 0)\n";

<?php
declare(strict_types=1);

/**
 * A practical memory monitoring harness for long-running PHP workers.
 * Demonstrates: memory bracketing, gc_status() telemetry, and
 * static cache leak simulation with detection.
 *
 * Pattern: wrap every job iteration with MemoryMonitor to catch leaks early.
 */

final class MemoryMonitor
{
    private int $baselineBytes;
    private int $iterationCount = 0;
    private int $totalBytesLeaked = 0;

    public function __construct(
        private readonly int  $alertThresholdBytes = 1_048_576, // 1 MB per iteration
        private readonly bool $forceGcBeforeMeasure = true
    ) {
        $this->baselineBytes = memory_get_usage();
    }

    public function beginIteration(): void
    {
        $this->iterationCount++;
        // Ensure we're measuring steady-state, not leftover allocation noise
        if ($this->forceGcBeforeMeasure) {
            gc_collect_cycles();
        }
        $this->baselineBytes = memory_get_usage();
    }

    public function endIteration(string $jobDescription): void
    {
        if ($this->forceGcBeforeMeasure) {
            gc_collect_cycles();
        }
        $currentBytes  = memory_get_usage();
        $deltaBytes    = $currentBytes - $this->baselineBytes;
        $this->totalBytesLeaked += max(0, $deltaBytes); // only count growth, not shrink

        $gcStatus = gc_status();

        $report = sprintf(
            '[Iter %04d] %-30s | Delta: %+d KB | Peak: %d MB | GC Roots: %d | Cycles Collected: %d',
            $this->iterationCount,
            $jobDescription,
            (int)($deltaBytes / 1024),
            (int)(memory_get_peak_usage() / 1024 / 1024),
            $gcStatus['roots'],        // pending roots in the buffer
            $gcStatus['collected'],    // total cycles freed since process start
        );

        echo $report . "\n";

        // Alert if this single iteration leaked more than the threshold
        if ($deltaBytes > $this->alertThresholdBytes) {
            echo "  *** MEMORY ALERT: iteration leaked " . (int)($deltaBytes / 1024) . " KB — investigate immediately ***\n";
        }
    }

    public function summary(): void
    {
        echo "\n=== Memory Monitor Summary ===\n";
        echo "Total iterations:   {$this->iterationCount}\n";
        echo "Total net growth:   " . (int)($this->totalBytesLeaked / 1024) . " KB\n";
        echo "Per-iteration avg:  " . (int)($this->totalBytesLeaked / $this->iterationCount / 1024) . " KB\n";
        echo "Current usage:      " . (int)(memory_get_usage() / 1024) . " KB\n";
        echo "Peak usage:         " . (int)(memory_get_peak_usage() / 1024 / 1024) . " MB\n";
    }
}

// --- Simulate two job types: a clean one and a leaking one ---

// LEAK PATTERN: a static cache that never evicts (common in poorly-designed singletons)
class ProductRepository
{
    /** @var array<int, array<string,mixed>> */
    private static array $queryCache = []; // grows forever — classic long-running leak

    public static function findById(int $productId): array
    {
        if (!isset(self::$queryCache[$productId])) {
            // Simulates a DB row — in reality this would be a PDO fetch
            self::$queryCache[$productId] = [
                'id'          => $productId,
                'name'        => 'Product ' . $productId,
                'description' => str_repeat('x', 1024), // 1KB per entry
            ];
        }
        return self::$queryCache[$productId];
    }

    // The fix: add a cache size limit or a clear method called after each job
    public static function clearCache(): void
    {
        self::$queryCache = [];
    }
}

function processOrderJobClean(int $orderId): void
{
    // Fetches product but clears the static cache after each job
    ProductRepository::findById($orderId);
    ProductRepository::findById($orderId + 1);
    ProductRepository::clearCache(); // releases static cache — memory returns to baseline
}

function processOrderJobLeaking(int $orderId): void
{
    // Fetches product but NEVER clears the cache — static grows unbounded
    ProductRepository::findById($orderId);
    ProductRepository::findById($orderId + 1);
    // No clearCache() call — each iteration permanently adds ~2KB to the static array
}

$monitor = new MemoryMonitor(alertThresholdBytes: 4096); // alert on > 4KB growth per iter

echo "--- Phase 1: Clean jobs (cache cleared each iteration) ---\n";
for ($jobId = 1; $jobId <= 5; $jobId++) {
    $monitor->beginIteration();
    processOrderJobClean($jobId * 100);
    $monitor->endIteration("processOrderJob#" . $jobId);
}

echo "\n--- Phase 2: Leaking jobs (static cache grows unbounded) ---\n";
for ($jobId = 1; $jobId <= 5; $jobId++) {
    $monitor->beginIteration();
    processOrderJobLeaking($jobId * 100 + 50);
    $monitor->endIteration("leakingJob#" . $jobId);
}

$monitor->summary();