PHP Magic Methods Explained: __get, __set, __call and Beyond

<?php

class CsvFileWriter
{
    private $fileHandle;      // Holds the open file resource
    private string $filePath;
    private int $rowsWritten = 0;

    public function __construct(string $filePath, string $mode = 'w')
    {
        // Validate the directory exists before we even try to open the file.
        // This enforces a valid state at birth — no half-constructed objects.
        $directory = dirname($filePath);
        if (!is_dir($directory)) {
            throw new InvalidArgumentException(
                "Directory '{$directory}' does not exist."
            );
        }

        $this->filePath   = $filePath;
        $this->fileHandle = fopen($filePath, $mode);

        if ($this->fileHandle === false) {
            throw new RuntimeException("Could not open file: {$filePath}");
        }

        echo "[__construct] File opened: {$filePath}" . PHP_EOL;
    }

    public function writeRow(array $columns): void
    {
        // fputcsv handles quoting and escaping automatically
        fputcsv($this->fileHandle, $columns);
        $this->rowsWritten++;
    }

    public function __destruct()
    {
        // Even if the developer forgets to close the file,
        // this cleanup runs automatically when the object is destroyed.
        if (is_resource($this->fileHandle)) {
            fclose($this->fileHandle);
            echo "[__destruct] File closed after writing {$this->rowsWritten} row(s): {$this->filePath}" . PHP_EOL;
        }
    }
}

// --- Usage ---

function exportUserReport(string $outputPath): void
{
    $writer = new CsvFileWriter($outputPath);

    $writer->writeRow(['id', 'name', 'email']);
    $writer->writeRow([1, 'Alice Johnson', 'alice@example.com']);
    $writer->writeRow([2, 'Bob Smith',    'bob@example.com']);

    // No manual fclose() needed — __destruct handles it
    // when $writer goes out of scope at the end of this function.
}

exportUserReport('/tmp/users_report.csv');

echo "Function has returned — object is already cleaned up." . PHP_EOL;

<?php

/**
 * Wraps an API JSON response so callers can access fields as properties
 * instead of navigating raw arrays: $response->userId vs $response->data['user_id']
 */
class ApiResponseWrapper
{
    // The raw decoded payload lives here — hidden from the outside world
    private array $payload;

    // Track which fields were accessed, useful for debugging / analytics
    private array $accessLog = [];

    public function __construct(array $jsonPayload)
    {
        $this->payload = $jsonPayload;
    }

    /**
     * Fires when you read a property that doesn't exist on this class directly.
     * Converts camelCase property names to snake_case to match typical JSON keys.
     */
    public function __get(string $propertyName): mixed
    {
        $snakeKey = $this->toSnakeCase($propertyName);
        $this->accessLog[] = $snakeKey;

        if (!array_key_exists($snakeKey, $this->payload)) {
            // Return null gracefully rather than throwing — caller can check with isset()
            return null;
        }

        return $this->payload[$snakeKey];
    }

    /**
     * Fires when you try to write a property that isn't explicitly declared.
     * We store the update in the payload so it's round-trippable.
     */
    public function __set(string $propertyName, mixed $value): void
    {
        $snakeKey = $this->toSnakeCase($propertyName);
        $this->payload[$snakeKey] = $value;
    }

    /**
     * CRITICAL: Without this, isset($response->userId) always returns false
     * even when the key exists in the payload. This breaks null-coalescing
     * operators and if(isset()) guards throughout your codebase.
     */
    public function __isset(string $propertyName): bool
    {
        $snakeKey = $this->toSnakeCase($propertyName);
        return isset($this->payload[$snakeKey]);
    }

    /**
     * Allows unset($response->userId) to actually remove the key from the payload.
     */
    public function __unset(string $propertyName): void
    {
        $snakeKey = $this->toSnakeCase($propertyName);
        unset($this->payload[$snakeKey]);
    }

    public function getAccessLog(): array
    {
        return $this->accessLog;
    }

    // Converts 'userId' -> 'user_id', 'createdAt' -> 'created_at'
    private function toSnakeCase(string $camelCase): string
    {
        return strtolower(preg_replace('/[A-Z]/', '_$0', lcfirst($camelCase)));
    }
}

// --- Usage ---

// Simulating a decoded JSON payload from a REST API
$rawPayload = [
    'user_id'    => 42,
    'first_name' => 'Alice',
    'created_at' => '2024-03-15',
    'is_active'  => true,
];

$response = new ApiResponseWrapper($rawPayload);

// Read with camelCase — __get converts it to snake_case internally
echo "User ID: " . $response->userId . PHP_EOL;
echo "First Name: " . $response->firstName . PHP_EOL;

// __isset makes null-coalescing work correctly
$status = isset($response->isActive) ? 'Active' : 'Inactive';
echo "Status: {$status}" . PHP_EOL;

// Reading a field that doesn't exist returns null gracefully
$missing = $response->phoneNumber ?? 'N/A';
echo "Phone: {$missing}" . PHP_EOL;

// Write via __set
$response->lastLoginAt = '2024-11-01';
echo "Last Login: " . $response->lastLoginAt . PHP_EOL;

// Inspect what was accessed (useful for caching / performance profiling)
echo "Fields accessed: " . implode(', ', $response->getAccessLog()) . PHP_EOL;

<?php

/**
 * A simplified fluent query builder that uses __call to handle
 * dynamic 'whereXxx' and 'orderByXxx' methods without defining each one.
 */
class FluentQueryBuilder
{
    private string $table;
    private array  $conditions = [];
    private array  $ordering   = [];
    private ?int   $limitCount = null;

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

    /**
     * Named constructor — __callStatic intercepts FluentQueryBuilder::for('users')
     * even though no static method called 'for' is defined.
     */
    public static function __callStatic(string $methodName, array $arguments): static
    {
        // We only support the 'for' factory method via __callStatic
        if ($methodName === 'for') {
            $tableName = $arguments[0] ?? throw new InvalidArgumentException('Table name required.');
            return new static($tableName); // Returns a fresh builder instance
        }

        throw new BadMethodCallException("Static method '{$methodName}' is not supported.");
    }

    /**
     * Handles:
     *   ->whereEmail('alice@example.com')   => WHERE email = 'alice@example.com'
     *   ->whereIsActive(true)               => WHERE is_active = 1
     *   ->orderByCreatedAt('DESC')          => ORDER BY created_at DESC
     *
     * $methodName = the full method name string, e.g. 'whereEmail'
     * $arguments  = array of arguments passed to the call, e.g. ['alice@example.com']
     */
    public function __call(string $methodName, array $arguments): static
    {
        if (str_starts_with($methodName, 'where')) {
            // Extract 'Email' from 'whereEmail', convert to 'email'
            $columnName = $this->toSnakeCase(substr($methodName, 5));
            $value      = $arguments[0] ?? throw new InvalidArgumentException(
                "A value is required for {$methodName}()"
            );

            // Store as a safe, typed condition
            $this->conditions[] = [
                'column' => $columnName,
                'value'  => $value,
            ];

            return $this; // Return $this to enable chaining
        }

        if (str_starts_with($methodName, 'orderBy')) {
            $columnName = $this->toSnakeCase(substr($methodName, 7));
            $direction  = strtoupper($arguments[0] ?? 'ASC');

            if (!in_array($direction, ['ASC', 'DESC'], true)) {
                throw new InvalidArgumentException("Direction must be ASC or DESC.");
            }

            $this->ordering[] = "{$columnName} {$direction}";

            return $this;
        }

        // Anything we don't recognise should fail loudly, not silently
        throw new BadMethodCallException(
            "Method '{$methodName}' does not exist on " . static::class
        );
    }

    public function limit(int $count): static
    {
        $this->limitCount = $count;
        return $this;
    }

    /**
     * Builds a SQL-like query string for demonstration.
     * In a real ORM this would prepare and execute a PDO statement.
     */
    public function toSql(): string
    {
        $sql = "SELECT * FROM {$this->table}";

        if (!empty($this->conditions)) {
            $whereClauses = array_map(
                fn($c) => "{$c['column']} = '" . addslashes((string) $c['value']) . "'",
                $this->conditions
            );
            $sql .= " WHERE " . implode(' AND ', $whereClauses);
        }

        if (!empty($this->ordering)) {
            $sql .= " ORDER BY " . implode(', ', $this->ordering);
        }

        if ($this->limitCount !== null) {
            $sql .= " LIMIT {$this->limitCount}";
        }

        return $sql;
    }
}

// --- Usage ---

// __callStatic handles the ::for() factory call
$query = FluentQueryBuilder::for('users')
    ->whereIsActive(true)           // __call handles this
    ->whereSubscriptionTier('pro')  // __call handles this too
    ->orderByCreatedAt('DESC')      // and this
    ->limit(10);

echo $query->toSql() . PHP_EOL;

// Another example
$adminQuery = FluentQueryBuilder::for('users')
    ->whereRole('admin')
    ->whereIsVerified(true)
    ->orderByLastLoginAt('DESC');

echo $adminQuery->toSql() . PHP_EOL;

<?php

/**
 * A value object representing a monetary amount.
 * Demonstrates __toString, __invoke, and __clone working together.
 */
class MoneyValue
{
    // Store as integer cents to avoid floating-point rounding errors
    private int $amountInCents;
    private string $currencyCode;
    private DateTime $createdAt;

    public function __construct(int $amountInCents, string $currencyCode = 'USD')
    {
        if ($amountInCents < 0) {
            throw new InvalidArgumentException('Monetary amount cannot be negative.');
        }

        $this->amountInCents = $amountInCents;
        $this->currencyCode  = strtoupper($currencyCode);
        $this->createdAt     = new DateTime();  // Inner object — important for __clone demo
    }

    /**
     * Called automatically when the object is used in a string context.
     * Lets you do: echo $price; or "Total: {$price}" without any ->format() call.
     */
    public function __toString(): string
    {
        $formatted = number_format($this->amountInCents / 100, 2);
        $symbol    = match($this->currencyCode) {
            'USD'  => '$',
            'EUR'  => '€',
            'GBP'  => '£',
            default => $this->currencyCode . ' ',
        };

        return "{$symbol}{$formatted}";
    }

    /**
     * Called when the object is used as a function: $tax = $price(0.2)
     * Here it acts as a multiplier — useful as a transformer/callback.
     * This makes MoneyValue usable anywhere a callable is expected.
     */
    public function __invoke(float $multiplier): static
    {
        $newAmountInCents = (int) round($this->amountInCents * $multiplier);
        return new static($newAmountInCents, $this->currencyCode);
    }

    /**
     * PHP's default clone would make $clone->createdAt point to the SAME
     * DateTime object as the original. Changing one would change both.
     * __clone ensures each clone gets its own independent DateTime instance.
     */
    public function __clone()
    {
        // Deep-copy the inner DateTime object so the clone is truly independent
        $this->createdAt = clone $this->createdAt;
    }

    public function add(MoneyValue $other): static
    {
        if ($this->currencyCode !== $other->currencyCode) {
            throw new InvalidArgumentException('Cannot add different currencies.');
        }
        return new static($this->amountInCents + $other->amountInCents, $this->currencyCode);
    }

    public function getCreatedAt(): DateTime
    {
        return $this->createdAt;
    }
}

// --- Demo: __toString ---
$subtotal = new MoneyValue(4999, 'USD'); // $49.99
$shipping = new MoneyValue(599,  'USD'); // $5.99
$total    = $subtotal->add($shipping);

echo "Subtotal: {$subtotal}" . PHP_EOL; // __toString fires inside the string
echo "Shipping: {$shipping}" . PHP_EOL;
echo "Total:    {$total}"    . PHP_EOL;

// --- Demo: __invoke ---
// Apply 20% tax to the total — $total is called like a function
$taxAmount = $total(0.20);
echo "Tax (20%): {$taxAmount}" . PHP_EOL;

// Works as a callable too — pass it to array_map, usort, etc.
$prices = [new MoneyValue(1000), new MoneyValue(2500), new MoneyValue(500)];
$discounted = array_map(fn($p) => $p(0.9), $prices); // 10% off each
echo "Discounted prices: " . implode(', ', $discounted) . PHP_EOL;

// --- Demo: __clone ---
$original = new MoneyValue(9999, 'GBP');
$copy     = clone $original; // __clone fires here

// Modify the clone's inner DateTime — should NOT affect the original
$copy->getCreatedAt()->modify('+1 year');

echo "Original timestamp: " . $original->getCreatedAt()->format('Y') . PHP_EOL;
echo "Clone timestamp:    " . $copy->getCreatedAt()->format('Y') . PHP_EOL;