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

<?php
declare(strict_types=1);

$cursor = new ArrayIterator(['Чай', 'Кофе']);

echo 'На этикетке: ', $cursor->current(), "\n";
echo 'Повторное чтение: ', $cursor->current(), "\n";
$cursor->next();
echo 'Следующий товар: ', $cursor->current(), "\n";

На этикетке: Чай
Повторное чтение: Чай
Следующий товар: Кофе

current читает значение текущей позиции; повторное чтение не двигает позицию. next выполняет отдельный переход. ArrayIterator — готовая реализация Iterator; собственная реализация пяти методов разобрана в главе.

<?php
declare(strict_types=1);

class ProductCursor implements Iterator {
    private int $position = 0;
    private array $items;
    public function __construct(array $items) {
        $this->items = array_values($items);
    }
    public function current(): mixed {
        return $this->items[$this->position] ?? null;
    }
    public function key(): mixed {
        return $this->valid() ? $this->position : null;
    }
    public function next(): void { ++$this->position; }
    public function rewind(): void { $this->position = 0; }
    public function valid(): bool {
        return array_key_exists($this->position, $this->items);
    }
}

$cursor = new ProductCursor([null]);
var_dump($cursor->valid(), $cursor->current());
$cursor->next();
var_dump($cursor->valid(), $cursor->current());

bool(true)
NULL
bool(false)
NULL

Одинаковый результат current не различает элемент null и конец. Нельзя писать while ($cursor->current()) для обхода данных, где допустимы null, 0, false или пустая строка. Поведение чтения вне позиции выбирает реализация, здесь она возвращает null.

<?php
declare(strict_types=1);

$cursor = new ArrayIterator(['Чай', 'Кофе']);

echo 'Позиция ', $cursor->key(), ': ', $cursor->current(), "\n";
$cursor->next();
echo 'Позиция ', $cursor->key(), ': ', $cursor->current(), "\n";

Позиция 0: Чай
Позиция 1: Кофе

key возвращает ключ текущего элемента. В этом списке ключи 0 и 1; в карте артикулов они могли бы быть строками. Интерфейс не обязывает ключ быть целым; следующий пример показывает артикул как ключ.

<?php
$cursor = new ArrayIterator(['A-10' => 'Книга', 'B-20' => 'Лампа']);
$cursor->rewind();
while ($cursor->valid()) {
    echo $cursor->key(), ':', $cursor->current(), "\n";
    $cursor->next();
}

A-10:Книга
B-20:Лампа

Тип mixed в интерфейсе шире int|string. Некоторые источники, например WeakMap, дают объект-ключ через InternalIterator; его нельзя автоматически сохранить как ключ обычного массива. Ожидаемый тип ключа включайте в описание своей коллекции.

<?php
declare(strict_types=1);

$cursor = new ArrayIterator(['Чай', 'Кофе']);

echo 'Уже обработан: ', $cursor->current(), "\n";
$cursor->next();
if ($cursor->valid()) { echo 'Теперь обработать: ', $cursor->current(), "\n"; }

Уже обработан: Чай
Теперь обработать: Кофе

next меняет позицию и возвращает void. Проверка valid перед чтением предотвращает попытку использовать несуществующий элемент после конца. Для обычного полного прохода эти действия делает foreach.

<?php
declare(strict_types=1);

class ProductCursor implements Iterator {
    private int $position = 0;
    private array $items;
    public function __construct(array $items) {
        $this->items = array_values($items);
    }
    public function current(): mixed {
        return $this->items[$this->position] ?? null;
    }
    public function key(): mixed {
        return $this->valid() ? $this->position : null;
    }
    public function next(): void { ++$this->position; }
    public function rewind(): void { $this->position = 0; }
    public function valid(): bool {
        return array_key_exists($this->position, $this->items);
    }
}

$cursor = new ProductCursor(['A', 'B']);
$cursor->rewind();
while ($cursor->valid()) {
    echo $cursor->current(), "\n";
    $cursor->next();
}
var_dump($cursor->valid());

A
B
bool(false)

Забытый next сделал бы этот цикл бесконечным. Обычному выводу списка лучше подходит foreach; ручное управление полезно при пошаговой обработке, объединении потоков и отладке курсора.

<?php
declare(strict_types=1);

$cursor = new ArrayIterator(['Чай', 'Кофе']);

$cursor->next();
echo 'До прохода: ', $cursor->current(), "\n";
foreach ($cursor as $title) { echo 'Этикетка: ', $title, "\n"; }

До прохода: Кофе
Этикетка: Чай
Этикетка: Кофе

foreach вызывает rewind перед обходом, поэтому печать началась с Чая. Конкретный Iterator обязан определить допустимость перемотки; Generator нельзя считать произвольно перематываемым массивом. NoRewindIterator в следующем примере сохраняет текущую позицию.

<?php
declare(strict_types=1);

class ProductCursor implements Iterator {
    private int $position = 0;
    private array $items;
    public function __construct(array $items) {
        $this->items = array_values($items);
    }
    public function current(): mixed {
        return $this->items[$this->position] ?? null;
    }
    public function key(): mixed {
        return $this->valid() ? $this->position : null;
    }
    public function next(): void { ++$this->position; }
    public function rewind(): void { $this->position = 0; }
    public function valid(): bool {
        return array_key_exists($this->position, $this->items);
    }
}

$cursor = new ProductCursor(['A', 'B', 'C']);
$cursor->next();
foreach (new NoRewindIterator($cursor) as $value) {
    echo $value, "\n";
}

B
C

NoRewindIterator из SPL подавляет сброс при начале foreach. Это полезно при продолжении уже начатого чтения. Он не клонирует источник: исходный курсор тоже продвигается.

<?php
declare(strict_types=1);

class ProductCursor implements Iterator {
    private int $position = 0;
    private array $items;
    public function __construct(array $items) {
        $this->items = array_values($items);
    }
    public function current(): mixed {
        return $this->items[$this->position] ?? null;
    }
    public function key(): mixed {
        return $this->valid() ? $this->position : null;
    }
    public function next(): void { ++$this->position; }
    public function rewind(): void { $this->position = 0; }
    public function valid(): bool {
        return array_key_exists($this->position, $this->items);
    }
}

$cursor = new ProductCursor([0, false, null]);
foreach ($cursor as $value) { var_dump($value); }

int(0)
bool(false)
NULL

array_key_exists в реализации valid сохраняет все три позиции. isset вернул бы false для null, а проверка current на истинность отсеяла бы ещё и ноль/false.

<?php
declare(strict_types=1);

$cursor = new ArrayIterator([]);
$cursor->rewind();
echo $cursor->valid() ? "Есть товар\n" : "Каталог пока пуст\n";
foreach ($cursor as $title) { echo 'Товар: ', $title, "\n"; }
echo "Можно предложить добавить первый товар\n";

Каталог пока пуст
Можно предложить добавить первый товар

valid сообщает существование текущей позиции. Для пустого источника foreach не выполнит тело ни разу. Это отличается от существующего элемента 0, false или null; они показаны рядом, чтобы не подменять valid проверкой значения.

<?php
declare(strict_types=1);

class Queue implements Countable
{
    private array $jobs = ['Письмо по заказу 42', 'Отчёт о продажах'];
    public function count(): int { return count($this->jobs); }
}
$queue = new Queue();
echo 'Метод очереди: ', $queue->count(), " задания\n";
echo 'Функция PHP: ', count($queue), " задания\n";

Метод очереди: 2 задания
Функция PHP: 2 задания

Вызов count($queue) направляется в Countable::count реализации Queue. Оба пути дают количество ожидающих элементов. Это осмысленный счётчик интерфейса, но он не оценивает длительность работы и не сохраняет очередь после завершения процесса.

<?php
class Sections implements Countable {
    private array $items = [['A', 'B'], ['C']];
    public function count(): int { return count($this->items); }
}
$sections = new Sections();
echo count($sections), "\n";
echo count($sections, COUNT_RECURSIVE), "\n";

2
2

Обе операции считают две верхние секции: метод не принимает режим и не стал рекурсивным. Если приложению нужен итог по вложенным товарам, создайте явно названный метод. Стоимость count у пользовательского класса зависит от реализации, в отличие от простого чтения количества элементов массива.

<?php
declare(strict_types=1);

class Settings implements ArrayAccess {
    private array $items = [];
    private function requireKey(mixed $offset): int|string {
        if (!is_int($offset) && !is_string($offset)) {
            throw new InvalidArgumentException('Ключ должен быть int или string');
        }
        return $offset;
    }
    public function offsetExists(mixed $offset): bool {
        return isset($this->items[$this->requireKey($offset)]);
    }
    public function offsetGet(mixed $offset): mixed {
        $key = $this->requireKey($offset);
        if (!array_key_exists($key, $this->items)) {
            throw new OutOfBoundsException('Настройка не найдена');
        }
        return $this->items[$key];
    }
    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->items[] = $value;
            return;
        }
        $this->items[$this->requireKey($offset)] = $value;
    }
    public function offsetUnset(mixed $offset): void {
        unset($this->items[$this->requireKey($offset)]);
    }
}

$settings = new Settings();
$settings['null'] = null;
$settings['zero'] = 0;
var_dump(isset($settings['null']), isset($settings['zero']), isset($settings['missing']));
var_dump(empty($settings['zero']));

bool(false)
bool(true)
bool(false)
bool(true)

Реализация через isset внутреннего массива отличает ноль от отсутствия, но считает null не установленным. empty нуля true. Это не обязательно семантика другого ArrayAccess-класса.

<?php
declare(strict_types=1);

class Settings implements ArrayAccess {
    private array $items = [];
    private function requireKey(mixed $offset): int|string {
        if (!is_int($offset) && !is_string($offset)) {
            throw new InvalidArgumentException('Ключ должен быть int или string');
        }
        return $offset;
    }
    public function offsetExists(mixed $offset): bool {
        return array_key_exists($this->requireKey($offset), $this->items);
    }
    public function offsetGet(mixed $offset): mixed {
        $key = $this->requireKey($offset);
        if (!array_key_exists($key, $this->items)) {
            throw new OutOfBoundsException('Настройка не найдена');
        }
        return $this->items[$key];
    }
    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->items[] = $value;
            return;
        }
        $this->items[$this->requireKey($offset)] = $value;
    }
    public function offsetUnset(mixed $offset): void {
        unset($this->items[$this->requireKey($offset)]);
    }
}

$settings = new Settings();
$settings['optional'] = null;
var_dump(isset($settings['optional']));
var_dump(empty($settings['optional']));

bool(true)
bool(true)

Здесь isset объекта отражает наш offsetExists через array_key_exists, поэтому возвращает true даже для null. empty читает null и возвращает true. Такой выбор нужно явно документировать, чтобы читатель не перенёс привычную семантику массивов без проверки.

<?php
declare(strict_types=1);

class Settings implements ArrayAccess {
    private array $items = [];
    private function requireKey(mixed $offset): int|string {
        if (!is_int($offset) && !is_string($offset)) {
            throw new InvalidArgumentException('Ключ должен быть int или string');
        }
        return $offset;
    }
    public function offsetExists(mixed $offset): bool {
        return isset($this->items[$this->requireKey($offset)]);
    }
    public function offsetGet(mixed $offset): mixed {
        $key = $this->requireKey($offset);
        if (!array_key_exists($key, $this->items)) {
            throw new OutOfBoundsException('Настройка не найдена');
        }
        return $this->items[$key];
    }
    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->items[] = $value;
            return;
        }
        $this->items[$this->requireKey($offset)] = $value;
    }
    public function offsetUnset(mixed $offset): void {
        unset($this->items[$this->requireKey($offset)]);
    }
}

$settings = new Settings();
$settings['optional'] = null;
var_dump($settings['optional']);
try { $settings['missing']; }
catch (OutOfBoundsException $error) { echo "Настройка не найдена\n"; }

NULL
Настройка не найдена

array_key_exists в getter позволяет хранить null, даже если offsetExists использует семантику isset. Возвращать null при любом пропуске тоже возможно, но тогда приложению труднее отличить два случая.

<?php
declare(strict_types=1);

class Settings implements ArrayAccess {
    private array $items = [];
    private function requireKey(mixed $offset): int|string {
        if (!is_int($offset) && !is_string($offset)) {
            throw new InvalidArgumentException('Ключ должен быть int или string');
        }
        return $offset;
    }
    public function offsetExists(mixed $offset): bool {
        return isset($this->items[$this->requireKey($offset)]);
    }
    public function &offsetGet(mixed $offset): mixed {
        $key = $this->requireKey($offset);
        if (!array_key_exists($key, $this->items)) {
            throw new OutOfBoundsException('Настройка не найдена');
        }
        return $this->items[$key];
    }
    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->items[] = $value;
            return;
        }
        $this->items[$this->requireKey($offset)] = $value;
    }
    public function offsetUnset(mixed $offset): void {
        unset($this->items[$this->requireKey($offset)]);
    }
}

$settings = new Settings();
$settings['attempts'] = 0;
++ $settings['attempts'];
echo $settings['attempts'], "\n";

1

Префиксный ++ изменяет значение, полученное по ссылке; setter здесь не выполняет проверку новой величины. Для ограниченного числа попыток лучше явный incrementAttempts, который не позволит обойти правило. Возврат ссылки — возможность, не обязательное улучшение.

<?php
declare(strict_types=1);

class Settings implements ArrayAccess {
    private array $items = [];
    private function requireKey(mixed $offset): int|string {
        if (!is_int($offset) && !is_string($offset)) {
            throw new InvalidArgumentException('Ключ должен быть int или string');
        }
        return $offset;
    }
    public function offsetExists(mixed $offset): bool {
        return isset($this->items[$this->requireKey($offset)]);
    }
    public function offsetGet(mixed $offset): mixed {
        $key = $this->requireKey($offset);
        if (!array_key_exists($key, $this->items)) {
            throw new OutOfBoundsException('Настройка не найдена');
        }
        return $this->items[$key];
    }
    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->items[] = $value;
            return;
        }
        $this->items[$this->requireKey($offset)] = $value;
    }
    public function offsetUnset(mixed $offset): void {
        unset($this->items[$this->requireKey($offset)]);
    }
}

$settings = new Settings();
$settings[] = 'Первая';
$settings[] = 'Вторая';
echo $settings[0], ':', $settings[1], "\n";

Первая:Вторая

Автоматические числовые ключи создаёт наш внутренний массив в ветке offset === null. Сам интерфейс не обязан поддерживать добавление: словарь фиксированных настроек может выбрасывать исключение.

<?php
declare(strict_types=1);

class Settings implements ArrayAccess {
    private array $items = [];
    private function requireKey(mixed $offset): int|string {
        if (!is_int($offset) && !is_string($offset)) {
            throw new InvalidArgumentException('Ключ должен быть int или string');
        }
        return $offset;
    }
    public function offsetExists(mixed $offset): bool {
        return isset($this->items[$this->requireKey($offset)]);
    }
    public function offsetGet(mixed $offset): mixed {
        $key = $this->requireKey($offset);
        if (!array_key_exists($key, $this->items)) {
            throw new OutOfBoundsException('Настройка не найдена');
        }
        return $this->items[$key];
    }
    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->items[] = $value;
            return;
        }
        $this->items[$this->requireKey($offset)] = $value;
    }
    public function offsetUnset(mixed $offset): void {
        unset($this->items[$this->requireKey($offset)]);
    }
}

$settings = new Settings();
$settings['theme'] = 'light';
try { $settings[new stdClass()] = 'dark'; }
catch (InvalidArgumentException $error) { echo "Неверный ключ\n"; }
echo $settings['theme'], "\n";

Неверный ключ
light

Наш контейнер принимает только int|string, объект-ключ отклонён. Явный $settings[null] тоже попадёт в ветку добавления и неотличим по параметру от []. Если вам нужно различать такие операции, используйте явные методы API.

<?php
declare(strict_types=1);

class Settings implements ArrayAccess {
    private array $items = [];
    private function requireKey(mixed $offset): int|string {
        if (!is_int($offset) && !is_string($offset)) {
            throw new InvalidArgumentException('Ключ должен быть int или string');
        }
        return $offset;
    }
    public function offsetExists(mixed $offset): bool {
        return isset($this->items[$this->requireKey($offset)]);
    }
    public function offsetGet(mixed $offset): mixed {
        $key = $this->requireKey($offset);
        if (!array_key_exists($key, $this->items)) {
            throw new OutOfBoundsException('Настройка не найдена');
        }
        return $this->items[$key];
    }
    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->items[] = $value;
            return;
        }
        $this->items[$this->requireKey($offset)] = $value;
    }
    public function offsetUnset(mixed $offset): void {
        unset($this->items[$this->requireKey($offset)]);
    }
}

$settings = new Settings();
$settings['theme'] = 'dark';
unset($settings['theme']);
var_dump(isset($settings['theme']));
unset($settings['missing']);
echo "Повторное удаление допустимо\n";

bool(false)
Повторное удаление допустимо

В этой реализации удаление отсутствующего корректного ключа безвредно. Другой контейнер может требовать ошибку или регистрировать событие удаления; согласуйте это с остальными методами.

<?php
declare(strict_types=1);

class Settings implements ArrayAccess {
    private array $items = [];
    private function requireKey(mixed $offset): int|string {
        if (!is_int($offset) && !is_string($offset)) {
            throw new InvalidArgumentException('Ключ должен быть int или string');
        }
        return $offset;
    }
    public function offsetExists(mixed $offset): bool {
        return isset($this->items[$this->requireKey($offset)]);
    }
    public function offsetGet(mixed $offset): mixed {
        $key = $this->requireKey($offset);
        if (!array_key_exists($key, $this->items)) {
            throw new OutOfBoundsException('Настройка не найдена');
        }
        return $this->items[$key];
    }
    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->items[] = $value;
            return;
        }
        $this->items[$this->requireKey($offset)] = $value;
    }
    public function offsetUnset(mixed $offset): void {
        unset($this->items[$this->requireKey($offset)]);
    }
}

$settings = new Settings();
$settings['theme'] = 'dark';
$also = $settings;
unset($settings);
echo $also['theme'], "\n";

dark

$also по-прежнему держит тот же экземпляр. offsetUnset вызывается для элемента через скобки, а не при уничтожении имени переменной. Историческое приведение (unset) также не вызывало его; само (unset) удалено в PHP 8 и не является современным способом очистки.

<?php
try { new InternalIterator(); }
catch (Error $error) { echo "Конструктор закрыт\n"; }

Конструктор закрыт

Error перехвачен только для демонстрации ограничения. В рабочем коде просто не вызывайте закрытый конструктор; он не принимает массив или источник в качестве обходного параметра.

<?php
declare(strict_types=1);

$tea = (object) ['title' => 'Чай'];
$coffee = (object) ['title' => 'Кофе'];
$labels = new WeakMap();
$labels[$tea] = 'Готов к публикации';
$labels[$coffee] = 'Нужна фотография';
$cursor = $labels->getIterator();
echo 'Тип курсора: ', get_class($cursor), "\n";
foreach ($cursor as $product => $label) { echo $product->title, ': ', $label, "\n"; }

Тип курсора: InternalIterator
Чай: Готов к публикации
Кофе: Нужна фотография

InternalIterator создаёт встроенный контейнер, здесь WeakMap. Пользовательский код получает готовый курсор через getIterator, а не new InternalIterator. Карта использует объект как ключ, поэтому в foreach product — сам объект товара.

<?php
declare(strict_types=1);

$first = new stdClass();
$second = new stdClass();
$map = new WeakMap();
$map[$first] = 'Первый';
$map[$second] = 'Второй';
$cursor = $map->getIterator();

$cursor->rewind();
if ($cursor->valid()) { echo $cursor->current(), "\n"; }

Первый

В примере порядок задаётся вставкой двух записей в WeakMap. Метод не отдаёт ключ и не меняет позицию.

<?php
$key = new stdClass();
$map = new WeakMap();
$map[$key] = null;
$cursor = $map->getIterator();
$cursor->rewind();
var_dump($cursor->valid(), $cursor->current());

bool(true)
NULL

В карте существует запись со значением null. Проверка через current на истинность потеряла бы её, а valid корректно сообщает наличие.

<?php
declare(strict_types=1);

$first = new stdClass();
$second = new stdClass();
$map = new WeakMap();
$map[$first] = 'Первый';
$map[$second] = 'Второй';
$cursor = $map->getIterator();

$cursor->rewind();
var_dump($cursor->key() === $first);
echo $cursor->current(), "\n";

bool(true)
Первый

Идентичность ключа полезна для поиска служебных сведений об объекте. Это не числовая позиция массива.

<?php
$key = new stdClass();
$map = new WeakMap();
$map[$key] = 'Подпись';
$cursor = $map->getIterator();
$cursor->rewind();
$savedKey = $cursor->key();
unset($cursor, $key);
echo count($map), "\n";
unset($savedKey);
echo count($map), "\n";

1
0

Полученный объект-ключ стал обычной сильной ссылкой в $savedKey. Диагностический сбор ключей способен продлить жизнь объектов и изменить ожидаемую очистку WeakMap.

<?php
declare(strict_types=1);

$first = new stdClass();
$second = new stdClass();
$map = new WeakMap();
$map[$first] = 'Первый';
$map[$second] = 'Второй';
$cursor = $map->getIterator();

$cursor->rewind();
$cursor->next();
if ($cursor->valid()) { echo $cursor->current(), "\n"; }

Второй

next управляет позицией того же курсора; он не возвращает второй элемент и не создаёт копию коллекции.

<?php
declare(strict_types=1);

$first = new stdClass();
$second = new stdClass();
$map = new WeakMap();
$map[$first] = 'Первый';
$map[$second] = 'Второй';
$cursor = $map->getIterator();

$cursor->rewind();
$cursor->next();
var_dump($cursor->valid());
$cursor->next();
var_dump($cursor->valid());

bool(true)
bool(false)

Не обращаемся к current после false. В производственном источнике ошибки чтения должны обрабатываться по договору контейнера, а не предположением, что любой next всегда успешен.

<?php
declare(strict_types=1);

$first = new stdClass();
$second = new stdClass();
$map = new WeakMap();
$map[$first] = 'Первый';
$map[$second] = 'Второй';
$cursor = $map->getIterator();

$cursor->rewind();
$cursor->next();
echo $cursor->current(), "\n";
$cursor->rewind();
echo $cursor->current(), "\n";

Второй
Первый

Работает для этой карты в памяти. Не переносите стоимость и повторяемость такого чтения на каждый потоковый источник.

<?php
declare(strict_types=1);

$first = new stdClass();
$second = new stdClass();
$map = new WeakMap();
$map[$first] = 'Первый';
$map[$second] = 'Второй';
$cursor = $map->getIterator();

$cursor->rewind();
$cursor->next();
foreach ($cursor as $value) { echo $value, "\n"; }

Первый
Второй

Сдвиг перед foreach не заставил цикл начать со второй записи. Для продолжения позиции используйте ручной цикл или подходящую оболочку NoRewindIterator.

<?php
$map = new WeakMap();
$cursor = $map->getIterator();
$cursor->rewind();
var_dump($cursor->valid());

bool(false)

Пустой источник не является ошибкой; интерфейс сообщает о нём обычным false.

<?php
declare(strict_types=1);

$tea = (object) ['title' => 'Чай'];
$coffee = (object) ['title' => 'Кофе'];
$labels = new WeakMap();
$labels[$tea] = 'Готов';
$labels[$coffee] = 'Черновик';
$cursor = $labels->getIterator();
$cursor->rewind();
while ($cursor->valid()) {
    echo $cursor->key()->title, ': ', $cursor->current(), "\n";
    $cursor->next();
}
echo "Все подписи просмотрены\n";

Чай: Готов
Кофе: Черновик
Все подписи просмотрены

valid проверяется перед каждым чтением. key возвращает объект товара, current — связанную подпись, next продвигает курсор. Важно не забыть next: иначе цикл будет повторять одну запись. Для простого вывода foreach короче.

<?php
declare(strict_types=1);

class SavedTask implements Serializable {
    public static int $constructed = 0;
    public function __construct(public string $label) {
        ++self::$constructed;
    }
    public function __serialize(): array {
        return ['label' => $this->label];
    }
    public function __unserialize(array $data): void {
        if (!isset($data['label']) || !is_string($data['label'])) {
            throw new UnexpectedValueException('Нет строковой метки');
        }
        $this->label = $data['label'];
    }
    public function serialize(): ?string {
        return json_encode($this->__serialize(), JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
    }
    public function unserialize(string $data): void {
        $decoded = json_decode($data, true, 512, JSON_THROW_ON_ERROR);
        if (!is_array($decoded)) {
            throw new UnexpectedValueException('Ожидался объект данных');
        }
        $this->__unserialize($decoded);
    }
}

$task = new SavedTask('Заказ');
echo $task->serialize(), "\n";
echo substr(serialize($task), 0, 2), "\n";

{"label":"Заказ"}
O:

Прямой метод всё ещё вызывается обычным способом. Глобальная функция предпочла __serialize, поэтому современная запись не содержит историческую C-оболочку. Сам интерфейс не требует JSON внутри: это выбранное нами содержимое.

<?php
class OptionalSnapshot implements Serializable {
    public function serialize(): ?string { return null; }
    public function unserialize(string $data): void {}
    public function __serialize(): array { return []; }
    public function __unserialize(array $data): void {}
}
$snapshot = new OptionalSnapshot();
var_dump($snapshot->serialize());
echo substr(serialize($snapshot), 0, 2), "\n";

NULL
O:

Этот диагностический класс показывает тип результата и приоритет magic-метода, не механизм хранения полезных данных. В новом коде оформляйте снимок через __serialize; наличие Serializable здесь нужно только для разбора исторического договора.

<?php
declare(strict_types=1);

class SavedTask implements Serializable {
    public static int $constructed = 0;
    public function __construct(public string $label) {
        ++self::$constructed;
    }
    public function __serialize(): array {
        return ['label' => $this->label];
    }
    public function __unserialize(array $data): void {
        if (!isset($data['label']) || !is_string($data['label'])) {
            throw new UnexpectedValueException('Нет строковой метки');
        }
        $this->label = $data['label'];
    }
    public function serialize(): ?string {
        return json_encode($this->__serialize(), JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
    }
    public function unserialize(string $data): void {
        $decoded = json_decode($data, true, 512, JSON_THROW_ON_ERROR);
        if (!is_array($decoded)) {
            throw new UnexpectedValueException('Ожидался объект данных');
        }
        $this->__unserialize($decoded);
    }
}

$task = new SavedTask('Старая метка');
$task->unserialize('{"label":"Новая метка"}');
echo $task->label, "\n";
echo SavedTask::$constructed, "\n";

Новая метка
1

Прямой метод не создаёт другой экземпляр. При обработке C-формата PHP выделяет объект и вызывает этот метод без обычного конструктора. В обоих случаях проверка данных остаётся вашей обязанностью.

<?php
declare(strict_types=1);

class SavedTask implements Serializable {
    public static int $constructed = 0;
    public function __construct(public string $label) {
        ++self::$constructed;
    }
    public function __serialize(): array {
        return ['label' => $this->label];
    }
    public function __unserialize(array $data): void {
        if (!isset($data['label']) || !is_string($data['label'])) {
            throw new UnexpectedValueException('Нет строковой метки');
        }
        $this->label = $data['label'];
    }
    public function serialize(): ?string {
        return json_encode($this->__serialize(), JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
    }
    public function unserialize(string $data): void {
        $decoded = json_decode($data, true, 512, JSON_THROW_ON_ERROR);
        if (!is_array($decoded)) {
            throw new UnexpectedValueException('Ожидался объект данных');
        }
        $this->__unserialize($decoded);
    }
}

$task = new SavedTask('Сохранить');
try { $task->unserialize('{"label":42}'); }
catch (UnexpectedValueException $error) { echo "Неверный формат метки\n"; }
echo $task->label, "\n";

Неверный формат метки
Сохранить

Проверка идёт до изменения свойства, поэтому старое состояние осталось. JSON_THROW_ON_ERROR отдельно отличает сломанный JSON от корректного JSON неправильной формы. Этот код не оправдывает unserialize внешнего пользовательского PHP-payload.

<?php
class ShipmentCode {
    public function __toString(): string { return 'SHIP-7'; }
}
$code = new ShipmentCode();
var_dump($code instanceof Stringable);
echo 'Отправление: ', $code, "\n";

bool(true)
Отправление: SHIP-7

Явное implements Stringable всё равно полезно как документация намерения. Метод не должен возвращать массив сведений: для него нужен другой протокол, например JsonSerializable.

<?php
declare(strict_types=1);
class InvalidLabel implements Stringable {
    public function __toString(): string { return 42; }
}
try { echo new InvalidLabel(); }
catch (TypeError $error) { echo "Нужен строковый результат\n"; }

Нужен строковый результат

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