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

<?php
declare(strict_types=1);

class B24Client
{
    public function listMethod(array $parameters, string $method): array { return []; }
}
$method = new ReflectionMethod(B24Client::class, 'listMethod');
foreach ($method->getParameters() as $parameter) {
    echo $method->getName(), ': ', $parameter->getName(),
        $parameter->isOptional() ? ' — необязательно' : ' — обязательно', "\n";
}

listMethod: parameters — обязательно
listMethod: method — обязательно

B24Client::class даёт строковое имя класса, а не экземпляр клиента. ReflectionMethod описывает выбранный метод. getParameters возвращает объекты описания его входов. Пустое тело listMethod здесь служит только декларацией исследуемого договора.

<?php
declare(strict_types=1);

class B24Client
{
    public function listMethod(array $parameters, string $method): array { return []; }
    public function portalName(): string { return 'Учебный портал'; }
    private function credentials(): string { return 'не выводить'; }
}
$class = new ReflectionClass(B24Client::class);
foreach ($class->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
    echo $method->getName(), '(', $method->getNumberOfRequiredParameters(), " обязательных)\n";
}

listMethod(2 обязательных)
portalName(0 обязательных)

IS_PUBLIC ограничивает список. Здесь количество нужно для практической подсказки обязательных входов; значения свойств не читаются и методы не запускаются. В большой библиотеке список может включать наследование, поэтому дополнительно исследуйте getDeclaringClass и документацию.

<?php
declare(strict_types=1);

#[Attribute(Attribute::TARGET_CLASS)]
class ReportTitle
{
    public function __construct(public string $text) {}
}
#[ReportTitle('Каталог товаров')]
class ProductReport {}
$class = new ReflectionClass(ProductReport::class);
$description = $class->getAttributes(ReportTitle::class)[0];
$title = $description->newInstance();
echo $title->text, "\n";

Каталог товаров

#[Attribute(...)] помечает ReportTitle как класс атрибута, TARGET_CLASS разрешает его у класса. #[ReportTitle(...)] сохраняет аргумент метки. getAttributes получает описание; newInstance создаёт объект ReportTitle и проверяет договор его применения. Существование метки и выполнение её конструктора — разные этапы.

<?php
declare(strict_types=1);

#[Attribute(Attribute::TARGET_METHOD)]
class Route
{
    public function __construct(public string $path) {}
}
class CatalogController
{
    #[Route('/products')]
    public function index(): string { return 'Каталог товаров'; }
}
$controller = new ReflectionClass(CatalogController::class);
foreach ($controller->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
    foreach ($method->getAttributes(Route::class) as $attribute) {
        $route = $attribute->newInstance();
        echo $route->path, ' → ', $method->getName(), "\n";
    }
}

/products → index

Это реально выполненное построение карты, не готовый HTTP-роутер. Метка описывает путь; диспетчер запроса ещё должен сопоставить HTTP-метод, проверить доступ и вызвать обработчик. При двух одинаковых путях карта должна сообщить конфликт, а не молча выбрать последний.

<?php
declare(strict_types=1);

#[Attribute(Attribute::TARGET_METHOD)]
class Route
{
    public function __construct(public string $path)
    {
        if (!str_starts_with($path, '/')) { throw new InvalidArgumentException('Путь должен начинаться с /'); }
    }
}
class BadController
{
    #[Route('products')]
    public function index(): void {}
}
$method = new ReflectionMethod(BadController::class, 'index');
try { $method->getAttributes(Route::class)[0]->newInstance(); }
catch (InvalidArgumentException $error) { echo 'Карта не собрана: ', $error->getMessage(), "\n"; }

Карта не собрана: Путь должен начинаться с /

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

<?php
declare(strict_types=1);

class Order
{
    public function __construct(public readonly string $id)
    {
        if ($id === '') { throw new InvalidArgumentException('Нужен номер'); }
    }
}
$description = new ReflectionClass(Order::class);
$order = $description->newInstanceWithoutConstructor();
try { echo 'Накладная для ', $order->id; }
catch (Error $error) { echo "не готова: номер не инициализирован\n"; }

Накладная для не готова: номер не инициализирован

newInstanceWithoutConstructor пропускает заполнение и проверки конструктора. Такой низкоуровневый приём нужен некоторым ORM и средствам восстановления, но они обязаны проверить структуру и заполнить состояние сами. Для обычной формы безопаснее явная фабрика из проверенных данных.

<?php
declare(strict_types=1);

#[Attribute(Attribute::TARGET_METHOD)]
class ExportHeading
{
    public const DEFAULT = 'Заказы';
    public static int $constructed = 0;

    public function __construct(public string $title)
    {
        self::$constructed++;
    }
}

class OrderDocument
{
    #[ExportHeading(title: ExportHeading::DEFAULT)]
    public function export(): void
    {
        throw new LogicException('Экспорт в этом опыте не вызывается');
    }
}

$method = new ReflectionMethod(OrderDocument::class, 'export');
$attribute = $method->getAttributes(ExportHeading::class)[0];
echo $attribute->getName(), "\n";
echo $attribute->getArguments()['title'], "\n";
echo 'Создано до newInstance: ', ExportHeading::$constructed, "\n";
$metadata = $attribute->newInstance();
echo $metadata->title, "\n";
echo 'Создано после newInstance: ', ExportHeading::$constructed, "\n";

ExportHeading
Заказы
Создано до newInstance: 0
Заказы
Создано после newInstance: 1

Title: — именованный аргумент конструктора атрибута; DEFAULT — константное выражение. Метод export не вызывается ни одним шагом. NewInstance запускает конструктор ExportHeading и проверяет возможность такого применения; это уже выполнение нашего кода метаданных.

<?php
declare(strict_types=1);

#[Attribute(Attribute::TARGET_METHOD)]
class ExportOnly
{
    public function __construct(public string $name) {}
}

#[ExportOnly('Ошибка места')]
class WrongExportTarget {}

class RepeatedExportTarget
{
    #[ExportOnly('Первая'), ExportOnly('Вторая')]
    public function run(): void {}
}

$targets = [
    new ReflectionClass(WrongExportTarget::class),
    new ReflectionMethod(RepeatedExportTarget::class, 'run'),
];
foreach ($targets as $target) {
    try {
        $target->getAttributes(ExportOnly::class)[0]->newInstance();
    } catch (Error $error) {
        echo "Некорректная схема атрибута отклонена\n";
    }
}

Некорректная схема атрибута отклонена
Некорректная схема атрибута отклонена

Пользовательский ExportOnly разрешён только у методов и не помечен IS_REPEATABLE. Описания синтаксически прочитались, но создание объектов метаданных остановлено. У ряда встроенных атрибутов PHP дополнительно проверяет правила уже при компиляции; не переносите время проверки этого опыта на все атрибуты.

<?php
declare(strict_types=1);

interface ExportHint
{
    public function text(): string;
}

#[Attribute(Attribute::TARGET_PROPERTY)]
class ColumnTitle implements ExportHint
{
    public function __construct(private string $value) {}
    public function text(): string { return 'Подпись: ' . $this->value; }
}

#[Attribute(Attribute::TARGET_PROPERTY)]
class ColumnUnit implements ExportHint
{
    public function __construct(private string $value) {}
    public function text(): string { return 'Единица: ' . $this->value; }
}

class ExportRow
{
    #[ColumnTitle('Вес'), ColumnUnit('кг')]
    public int $weight = 2;
}

$property = new ReflectionProperty(ExportRow::class, 'weight');
$attributes = $property->getAttributes(ExportHint::class, ReflectionAttribute::IS_INSTANCEOF);
foreach ($attributes as $attribute) {
    echo $attribute->newInstance()->text(), "\n";
}

Подпись: Вес
Единица: кг

Оба класса явно объявлены атрибутами и выполняют ExportHint. Повторяемости не требуется: на свойстве стоят разные классы по одному разу. Обработчик работает с известными разработчику метаданными, а не вызывает методы случайного класса из HTTP-ввода.

<?php
declare(strict_types=1);

function rejectDemoToken(#[SensitiveParameter] string $token): void
{
    throw new RuntimeException('Учебный отказ');
}

$previous = ini_set('zend.exception_ignore_args', '0');
try {
    try {
        rejectDemoToken('DEMO-NOT-A-REAL-TOKEN');
    } catch (RuntimeException $error) {
        $argument = $error->getTrace()[0]['args'][0];
        echo $argument instanceof SensitiveParameterValue
            ? "Аргумент трассировки скрыт оболочкой\n"
            : "Аргумент не скрыт\n";
    }
} finally {
    if ($previous !== false) {
        ini_set('zend.exception_ignore_args', $previous);
    }
}

Аргумент трассировки скрыт оболочкой

Только для опыта включены аргументы трассировки, затем настройка восстановлена. Используется вымышленная строка. Мы проверяем наличие SensitiveParameterValue, не пытаясь извлечь её содержимое. В рабочей среде отключённые аргументы трассировки могут быть предпочтительнее для всего приложения.

<?php
declare(strict_types=1);

function total(): int
{
    return 240;
}

#[Deprecated(message: 'Используйте total()', since: '2.0')]
function oldTotal(): int
{
    return total();
}

set_error_handler(function (int $level, string $message): bool {
    if ($level !== E_USER_DEPRECATED) {
        return false;
    }
    echo "Замечен устаревший вызов\n";
    return true;
});
try {
    echo oldTotal(), "\n";
} finally {
    restore_error_handler();
}

Замечен устаревший вызов
240

Since — версия нашей библиотеки, PHP не проверяет её смысл. Обработчик предупреждения намеренно локальный и выводит устойчивое сообщение для теста. В приложении deprecation обычно направляют в журнал и исправляют вызов, а не прячут глобальным отключением error_reporting.

<?php
declare(strict_types=1);

#[NoDiscard('Нужно проверить возможность отправки')]
function canShip(int $stock): bool
{
    return $stock > 0;
}

$warnings = 0;
set_error_handler(function (int $level, string $message) use (&$warnings): bool {
    if ($level !== E_USER_WARNING || !str_contains($message, 'canShip')) {
        return false;
    }
    $warnings++;
    return true;
});
try {
    canShip(0);
    $allowed = canShip(0);
    echo $allowed ? "Можно отправить\n" : "Отправка запрещена\n";
    (void) canShip(1);
} finally {
    restore_error_handler();
}
echo 'Потерянных результатов: ', $warnings, "\n";

Отправка запрещена
Потерянных результатов: 1

Первый результат не использован и выдаёт предупреждение. Второй участвует в решении. Последняя строка с (void) явно отбрасывает результат и подавляет предупреждение: это демонстрация синтаксиса PHP 8.5, а не совет игнорировать реальную проверку склада.

<?php
declare(strict_types=1);

#[AllowDynamicProperties]
class LegacyImportRow {}

$row = new LegacyImportRow();
$row->title = 'Чай';
$row->warehouse = 'A';
echo $row->title, ' / ', $row->warehouse, "\n";
echo property_exists($row, 'warehouse') ? "Поле создано\n" : "Поля нет\n";

Чай / A
Поле создано

Атрибут убирает deprecation именно создания динамических полей этого класса; это не проверка разрешённых имён. Свободная опечатка тоже будет принята. Для нового импорта обычно яснее массив со схемой или DTO с объявленными свойствами; stdClass уже допускает динамические свойства без такой пометки.

<?php
declare(strict_types=1);

class LegacyLineCount implements Countable
{
    #[ReturnTypeWillChange]
    public function count()
    {
        return count(['Чай', 'Чашка']);
    }
}

class LineCount implements Countable
{
    public function count(): int
    {
        return count(['Чай', 'Чашка']);
    }
}

echo 'Старый договор: ', count(new LegacyLineCount()), " строки\n";
echo 'Современный договор: ', count(new LineCount()), " строки\n";

Старый договор: 2 строки
Современный договор: 2 строки

Обе реализации считают один учебный список. ReturnTypeWillChange временно подавляет предупреждение о tentative return type встроенного Countable; он не меняет результат. Для PHP 8.2+ следует объявить count(): int. В пользовательском наследовании атрибут не разрешает несовместимую сигнатуру.

<?php
declare(strict_types=1);

class ExportSettings
{
    public string $format = 'csv';
}

class JsonExportSettings extends ExportSettings
{
    #[Override]
    public string $format = 'json';
}

echo (new JsonExportSettings())->format, "\n";

json

Если написать другое имя свойства, PHP обнаружит отсутствие соответствующего объявления родителя при компиляции. В этом опыте тип и видимость совместимы. Override не делает несовместимое изменение типа допустимым и не означает, что значение readonly разрешено менять.

<?php
declare(strict_types=1);

class CompatibilityProbe
{
    #[DelayedTargetValidation]
    #[Override]
    public const FORMAT = 'csv';
}

echo CompatibilityProbe::FORMAT, "\n";
$constant = new ReflectionClassConstant(CompatibilityProbe::class, 'FORMAT');
try {
    $constant->getAttributes(Override::class)[0]->newInstance();
} catch (Error $error) {
    echo "Override нельзя применять к этой константе\n";
}

csv
Override нельзя применять к этой константе

Это намеренно неправильное место Override, изолированное для исследования механизма. Объявление допускается благодаря DelayedTargetValidation, но Reflection всё равно отвергает неподдерживаемую цель. Такой код не является полезной настройкой формата экспорта — он показывает границу совместимости.

<?php
declare(strict_types=1);

class QuantityRange
{
    public static int $created = 0;
    public function __construct(public int $min, public int $max)
    {
        self::$created++;
    }
    public function allows(int $quantity): bool
    {
        return $quantity >= $this->min && $quantity <= $this->max;
    }
}

#[Attribute(Attribute::TARGET_PROPERTY)]
class QuantityCheck
{
    public function __construct(public QuantityRange $range) {}
}

class ImportLine
{
    #[QuantityCheck(new QuantityRange(1, 10))]
    public int $quantity = 3;
}

$description = (new ReflectionProperty(ImportLine::class, 'quantity'))
    ->getAttributes(QuantityCheck::class)[0];
echo 'До чтения: ', QuantityRange::$created, "\n";
$first = $description->getArguments()[0];
$second = $description->getArguments()[0];
echo 'После двух чтений: ', QuantityRange::$created, "\n";
echo $first === $second ? "Общий объект\n" : "Два разных правила\n";
$check = $description->newInstance();
echo 'После newInstance: ', QuantityRange::$created, "\n";
echo $check->range->allows(3) ? "Количество 3 допустимо\n" : "Ошибка\n";
echo $check->range->allows(11) ? "Принято\n" : "Количество 11 отклонено\n";

До чтения: 0
После двух чтений: 2
Два разных правила
После newInstance: 3
Количество 3 допустимо
Количество 11 отклонено

GetAttributes возвращает описание. GetArguments уже вычисляет выражения аргументов, поэтому new QuantityRange выполняется при каждом чтении. NewInstance создаёт QuantityCheck с новым аргументом. Нельзя считать любое чтение Reflection лишённым побочных эффектов.

<?php
declare(strict_types=1);

namespace LibraryMeta {
    #[\Attribute(\Attribute::TARGET_PROPERTY)]
    class Column
    {
        public function __construct(public string $title) {}
    }
}

namespace ExportArea {
    use LibraryMeta\Column as Heading;
    use LibraryMeta as Meta;

    class ItemRow
    {
        #[Heading('Артикул')]
        public string $sku = 'TEA-1';
        #[Meta\Column('Название')]
        public string $title = 'Чай';
        #[\LibraryMeta\Column('Остаток')]
        public int $stock = 3;
        #[Column('Нет такого класса в ExportArea')]
        public string $mistake = '';
    }

    foreach (['sku', 'title', 'stock'] as $field) {
        $description = (new \ReflectionProperty(ItemRow::class, $field))->getAttributes()[0];
        echo $description->getName(), ': ', $description->newInstance()->title, "\n";
    }
    try {
        (new \ReflectionProperty(ItemRow::class, 'mistake'))->getAttributes()[0]->newInstance();
    } catch (\Error $error) {
        echo "Для Column не указан нужный use\n";
    }
}

LibraryMeta\Column: Артикул
LibraryMeta\Column: Название
LibraryMeta\Column: Остаток
Для Column не указан нужный use

Обе namespace-группы находятся в одном самостоятельном example.php. Фигурные скобки ограничивают область каждого пространства. Начальный слеш у Attribute/ReflectionProperty/Error выбирает встроенные глобальные классы. Неверное имя можно прочитать как описание; ошибка возникла при попытке создать его объект.

<?php
declare(strict_types=1);

#[Attribute(Attribute::TARGET_ALL | Attribute::IS_REPEATABLE)]
class SchemaLabel
{
    public function __construct(public string $text) {}
}

#[SchemaLabel('глобальная константа')]
const EXPORT_SCHEMA_VERSION = 2;

#[SchemaLabel('функция')]
function prepareExport(#[SchemaLabel('параметр')] int $limit): int
{
    return $limit;
}

#[SchemaLabel('класс')]
#[SchemaLabel('схема документа')]
class ExportSchema
{
    #[SchemaLabel('свойство')]
    public string $title = 'Заказы';
    #[SchemaLabel('константа класса')]
    public const FORMAT = 'csv';
    #[SchemaLabel('метод')]
    public function build(): void {}
}

$targets = [
    new ReflectionClass(ExportSchema::class),
    new ReflectionFunction('prepareExport'),
    new ReflectionMethod(ExportSchema::class, 'build'),
    new ReflectionProperty(ExportSchema::class, 'title'),
    new ReflectionClassConstant(ExportSchema::class, 'FORMAT'),
    new ReflectionParameter('prepareExport', 'limit'),
    new ReflectionConstant('EXPORT_SCHEMA_VERSION'),
];
foreach ($targets as $target) {
    echo $target->getAttributes(SchemaLabel::class)[0]->newInstance()->text, "\n";
}
$definition = (new ReflectionClass(SchemaLabel::class))->getAttributes(Attribute::class)[0]->newInstance();
echo ($definition->flags & Attribute::TARGET_CONSTANT) !== 0 ? "Глобальный const разрешён\n" : "Запрещён\n";
echo count((new ReflectionClass(ExportSchema::class))->getAttributes(SchemaLabel::class)), " метки класса\n";

класс
функция
метод
свойство
константа класса
параметр
глобальная константа
Глобальный const разрешён
2 метки класса

Массив targets здесь только собирает семь описаний для общего цикла. Getter getAttributes на каждом описании выполняет одну понятную задачу. Маску разрешённых мест читаем у #[Attribute] класса SchemaLabel; это не то же самое, что getTarget у конкретного применения. Две метки на ExportSchema допустимы благодаря IS_REPEATABLE.

<?php
declare(strict_types=1);

#[Attribute(Attribute::TARGET_PARAMETER | Attribute::TARGET_PROPERTY)]
class FieldLabel
{
    public function __construct(public string $title) {}
}

class ProductInput
{
    public function __construct(#[FieldLabel('Артикул')] public string $sku) {}
}

$parameter = new ReflectionParameter([ProductInput::class, '__construct'], 'sku');
$property = new ReflectionProperty(ProductInput::class, 'sku');
echo 'Параметр: ', $parameter->getAttributes(FieldLabel::class)[0]->newInstance()->title, "\n";
echo 'Свойство: ', $property->getAttributes(FieldLabel::class)[0]->newInstance()->title, "\n";

#[Attribute(Attribute::TARGET_PROPERTY)]
class StoredField {}
class StorageInput
{
    public function __construct(#[StoredField] public string $sku) {}
}

(new ReflectionProperty(StorageInput::class, 'sku'))->getAttributes(StoredField::class)[0]->newInstance();
echo "Метка свойства создана\n";
try {
    (new ReflectionParameter([StorageInput::class, '__construct'], 'sku'))
        ->getAttributes(StoredField::class)[0]->newInstance();
} catch (Error $error) {
    echo "Та же метка не разрешена для параметра\n";
}

Параметр: Артикул
Свойство: Артикул
Метка свойства создана
Та же метка не разрешена для параметра

В обоих случаях описания скопированы. У FieldLabel разрешены обе цели; у StoredField только свойство, поэтому ошибка появляется при newInstance описания параметра. Это не повторяемость: IS_REPEATABLE относится к нескольким применениям на одной цели, а здесь цели две.

<?php
declare(strict_types=1);

#[Deprecated(message: 'Объявите exportName() в своём классе', since: '2.0')]
trait LegacyExportName
{
    public function exportName(): string
    {
        return 'orders.csv';
    }
}

$notices = 0;
set_error_handler(function (int $level, string $message) use (&$notices): bool {
    if ($level !== E_USER_DEPRECATED || !str_contains($message, 'LegacyExportName')) {
        return false;
    }
    $notices++;
    return true;
});
try {
    require __DIR__ . '/old-export.php';
} finally {
    restore_error_handler();
}
echo 'Предупреждений при подключении: ', $notices, "\n";
echo (new OldExport())->exportName(), "\n";

class CurrentExport
{
    public function exportName(): string
    {
        return 'orders.csv';
    }
}
echo (new CurrentExport())->exportName(), "\n";

Предупреждений при подключении: 1
orders.csv
orders.csv

Демо не записывает CSV: метод возвращает имя будущего файла. Предупреждение возникает при применении трейта, не при каждом вызове exportName. Обработчик перехватывает только известное deprecation и обязательно восстанавливается.

<?php
declare(strict_types=1);

const CURRENT_IMPORT_BATCH = 50;
#[Deprecated(message: 'Используйте CURRENT_IMPORT_BATCH', since: '2.0')]
const LEGACY_IMPORT_BATCH = 20;

$notices = 0;
set_error_handler(function (int $level, string $message) use (&$notices): bool {
    if ($level !== E_USER_DEPRECATED || !str_contains($message, 'LEGACY_IMPORT_BATCH')) {
        return false;
    }
    $notices++;
    return true;
});
try {
    echo defined('LEGACY_IMPORT_BATCH') ? "Старое имя пока существует\n" : "Имя удалено\n";
    echo 'Старый пакет: ', constant('LEGACY_IMPORT_BATCH'), "\n";
} finally {
    restore_error_handler();
}
echo 'Событий устаревшего чтения: ', $notices, "\n";
echo 'Новый пакет: ', CURRENT_IMPORT_BATCH, "\n";

Старое имя пока существует
Старый пакет: 20
Событий устаревшего чтения: 1
Новый пакет: 50

Defined проверяет наличие; чтение constant использует значение и выдаёт deprecation. Новый размер выбран в условии задачи: Deprecated не меняет 20 на 50. Изменение размера реального импорта надо отдельно проверить на лимитах сервиса и памяти.