PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

class OrderNumber
{
    public function __construct(private int $id) {}
    public function label(): string { return 'ORD-' . $this->id; }
    public function __toString(): string { return $this->label(); }
}
$order = new OrderNumber(42);
echo $order->label(), "\n";
echo $order, "\n";

ORD-42
ORD-42

__toString пишется с двумя подчёркиваниями и должен соблюдать строковый договор. PHP вызывает его при соответствующем приведении объекта к строке. Он не выполняется при любой передаче объекта и не заменяет все операции заказа.

<?php
declare(strict_types=1);

class AtLeastPrice
{
    public function __construct(private int $minimumKopecks) {}
    public function __invoke(array $product): bool
    {
        return $product['price_kopecks'] >= $this->minimumKopecks;
    }
}
$products = [
    ['title' => 'Чай', 'price_kopecks' => 25900],
    ['title' => 'Кофе', 'price_kopecks' => 45000],
];
$filter = new AtLeastPrice(30000);
foreach (array_filter($products, $filter) as $product) {
    echo $product['title'], ': ', $product['price_kopecks'], " коп.\n";
}

Кофе: 45000 коп.

array_filter передаёт каждую запись в callable $filter. Поскольку это объект с __invoke, PHP вызывает этот метод; bool определяет оставить ли товар. В этом примере структура записей уже известна. Для единственного фильтра короткое замыкание может быть проще объекта.

<?php
declare(strict_types=1);

class Settings
{
    private array $values = ['locale' => 'ru'];
    public function __get(string $name): mixed
    {
        if (!array_key_exists($name, $this->values)) {
            throw new OutOfBoundsException('Неизвестная настройка: ' . $name);
        }
        return $this->values[$name];
    }
}
$settings = new Settings();
echo 'Язык: ', $settings->locale, "\n";
try { echo $settings->loacle; }
catch (OutOfBoundsException $error) { echo $error->getMessage(), "\n"; }

Язык: ru
Неизвестная настройка: loacle

Обращение к недоступному объявленному или отсутствующему полю может вызвать __get. Мы разрешили только ключи внутренней схемы. property_exists не вызывает __get ради поиска виртуальных полей. Для нового простого API явный locale() или объявленное свойство обычно легче исследовать инструментами.

<?php
declare(strict_types=1);

class ProductLabel
{
    public function __construct(private string $title) {}
    public function __toString(): string { return $this->title; }
}
$label = new ProductLabel('<Чай & кофе>');
echo htmlspecialchars((string) $label, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'), "\n";

<Чай & кофе>

Это точный текст HTML-экранированного результата, показанный как CLI-вывод. __toString только возвращает название; контекст HTML требует htmlspecialchars. Для JSON используется json_encode, для SQL — параметры запроса, а не это экранирование.

<?php
declare(strict_types=1);

class Customer implements JsonSerializable
{
    public function __construct(private int $id, private string $name, private string $internalNote) {}
    public function jsonSerialize(): array { return ['id' => $this->id, 'name' => $this->name]; }
}
$customer = new Customer(7, 'Анна', 'Позвонить после 18:00');
echo json_encode($customer, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), "\n";

{"id":7,"name":"Анна"}

JsonSerializable — интерфейс, а jsonSerialize не относится к методам с двойным подчёркиванием. Здесь он задаёт явный внешний набор полей. Не путайте JSON для обмена с serialize для PHP-состояния.

<?php
declare(strict_types=1);

final class ImportBookmark
{
    private int $page;

    public function __construct(int $page)
    {
        $this->setPage($page);
    }

    private function setPage(int $page): void
    {
        if ($page < 1 || $page > 1000) {
            throw new InvalidArgumentException('Недопустимая страница');
        }
        $this->page = $page;
    }

    public function page(): int
    {
        return $this->page;
    }

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

    public function __unserialize(array $data): void
    {
        if (($data['version'] ?? null) !== 1 || !is_int($data['page'] ?? null)) {
            throw new UnexpectedValueException('Формат закладки не поддерживается');
        }
        $this->setPage($data['page']);
    }
}

$original = new ImportBookmark(3);
$saved = serialize($original);
$restored = unserialize($saved, ['allowed_classes' => [ImportBookmark::class]]);
if (!$restored instanceof ImportBookmark) {
    throw new UnexpectedValueException('Ожидалась закладка');
}
echo 'Следующая страница: ', $restored->page(), "\n";
echo $original === $restored ? "Тот же экземпляр\n" : "Новый экземпляр\n";
try {
    $restored->__unserialize(['version' => 1, 'page' => 0]);
} catch (InvalidArgumentException $error) {
    echo "Проверка отклонила страницу\n";
}
echo 'После отказа: ', $restored->page(), "\n";

Следующая страница: 3
Новый экземпляр
Проверка отклонила страницу
После отказа: 3

Прямой вызов __unserialize в конце — изолированная проверка нашей функции валидации, а не рекомендуемый прикладной API. SetPage проверяет до присваивания, поэтому плохое значение не портит уже существующий объект. Для загрузки нескольких полей сначала проверьте весь набор, потом меняйте состояние.

<?php
declare(strict_types=1);

class LocalDeals
{
    public function listDeals(): array
    {
        return [['ID' => 42, 'TITLE' => 'Учебная сделка']];
    }

    public function __call(string $name, array $arguments): mixed
    {
        if ($name === 'oldList' && $arguments === []) {
            return $this->listDeals();
        }
        throw new BadMethodCallException('Неизвестный вызов');
    }

    public static function __callStatic(string $name, array $arguments): mixed
    {
        if ($name === 'oldClient' && $arguments === []) {
            return new self();
        }
        throw new BadMethodCallException('Неизвестная фабрика');
    }
}

$client = LocalDeals::oldClient();
echo $client->oldList()[0]['TITLE'], "\n";
try {
    $client->deleteEverything();
} catch (BadMethodCallException $error) {
    echo "Неизвестная операция отклонена\n";
}
echo method_exists($client, 'oldList') ? "Метод объявлен\n" : "Объявления oldList нет\n";

Учебная сделка
Неизвестная операция отклонена
Объявления oldList нет

Список здесь — локальный fixture, сеть не вызывается. __CallStatic должен быть static; у него нет $this. __Call получает аргументы массивом, поэтому правила количества и типов нужно проверить самостоятельно. Method_exists ищет реальное объявление и не угадывает, какие имена разрешает наша магия.

<?php
declare(strict_types=1);

class LocalPreferences
{
    private array $values = ['theme' => 'dark'];

    public function __get(string $name): mixed
    {
        return $this->values[$name] ?? null;
    }

    public function __isset(string $name): bool
    {
        return isset($this->values[$name]);
    }

    public function __unset(string $name): void
    {
        unset($this->values[$name]);
    }
}

$preferences = new LocalPreferences();
echo $preferences->theme, "\n";
unset($preferences->theme);
echo isset($preferences->theme) ? "Настройка есть\n" : "Настройки нет\n";

dark
Настройки нет

Значение живёт в values, динамическое свойство theme не создаётся. Для фиксированной модели предпочтительнее объявленные поля или явный removeTheme. Эта компактная карта не предоставляет запись извне и не является готовой системой настроек с проверкой схемы.

<?php
declare(strict_types=1);

final class ExportOptions
{
    public function __construct(private string $format)
    {
        if (!in_array($format, ['csv', 'json'], true)) {
            throw new InvalidArgumentException('Неизвестный формат');
        }
    }

    public function __debugInfo(): array
    {
        return ['format' => $this->format, 'description' => 'Настройки экспорта'];
    }

    public static function __set_state(array $properties): object
    {
        if (!is_string($properties['format'] ?? null)) {
            throw new InvalidArgumentException('Ожидалась строка формата');
        }
        return new self($properties['format']);
    }

    public function format(): string
    {
        return $this->format;
    }
}

$options = new ExportOptions('csv');
ob_start();
var_dump($options);
$diagnostic = ob_get_clean();
echo str_contains($diagnostic, 'Настройки экспорта') ? "Дамп использует __debugInfo\n" : "Нет описания\n";
$phpExpression = var_export($options, true);
echo str_contains($phpExpression, '__set_state') ? "Экспорт содержит вызов восстановления\n" : "Нет вызова\n";
$copy = ExportOptions::__set_state(['format' => 'csv']);
echo $copy->format(), "\n";

Дамп использует __debugInfo
Экспорт содержит вызов восстановления
csv

Буфер перехватывает var_dump, поэтому пример не зависит от номера объекта в дампе. Var_export возвращает текст PHP-выражения; при экспорте сам __set_state ещё не выполняется. Мы проверяем наличие вызова в тексте и отдельно вызываем восстановление с известным массивом, без eval и без запуска внешнего PHP-кода.

<?php
declare(strict_types=1);

class ReportSettings
{
    private array $data = ['enabled' => '0', 'name' => 'Отчёт', 'note' => null];
    public array $events = [];

    public function __isset(string $name): bool
    {
        $this->events[] = 'isset:' . $name;
        return isset($this->data[$name]);
    }

    public function __get(string $name): mixed
    {
        $this->events[] = 'get:' . $name;
        return $this->data[$name] ?? null;
    }
}

$settings = new ReportSettings();
echo isset($settings->note) ? "Есть\n" : "Нет ненулевого значения\n";
echo empty($settings->enabled) ? "Пусто по правилам empty\n" : "Не пусто\n";
echo empty($settings->name) ? "Без имени\n" : "Имя задано\n";
echo implode(', ', $settings->events), "\n";

Нет ненулевого значения
Пусто по правилам empty
Имя задано
isset:note, isset:enabled, get:enabled, isset:name, get:name

Строка 0 существует, но empty даёт true. Для формы «значение обязательно, ноль разрешён» нужна явная проверка допустимого типа и значения. В собственном __isset можно выбрать другую семантику, например array_key_exists для наличия ключа даже с null, но тогда это необходимо документировать.

<?php
declare(strict_types=1);

class ReportDraft
{
    private string $status = 'Проверяется';
    private array $extra = [];
    public array $events = [];

    public function currentStatus(): string { return $this->status; }
    public function __get(string $name): mixed
    {
        $this->events[] = 'get:' . $name;
        return $name === 'status' ? 'Доступен только просмотр' : ($this->extra[$name] ?? null);
    }
    public function __set(string $name, mixed $value): void
    {
        $this->events[] = 'set:' . $name;
        $this->extra[$name] = $value;
    }
}

$draft = new ReportDraft();
echo $draft->status, "\n";
echo $draft->currentStatus(), "\n";
$assigned = $draft->limit = 10;
echo $assigned, "\n";
echo implode(', ', $draft->events), "\n";

Доступен только просмотр
Проверяется
10
get:status, set:limit

Снаружи private status недоступно, поэтому работает __get. В currentStatus поле доступно напрямую. В цепочке присваивания результатом является присвоенное 10: PHP не вызывает __get для его повторного чтения, а возвращаемое значение __set не служит результатом присваивания.

<?php
declare(strict_types=1);

class LegacyBookmark
{
    public string $caption = '';
    public function __construct(public string $sku)
    {
        $this->caption = 'Товар ' . $sku;
    }
    public function __sleep(): array { return ['sku']; }
    public function __wakeup(): void { $this->caption = 'Товар ' . $this->sku; }
}

$original = new LegacyBookmark('P-42');
$original->caption = 'Временное оформление';
$saved = serialize($original);
$restored = unserialize($saved, ['allowed_classes' => [LegacyBookmark::class]]);
if (!$restored instanceof LegacyBookmark) {
    throw new UnexpectedValueException('Неверный тип локального снимка');
}
echo $restored->caption, "\n";
echo $restored === $original ? "Тот же объект\n" : "Отдельный экземпляр\n";

Товар P-42
Отдельный экземпляр

Caption не входит в список __sleep: она собирается заново. Это чтение исторического кода, а не рекомендация нового формата. __Sleep также неудобен для private-полей родителя: простой список имён в потомке не решает различие областей этих свойств.

<?php
declare(strict_types=1);

class CurrentBookmark
{
    public function __construct(public string $sku) {}
    public function __serialize(): array { return ['version' => 1, 'product' => $this->sku]; }
    public function __unserialize(array $data): void
    {
        if (($data['version'] ?? null) !== 1 || !is_string($data['product'] ?? null)) {
            throw new UnexpectedValueException('Неподдерживаемый снимок');
        }
        if (!preg_match('/\AP-[1-9][0-9]*\z/', $data['product'])) {
            throw new UnexpectedValueException('Недопустимый артикул');
        }
        $this->sku = $data['product'];
    }
    public function __sleep(): array { throw new LogicException('Старый путь не нужен'); }
    public function __wakeup(): void { throw new LogicException('Старый путь не нужен'); }
}

$saved = serialize(new CurrentBookmark('P-42'));
$restored = unserialize($saved, ['allowed_classes' => [CurrentBookmark::class]]);
if (!$restored instanceof CurrentBookmark) {
    throw new UnexpectedValueException('Неверный тип локального снимка');
}
echo $restored->sku, "\n";
echo "Современная пара обработала снимок\n";

P-42
Современная пара обработала снимок

Если бы PHP вызвал старую пару, пример завершился бы исключением. __Unserialize получает собственную схему данных; конструктор его не подстраховывает, поэтому проверка здесь самостоятельная. Allowed_classes ограничивает обычные классы, но не делает недоверенный сериализованный поток безопасным.

<?php
class StoredBookmark
{
    public function __construct(public string $sku) {}
    public function caption(): string { return 'Товар ' . $this->sku; }
}

Этот файл лежит рядом с main.php и producer.php. Он виден как часть проекта, но до require не определяет класс в каждом другом процессе автоматически.

<?php
require __DIR__ . '/StoredBookmark.php';
echo serialize(new StoredBookmark('P-42'));

Выполняется только наш локальный фиксированный файл. Строка снимка не приходит из запроса и не содержит данных пользователя.

<?php
declare(strict_types=1);

$process = proc_open(
    [PHP_BINARY, '-n', __DIR__ . '/producer.php'],
    [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']],
    $pipes
);
if (!is_resource($process)) { throw new RuntimeException('Не запущен producer'); }
fclose($pipes[0]);
$saved = stream_get_contents($pipes[1]);
$errors = stream_get_contents($pipes[2]);
fclose($pipes[1]);
fclose($pipes[2]);
if (proc_close($process) !== 0 || $errors !== '') {
    throw new RuntimeException('Не создан локальный снимок');
}

$withoutClass = unserialize($saved, ['allowed_classes' => ['StoredBookmark']]);
echo get_class($withoutClass), "\n";
$loader = static function (string $class): void {
    if ($class === 'StoredBookmark') { require __DIR__ . '/StoredBookmark.php'; }
};
spl_autoload_register($loader);
try {
    $ready = unserialize($saved, ['allowed_classes' => ['StoredBookmark']]);
    if (!$ready instanceof StoredBookmark) { throw new UnexpectedValueException('Нет класса'); }
    echo $ready->caption(), "\n";
} finally {
    spl_autoload_unregister($loader);
}

__PHP_Incomplete_Class
Товар P-42

Первый неполный объект не превращается в готовый после подключения класса: мы отдельно восстанавливаем исходную строку второй раз. Сохранены имя класса и состояние; реализация caption берётся из текущего файла. При изменении класса разработчик отвечает за совместимость схемы.

<?php
declare(strict_types=1);

class MigratingBookmark implements Serializable
{
    public static array $paths = [];
    public function __construct(public string $sku) {}

    private function restore(array $data): void
    {
        if (($data['version'] ?? null) !== 1 || !is_string($data['sku'] ?? null)
            || !preg_match('/\AP-[1-9][0-9]*\z/', $data['sku'])) {
            throw new UnexpectedValueException('Неверная схема закладки');
        }
        $this->sku = $data['sku'];
    }
    public function serialize(): string
    {
        return json_encode(['version' => 1, 'sku' => $this->sku], JSON_THROW_ON_ERROR);
    }
    public function unserialize(string $data): void
    {
        self::$paths[] = 'Старый C';
        $decoded = json_decode($data, true, 8, JSON_THROW_ON_ERROR);
        if (!is_array($decoded)) { throw new UnexpectedValueException('Ожидается массив'); }
        $this->restore($decoded);
    }
    public function __serialize(): array { return ['version' => 1, 'sku' => $this->sku]; }
    public function __unserialize(array $data): void
    {
        self::$paths[] = 'Новый O';
        $this->restore($data);
    }
}

$original = new MigratingBookmark('P-42');
$className = MigratingBookmark::class;
$payload = $original->serialize();
$oldFixture = 'C:' . strlen($className) . ':"' . $className . '":'
    . strlen($payload) . ':{' . $payload . '}';
$newFixture = serialize($original);
foreach ([$oldFixture, $newFixture] as $saved) {
    $restored = unserialize($saved, ['allowed_classes' => [MigratingBookmark::class]]);
    if (!$restored instanceof MigratingBookmark) { throw new UnexpectedValueException('Неверный класс'); }
    echo $restored->sku, "\n";
}
echo implode(' / ', MigratingBookmark::$paths), "\n";

P-42
P-42
Старый C / Новый O

Имя serialize у обычного вызова $original->serialize() и у функции serialize($original) обозначает разные точки входа. Вторая выбирает протокол PHP и теперь вызывает __serialize. Длина в старом заголовке измеряется в байтах через strlen. Этот учебный мост не делает произвольную строку безопасной.