Magic methods

What it is and why it exists

PHP magic methods are double-underscore methods that the engine calls according to a protocol. Business code usually doesn’t call them directly. It reads a property, calls a method, uses clone, calls serialize(), or requests a string conversion; the engine recognizes the operation-method pair and gives the object control.

These hooks adapt behavior at the edges of the object model. An object can map dynamic fields into an internal array, act as a callable strategy, or restore its invariants during copying and persistence. Framework models, proxies, lazy loaders, and test doubles often use them, but an ordinary domain object may need none.

PHP property overloading isn’t Java- or C++-style selection by parameter signature. It means dynamically handling a read, write, existence check, or deletion of an inaccessible property. Inaccessible includes an undefined property and a private or protected property that the current calling scope can’t access.

PHP reserves the double-underscore prefix. Don’t invent application protocols such as __publish() unless the manual defines that magic method. Business entry points should be ordinary methods so callers, IDEs, and static analyzers can see the contract.

The common hooks group by triggering operation:

How it works

A specific syntax form or built-in function triggers each magic method; magic methods don’t take over every operation on an object. Reading an accessible declared property reads it directly, and calling an accessible declared method executes it directly. A property or method overloading hook gets a chance only when ordinary lookup can’t complete the current operation.

The simplified flow for one operation looks like this. Each hook receives different arguments and returns a different type, but all should translate an engine entry point into a narrow, testable object contract.

Property access is a protocol family

__get(string $name): mixed handles reads, and __set(string $name, mixed $value): void handles writes. __isset(string $name): bool decides the result of isset() and is also consulted by empty(); if the result says a value exists, empty() may then read that value. __unset(string $name): void handles deletion.

All four methods should share one policy for names, nullability, and write access. If __get() accepts nickname => null, __isset() can still return false according to native isset() semantics, but an unknown name shouldn’t silently become the same null. Use array_key_exists() when internal storage must distinguish a missing key from a key whose value is null.

Method overloading is fallback dispatch

__call(string $name, array $arguments): mixed handles an inaccessible instance method, and __callStatic(string $name, array $arguments): mixed handles the static equivalent. The latter must be declared static. Both the name and arguments are runtime data, so the hook must enforce its own allowlist, arity, and type checks.

Don’t forward $name to a service object without restriction. Doing so makes the proxy’s public interface change with the service implementation and can expose methods callers shouldn’t trigger. An explicit match or a closed name-to-closure map is easier to review.

Conversion, invocation, and object state

A string context calls __toString(): string. PHP also treats a class with this method as implementing Stringable, though declaring the interface makes the intent clearer. Parentheses after an object call __invoke(), so such an instance can be passed to an API that expects a callback .

clone first makes a shallow property copy and then calls __clone() on the new object. serialize() prefers the state array supplied by __serialize(), while unserialize() uses __unserialize() to restore state. A constructor doesn’t replace the unserialization hook, so restoration must establish valid state itself.

Examples

These four examples progress through a property protocol, restricted method dispatch, a callable value object, and cloning plus serialization. Every output shown came from running the corresponding file with local PHP 8.3.33.

Building a strict property protocol

Profile permits only three dynamic names and keeps their data in one declared array. Reading an unknown name fails, so a capitalization typo can’t masquerade as a missing value.

The constructor state contains nickname => null, so reading that property is legal while isset() still returns false under native null semantics. If the domain needs a key-presence query, add a separate named method instead of changing the familiar meaning of isset().

__set() doesn’t execute $this->{$name} = $value. That form creates a real dynamic property and enters a deprecation path on PHP 8.2 and later. An internal array also centralizes the name and type policy.

Restricting dynamic method dispatch

OrderActions exposes two dynamic actions without handing every name to its implementation. The hook validates the method name, argument count, and order ID type together.

<?php

declare(strict_types=1);

final class OrderActions
{
    public function __call(string $name, array $arguments): string
    {
        if (!in_array($name, ['cancel', 'resendReceipt'], true)) {
            throw new BadMethodCallException("Unsupported action: {$name}");
        }
        if (count($arguments) !== 1 || !is_int($arguments[0])) {
            throw new InvalidArgumentException('Expected one integer order ID');
        }

        return match ($name) {
            'cancel' => $this->cancelOrder($arguments[0]),
            'resendReceipt' => $this->resend($arguments[0]),
        };
    }

    private function cancelOrder(int $orderId): string
    {
        return "Order {$orderId} cancelled";
    }

    private function resend(int $orderId): string
    {
        return "Receipt {$orderId} resent";
    }
}

$actions = new OrderActions();
echo $actions->cancel(17), "\n";
echo $actions->resendReceipt(23), "\n";

try {
    echo $actions->delete(31);
} catch (BadMethodCallException $error) {
    echo $error->getMessage(), "\n";
}

Order 17 cancelled
Receipt 23 resent
Unsupported action: delete

The allowlist is this object’s real public protocol. If the actions are stable, directly declaring cancel(int $orderId) and resendReceipt(int $orderId) is usually better. Dynamic dispatch fits a narrow boundary whose name set comes from explicit metadata.

The example doesn’t use method_exists() as an authorization check. That function answers whether a method exists in the implementation, not whether a caller should access it or whether the current scope can call it legally.

Using an object as a function and string

The discount object stores validated basis points and exposes one main operation through __invoke(). Its __toString() produces only a concise human-readable label, not a JSON or persistence protocol.

<?php

declare(strict_types=1);

final class PercentageDiscount implements Stringable
{
    public function __construct(private int $basisPoints)
    {
        if ($basisPoints < 0 || $basisPoints > 10_000) {
            throw new InvalidArgumentException('Invalid discount');
        }
    }

    public function __invoke(int $priceInCents): int
    {
        return intdiv($priceInCents * (10_000 - $this->basisPoints), 10_000);
    }

    public function __toString(): string
    {
        return number_format($this->basisPoints / 100, 2) . '% off';
    }
}

$discount = new PercentageDiscount(1_500);
echo $discount, "\n";
echo 'callable: ', is_callable($discount) ? 'yes' : 'no', "\n";
printf("final price: $%.2f\n", $discount(12_000) / 100);

15.00% off
callable: yes
final price: $102.00

The amount uses integer cents so the example doesn’t mix binary floating-point rounding into a magic-method lesson. __invoke() parameters and return values remain ordinary PHP type contracts; calling an object doesn’t bypass type checking.

The string form is an object representation . This __toString() result is suitable for a log label or UI fragment but shouldn’t be parsed back; machine protocols need explicit fields and versioned formats.

Separating copied state from persistent state

The cart clones its owned address and drops a session token. The modern serialization hooks keep only business state. This example unserializes only bytes that the same process has just produced and therefore trusts.

<?php

declare(strict_types=1);

final class Address
{
    public function __construct(public string $city) {}
}

final class CartDraft
{
    public function __construct(
        public Address $address,
        private array $items,
        private string $sessionToken,
    ) {}

    public function __clone(): void
    {
        $this->address = clone $this->address;
        $this->sessionToken = '';
    }

    public function __serialize(): array
    {
        return ['address' => $this->address, 'items' => $this->items];
    }

    public function __unserialize(array $data): void
    {
        if (!($data['address'] ?? null) instanceof Address || !is_array($data['items'] ?? null)) {
            throw new UnexpectedValueException('Invalid cart data');
        }
        $this->address = $data['address'];
        $this->items = $data['items'];
        $this->sessionToken = '';
    }

    public function hasSessionToken(): bool
    {
        return $this->sessionToken !== '';
    }
}

$original = new CartDraft(new Address('Paris'), ['BK-1' => 2], 'secret');
$copy = clone $original;
$copy->address->city = 'Lyon';
$restored = unserialize(serialize($original), [
    'allowed_classes' => [CartDraft::class, Address::class],
]);

echo "original: {$original->address->city}\n";
echo "copy: {$copy->address->city}\n";
echo 'clone token: ', $copy->hasSessionToken() ? 'yes' : 'no', "\n";
echo "restored: {$restored->address->city}\n";
echo 'restored token: ', $restored->hasSessionToken() ? 'yes' : 'no', "\n";

original: Paris
copy: Lyon
clone token: no
restored: Paris
restored token: no

Without __clone(), both carts would point to the same Address, and changing the copy’s city would change the original. A deep copy doesn’t mean mechanically cloning every object. This implementation copies the mutable value the cart owns and explicitly resets an ephemeral credential.

allowed_classes narrows the types this trusted example can restore, but it isn’t a safety promise for attacker-controlled input. External JSON, cookies, or database fields should use a data-only format, strict schema validation, and explicit construction.

Pitfalls

Treating a hook as a universal interceptor

Fix: enumerate the triggering syntax, member visibility, and expected hook. Cross-cutting logic that must cover every call belongs in an explicit service, decorator, or unified entry point rather than lookup failure.

Swallowing name errors as null

Fix: share one allowlist and distinguish unknown, missing, and explicitly null. Throw a name-bearing exception for an unknown member and handle an optional field through a documented nullable contract.

Forwarding methods without restriction

Fix: map external names to fixed actions, validate each argument list, and reject everything else. Prefer ordinary named methods and an interface when the set is fixed; method_exists() isn’t an authorization policy.

Depending on a destructor for critical work

Fix: give the resource a close(), commit(), or scoped management method and pair it with try/finally. A destructor may perform small, idempotent local fallback cleanup, but it isn’t a business success signal.

Serializing the whole object state

Fix: make __serialize() return only necessary, versioned data. Make __unserialize() validate keys, types, and invariants and establish safe defaults for ephemeral dependencies. A password or token isn’t confidential merely because it sits in a private property.

Calling unserialize() on untrusted bytes

Fix: use a data-only format such as JSON at external boundaries, then validate and construct domain objects explicitly. When PHP serialized data must be read from trusted storage, verify its integrity and minimize the restorable class set.

Further reading

• PHP manual: Magic methods
• PHP manual: Overloading
• PHP manual: Object cloning
• PHP manual: Serializing objects
• PHP manual: unserialize()
• PHP manual: Dynamic properties