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

<?php
#[Attribute(Attribute::TARGET_FUNCTION)]
class Route {
    public string $path;
    public function __construct(string $path) { $this->path = $path; }
}
#[Route('/catalog')]
function catalog(): string { return 'Каталог'; }
$reflection = new ReflectionFunction('catalog');
$attribute = $reflection->getAttributes(Route::class)[0]->newInstance();
echo $attribute->path, "\n";
echo catalog(), "\n";

/catalog
Каталог

Reflection отдельно прочитал метаданные, а обычный catalog() отдельно выполнил функцию. Скобки [0] выбирают первую найденную пометку; в общем загрузчике проверьте наличие и допустимое количество. Не создавайте атрибуты из непроверенного кода: их конструкторы выполняются.

<?php
#[Attribute(Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
class Tag {
    public function __construct(public string $name) {}
}
#[Tag('catalog'), Tag('public')]
function listProducts(): void {}
foreach ((new ReflectionFunction('listProducts'))->getAttributes(Tag::class) as $metadata) {
    echo $metadata->newInstance()->name, "\n";
}

catalog
public

public string $name в параметре конструктора одновременно объявляет и заполняет свойство. В реальном приложении метки могут выбрать обработчики кеширования или документации. Пока вы не написали обработчик, это только данные.

<?php
#[Attribute(Attribute::TARGET_FUNCTION)]
class FunctionTag {}
#[FunctionTag]
class Product {}
$metadata = (new ReflectionClass(Product::class))->getAttributes(FunctionTag::class)[0];
echo $metadata->getName(), "\n";
try { $metadata->newInstance(); }
catch (Error $error) { echo "Неподходящая цель\n"; }

FunctionTag
Неподходящая цель

Чтение имени атрибута и создание его объекта — разные операции. Поэтому система, которая проверяет конфигурацию при запуске, должна проверять не только наличие метки, но и корректность её использования.

<?php
#[\AllowDynamicProperties]
class FlexibleRecord {}
class ImportedRecord extends FlexibleRecord {}
$record = new ImportedRecord();
$record->externalCode = 'EXT-7';
echo $record->externalCode, "\n";

EXT-7

Наследуется эффект разрешения динамических свойств, а не общая способность всех атрибутов наследоваться. В namespace обратный слеш у \AllowDynamicProperties выбирает именно встроенный класс.

<?php
class Order {
    public string $status = 'new';
}
$order = new Order();
$order->status = 'paid';
echo $order->status, "\n";

paid

Для заранее определённого статуса отдельный атрибут не нужен. Тип string ограничивает тип значения, но не набор допустимых статусов: для этого можно использовать enum из главы о перечислениях.

<?php
interface Sender { public function send(string $text): string; }
class ConsoleSender implements Sender {
    #[\Override]
    public function send(string $text): string { return 'Отправлено: ' . $text; }
}
echo (new ConsoleSender())->send('Заказ готов'), "\n";

Отправлено: Заказ готов

Если назвать метод snd, требуемый send не будет реализован; если пометить лишний метод без совпадения, Override тоже обнаружит ошибку. Компиляционная ошибка такого объявления не является обычным возвращаемым результатом вызова.

<?php
class BaseView { public string $title = 'Страница'; }
class CatalogView extends BaseView {
    #[\Override]
    public string $title = 'Каталог';
}
echo (new CatalogView())->title, "\n";

Каталог

Override доступен для методов с PHP 8.3, для свойств — с PHP 8.5. Он не применяется к __construct, который имеет особые правила сигнатуры. Пометка на совершенно новом свойстве не подходит: требуется совпадение в родительском/интерфейсном договоре.

<?php
set_error_handler(function (int $level, string $message): bool {
    if ($level !== E_USER_DEPRECATED) { return false; }
    echo "Устаревший вызов\n";
    return true;
});
#[\Deprecated(message: 'Используйте currentPrice()', since: '2.0')]
function oldPrice(): int { return 100; }
echo oldPrice(), "\n";
restore_error_handler();

Устаревший вызов
100

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

<?php
set_error_handler(function (int $level): bool {
    if ($level !== E_USER_DEPRECATED) { return false; }
    echo "Старое имя константы\n";
    return true;
});
#[\Deprecated('Используйте API_TIMEOUT', '2.0')]
const OLD_TIMEOUT = 10;
echo OLD_TIMEOUT, "\n";
restore_error_handler();

Старое имя константы
10

Атрибут записан при объявлении const, а предупреждение связано с использованием. Для константы, создаваемой обычным вызовом define, такой синтаксис пометки не применяется.

<?php
declare(strict_types=1);

set_error_handler(function (int $level): bool {
    if ($level !== E_USER_WARNING) { return false; }
    echo "Не потеряйте список отклонённых заказов\n";
    return true;
});
#[NoDiscard('Проверьте отклонённые элементы')]
function rejectedItems(): array { return ['Заказ A-42: неизвестный артикул']; }
rejectedItems();
$rejected = rejectedItems();
foreach ($rejected as $message) { echo $message, "\n"; }
restore_error_handler();

Не потеряйте список отклонённых заказов
Заказ A-42: неизвестный артикул

PHP 8.5+. Первый вызов намеренно выбрасывает важный результат, и NoDiscard предупреждает. Второй сохраняет список и даёт полезное сообщение для исправления импорта. Атрибут не заставляет программу правильно обработать список: присвоение само по себе тоже ещё не отчёт об ошибках.

<?php
declare(strict_types=1);

#[NoDiscard]
function replaceCaption(array &$preview, string $caption): string
{
    $previous = $preview['caption'];
    $preview['caption'] = $caption;
    return $previous;
}
$preview = ['caption' => 'Черновик'];
(void) replaceCaption($preview, 'Готовый отчёт');
echo $preview['caption'], "\n";
$_ = replaceCaption($preview, 'Отчёт за октябрь');
echo $preview['caption'], "\n";

Готовый отчёт
Отчёт за октябрь

Функция заменяет подпись и возвращает прежний текст. В первом вызове (void) явно отбрасывает прошлую подпись; во втором результат присвоен переменной $_ и потому считается использованным. $_ — обычное имя, не встроенная защита. Так нельзя обосновывать игнорирование списка ошибок: сначала определите, действительно ли возвращённые данные не нужны.

<?php
declare(strict_types=1);

class LegacyBasket implements Countable
{
    private array $items = ['Чай', 'Кофе'];
    #[ReturnTypeWillChange]
    public function count() { return count($this->items); }
}
echo 'В старой корзине: ', count(new LegacyBasket()), " позиции\n";

В старой корзине: 2 позиции

ReturnTypeWillChange временно подавляет deprecation из-за отсутствующего ожидаемого типа результата внутреннего договора. Он не исправляет ошибочный алгоритм и не обещает будущую совместимость. Следующий пример показывает конечную цель миграции.

<?php
declare(strict_types=1);

class Basket implements Countable
{
    private array $items = ['Чай', 'Кофе'];
    public function count(): int { return count($this->items); }
}
echo 'В новой корзине: ', count(new Basket()), " позиции\n";

В новой корзине: 2 позиции

Добавлен совместимый : int, поэтому временный атрибут не нужен. Число по-прежнему обозначает позиции, а не суммарные единицы. Миграция сохраняет видимый результат и делает договор проверяемым.

<?php
ini_set('zend.exception_ignore_args', '0');
function authenticate(#[\SensitiveParameter] string $password): void {
    throw new RuntimeException('Вход не выполнен');
}
try { authenticate('demo-secret'); }
catch (RuntimeException $error) {
    $argument = $error->getTrace()[0]['args'][0];
    echo get_class($argument), "\n";
    var_dump($argument->__debugInfo());
}

SensitiveParameterValue
array(0) {
}

Настройка включает аргументы только внутри самостоятельного опыта, чтобы показать обёртку. При zend.exception_ignore_args=1 аргументы исключения вообще не сохраняются. Во многих рабочих окружениях это подходящий более общий способ не включать их в диагностику.

<?php
declare(strict_types=1);

function tokenStatus(#[SensitiveParameter] string $token): string
{
    return $token === 'demo-token' ? 'Учебный токен принят' : 'Учебный токен отклонён';
}
echo tokenStatus('demo-token'), "\n";
echo tokenStatus('other'), "\n";

Учебный токен принят
Учебный токен отклонён

SensitiveParameter меняет представление аргумента в трассировке, но внутри функции token остаётся обычной строкой. Это демонстрационное сравнение, не готовая авторизация. Не выводите и не логируйте сам токен; атрибут не защитит от вашего echo или записи в файл.

<?php
class Feature {
    #[\DelayedTargetValidation]
    #[\Override]
    public const LABEL = 'Каталог';
}
echo Feature::LABEL, "\n";
$reflection = new ReflectionClassConstant(Feature::class, 'LABEL');
$metadata = $reflection->getAttributes(Override::class)[0];
try { $metadata->newInstance(); }
catch (Error $error) { echo "Override не допускает эту цель\n"; }

Каталог
Override не допускает эту цель

В PHP 8.5 Override допускает метод/свойство, но не константу класса. Отложенная проверка позволила загрузить объявление, затем newInstance обнаружил несоответствие. Это контролируемая иллюстрация, а не рекомендуемое оформление константы.