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

<?php
declare(strict_types=1);

class Stock
{
    private int $quantity = 3;
    public function remaining(): int
    {
        return $this->quantity;
    }
}
$stock = new Stock();
echo 'Осталось: ', $stock->remaining(), "\n";
try {
    $stock->quantity = -7;
} catch (Error $error) {
    echo "Прямая запись закрыта\n";
}

Осталось: 3
Прямая запись закрыта

private допускает доступ внутри объявившего класса. public делает remaining доступным вызывающему коду. Это правило организации программы; оно не шифрует данные и не заменяет авторизацию пользователя.

<?php
declare(strict_types=1);

class Stock
{
    public function __construct(private int $quantity)
    {
        if ($quantity < 0) {
            throw new InvalidArgumentException('Остаток должен быть неотрицательным');
        }
    }
    public function reserve(int $amount): void
    {
        if ($amount < 1 || $amount > $this->quantity) {
            throw new DomainException('Недостаточно товара или неверное количество');
        }
        $this->quantity -= $amount;
    }
    public function remaining(): int { return $this->quantity; }
}
$stock = new Stock(3);
$stock->reserve(2);
echo 'Осталось: ', $stock->remaining(), "\n";
try {
    $stock->reserve(2);
} catch (DomainException $error) {
    echo $error->getMessage(), "\n";
}
echo 'После отказа: ', $stock->remaining(), "\n";

Осталось: 1
Недостаточно товара или неверное количество
После отказа: 1

amount — сколько запрашивают сейчас; quantity — сохранённый остаток. || означает «или». -= вычитает и сохраняет новое значение. Проверка стоит перед изменением, поэтому отказ не оставляет частично изменённый остаток.

<?php
declare(strict_types=1);

class ProductCard
{
    public string $title = 'Чай' {
        set {
            $value = trim($value);
            if ($value === '') {
                throw new InvalidArgumentException('Название не должно быть пустым');
            }
            $this->title = $value;
        }
    }
}
$card = new ProductCard();
$card->title = '  Чёрный чай  ';
echo $card->title, "\n";
try {
    $card->title = '';
} catch (InvalidArgumentException $error) {
    echo $error->getMessage(), "\n";
}

Чёрный чай
Название не должно быть пустым

PHP 8.4+. Неявный $value — новое значение, пришедшее в set. Внутри собственного хука $this->title обращается к хранилищу свойства без повторного вызова этого же хука. В PHP 8.2–8.3 используйте private-поле и rename(). Начальное значение задавайте корректным: значение по умолчанию не является обычной внешней записью через set.

<?php
declare(strict_types=1);

class Stock
{
    public private(set) int $quantity = 3;
    public function reserveOne(): void
    {
        if ($this->quantity < 1) {
            throw new DomainException('Товар закончился');
        }
        --$this->quantity;
    }
}
$stock = new Stock();
$stock->reserveOne();
echo 'Осталось: ', $stock->quantity, "\n";

Осталось: 2

Первое public относится к чтению, private(set) — к записи. -- уменьшает число на один; эта запись разрешена внутри Stock. Видимость записи не может быть шире чтения. private(set)-свойство не допускает переопределения в потомке: оно неявно final.

<?php
declare(strict_types=1);

class BasketLine
{
    public int $total {
        get => $this->price * $this->quantity;
    }

    public function __construct(public int $price, public int $quantity) {}
}

$line = new BasketLine(120, 2);
echo $line->total, "\n";
$line->quantity = 3;
echo $line->total, "\n";
try {
    $line->total = 1;
} catch (Error $error) {
    echo "Итог нельзя присвоить напрямую\n";
}

240
360
Итог нельзя присвоить напрямую

Числа маленькие и заранее известны: пример объясняет механизм, а не проверку денег. Для внешнего ввода нужны ограничения цены, количества и переполнения. У get нет обращения к собственному $this->total — здесь нет backing storage, и отсутствующий set запрещает запись.

<?php
declare(strict_types=1);

class NotificationFlag
{
    public bool $enabled = false {
        set(bool|string $value) {
            if (is_string($value)) {
                $value = match ($value) {
                    'yes' => true,
                    'no' => false,
                    default => throw new InvalidArgumentException('Ожидаются yes или no'),
                };
            }
            $this->enabled = $value;
        }
    }
}

$flag = new NotificationFlag();
$flag->enabled = 'yes';
echo $flag->enabled ? "Уведомления включены\n" : "Уведомления выключены\n";
$flag->enabled = false;
try {
    $flag->enabled = 'perhaps';
} catch (InvalidArgumentException $error) {
    echo "Неизвестный вариант отклонён\n";
}
echo $flag->enabled ? "Уведомления включены\n" : "Уведомления выключены\n";

Уведомления включены
Неизвестный вариант отклонён
Уведомления выключены

Тип свойства ограничивает хранение, тип параметра set — вход операции. Начальное false известно заранее. Хук проверяет новое значение до присваивания; ошибка не меняет прежнее false. Случай с perhaps не превращается в true, как при неосмотрительном приведении любой непустой строки к bool.

<?php
declare(strict_types=1);

class ImportedRows
{
    public private(set) static int $accepted = 0;

    public static function accept(): void
    {
        self::$accepted++;
    }
}

ImportedRows::accept();
ImportedRows::accept();
echo 'Принято: ', ImportedRows::$accepted, "\n";
try {
    ImportedRows::$accepted = 0;
} catch (Error $error) {
    echo "Снаружи запись запрещена\n";
}

Принято: 2
Снаружи запись запрещена

Public относится к чтению, private(set) — к изменению из объявившего класса. Static означает общую ячейку класса в текущем процессе. Это не общий счётчик всех веб-запросов: для него понадобятся хранилище и согласованное атомарное обновление.

<?php
declare(strict_types=1);

class CurrencyAmount
{
    public function __construct(private int $minor, private string $currency) {}

    public function sameCurrency(self $other): bool
    {
        return $this->currency === $other->currency;
    }
}

$first = new CurrencyAmount(120, 'RUB');
$second = new CurrencyAmount(240, 'RUB');
$third = new CurrencyAmount(100, 'EUR');
echo $first->sameCurrency($second) ? "Одна валюта\n" : "Разные валюты\n";
echo $first->sameCurrency($third) ? "Одна валюта\n" : "Разные валюты\n";

Одна валюта
Разные валюты

Self в параметре означает экземпляр текущего класса или допустимого потомка. $this — первая сумма, $other — переданная. Оба закрытых currency читаются внутри области CurrencyAmount. Числа и валюты известны заранее; полноценный Money с проверкой и операциями разобран отдельно.

<?php
declare(strict_types=1);

class NormalizedSku
{
    public string $sku {
        final get => $this->sku;
        set => strtoupper(trim($value));
    }
}

class VendorSku extends NormalizedSku
{
    public string $sku {
        set {
            if (!str_starts_with($value, 'v-')) {
                throw new InvalidArgumentException('Требуется префикс v-');
            }
            parent::$sku::set($value);
        }
    }
}

$item = new VendorSku();
$item->sku = 'v-42';
echo $item->sku, "\n";
try {
    $item->sku = 'other-42';
} catch (InvalidArgumentException $error) {
    echo "Чужой префикс отклонён\n";
}
echo $item->sku, "\n";

V-42
Чужой префикс отклонён
V-42

Set в дочернем классе заменяет только set, а get наследуется. Final у get запрещает заменить конкретно чтение; это уже, чем final всего свойства. Проверка префикса намеренно требует вход v- в нижнем регистре, после чего родитель сохраняет верхний регистр. Это договор учебного поставщика, не универсальное правило всех SKU.

<?php
declare(strict_types=1);

class SelectedTitles
{
    public array $items = [] {
        set {
            foreach ($value as $title) {
                if (!is_string($title) || $title === '') {
                    throw new InvalidArgumentException('Нужны непустые названия');
                }
            }
            $this->items = $value;
        }
    }
}

$selection = new SelectedTitles();
$selection->items = ['Чай'];
try {
    $selection->items[] = 'Кофе';
} catch (Error $error) {
    echo "Прямое изменение элемента запрещено\n";
}
$updated = $selection->items;
$updated[] = 'Кофе';
$selection->items = $updated;
echo implode(', ', $selection->items), "\n";

Прямое изменение элемента запрещено
Чай, Кофе

Чтение массива в updated получает обычное значение; оно не является ссылкой на поле. Мы меняем локальный набор и затем присваиваем весь результат, поэтому set снова проверяет каждый элемент. Для больших наборов это не обещание дешёвого изменения: приходится учитывать копирование и повторный полный обход.

<?php
declare(strict_types=1);

class ExportTitle
{
    public string $title = 'tea' {
        get => strtoupper($this->title);
    }
}

$item = new ExportTitle();
echo $item->title, "\n";
echo ((array) $item)['title'], "\n";
echo json_encode($item, JSON_THROW_ON_ERROR), "\n";
$saved = serialize($item);
$restored = unserialize($saved, ['allowed_classes' => [ExportTitle::class]]);
if (!$restored instanceof ExportTitle) {
    throw new UnexpectedValueException('Ожидался ExportTitle');
}
echo ((array) $restored)['title'], "\n";

TEA
tea
{"title":"TEA"}
tea

Get вычисляет TEA, а в backing storage остаётся tea. Приведение к массиву показывает сырое значение. Json_encode читает публичное свойство через get. Обычный serialize без собственных магических методов сохраняет сырой вариант; круговое восстановление использует только нашу доверенную строку.

<?php
declare(strict_types=1);

class BaseImport
{
    public protected(set) string $status = 'new';
}

class CrmImport extends BaseImport
{
    public function finish(): void
    {
        $this->status = 'done';
    }
}

class EditableImport extends BaseImport
{
    public string $status = 'new';
}

$import = new CrmImport();
$import->finish();
echo $import->status, "\n";
try {
    $import->status = 'new';
} catch (Error $error) {
    echo "Внешняя запись запрещена\n";
}
$editable = new EditableImport();
$editable->status = 'review';
echo $editable->status, "\n";

done
Внешняя запись запрещена
review

EditableImport сознательно расширяет запись до public: права можно сделать доступнее, если свойство не final. Это не автоматическое свойство наследования; собственное объявление меняет договор. Сужать доступные права потомок не должен. Для неизменяемого публичного контракта выбирайте final или другую модель расширения.

<?php
declare(strict_types=1);

class BaseReceipt
{
    public readonly string $number;
}

class ImportedReceipt extends BaseReceipt
{
    public function __construct(string $number)
    {
        $this->number = $number;
    }

    public function replace(string $number): void
    {
        $this->number = $number;
    }
}

$receipt = new ImportedReceipt('INV-42');
echo $receipt->number, "\n";
try {
    $receipt->replace('INV-43');
} catch (Error $error) {
    echo "Readonly уже инициализировано\n";
}

INV-42
Readonly уже инициализировано

С PHP 8.4 неявная область записи readonly стала protected(set), поэтому потомок может выполнить первую инициализацию. После неё запрет повторного присваивания остаётся. В PHP 8.2–8.3 этот путь нужно организовать через конструктор или метод объявившего поле родителя.

<?php
declare(strict_types=1);

class BackedTags
{
    public array $tags = ['php'] {
        &get { return $this->tags; }
    }
}

class VirtualTags
{
    private array $stored = ['php'];

    public array $tags {
        &get { return $this->stored; }
    }

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

$backed = new BackedTags();
$backed->tags[] = 'web';
echo implode(', ', $backed->tags), "\n";
$virtual = new VirtualTags();
$virtual->tags[] = 'api';
echo implode(', ', $virtual->tags), "\n";
echo 'Внутри virtual: ', $virtual->count(), "\n";

php, web
php, api
Внутри virtual: 2

Первый хук ссылается на собственное $this->tags: у свойства есть backing storage. Второй отдаёт ссылку на другое поле stored, поэтому tags виртуальное, но изменение всё равно достигает объекта. Место хранения определяется реализацией, а не одним наличием имени tags.