Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Standard PHP Library and Classes

WeakMap and WeakReference

Reference for PHP WeakMap and WeakReference: attach data to objects without keeping them alive, how garbage collection removes entries, and when to use them.

Normally, holding an object in an array or property keeps it alive: PHP only frees an object when nothing refers to it. Sometimes you want the opposite, a way to refer to an object without preventing its cleanup. PHP gives you two tools for that.

WeakReference wraps one object and lets you fetch it with get() while it still exists (null afterwards). WeakMap is a map whose keys are objects; when a key object is destroyed, its entry disappears. Typical uses are caches and metadata tables attached to objects you do not own.

PHP
$map = new WeakMap();
$map[$object] = "extra data";
count($map); // entries whose key objects are still alive

Try it

PHP WeakMap entries disappear with their keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP WeakReference::get()

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
final class WeakReference
{
    public static function create(object $object): WeakReference;
    public function get(): ?object;
}

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate
{
    // $map[$object] = $value;  isset($map[$object]);  unset($map[$object]);
    // count($map);  foreach ($map as $object => $value) { ... }
}
Name Description
WeakReference::create($object) Creates a weak reference to $object. Calling it twice for the same live object returns the same WeakReference instance.
WeakReference::get() Returns the object, or null once it has been destroyed.
$map[$object] Reads or writes the value for an object key. Reading a missing key throws Error.

Return value: get() returns ?object. A WeakMap counts only entries whose keys are alive.

Errors / Exceptions: TypeError if a WeakMap key is not an object ("WeakMap key must be an object"); Error when reading a key that is not in the map. WeakReference cannot be constructed with new.

Usage notes

  • Only unset or end of scope frees the object. An entry vanishes when the last strong reference to the key goes away. If any other variable still holds the object, the entry stays.
  • Values are strong. A WeakMap value that refers back to its own key keeps the key alive, so the entry never disappears. Avoid cycles like that.
  • Use isset() before reading unless you are sure the key exists; $map[$obj] ?? null is a safe alternative.
  • Keys are matched by identity, not by equality. Two equal but different objects are two keys.
  • Compare with SplObjectStorage. SplObjectStorage holds objects strongly, so it keeps them alive; WeakMap does not.
  • Not serializable. A WeakMap cannot be passed to serialize().
  • Timing. In CLI scripts with reference counting, destruction is immediate when the count reaches zero. Objects in reference cycles wait for the cycle collector, so counts can lag.
  • Added in PHP 7.4 (WeakReference) and PHP 8.0 (WeakMap).