Атрибуты PHP были представлены в PHP 8.0. Эта версия стала важной вехой в развитии языка, принеся с собой несколько новых функций и улучшений, включая введение атрибутов для добавления метаданных в объявления кода.

Впервые мне пришлось иметь дело с атрибутами из-за проблемы в PHP-библиотеке Инспектора. Проверьте на GitHub. Прежде чем углубиться в решение, давайте рассмотрим, что такое атрибуты и как их можно использовать в вашем PHP-коде.

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

Помните: атрибуты не действуют во время выполнения. Они будут доступны в API-интерфейсах Reflection, чтобы ваше приложение знало о том, что вы хотите запустить, на основе атрибутов, прикрепленных к классу, методу или свойству.

Встроенные атрибуты

PHP поставляется с несколькими встроенными атрибутами, которые служат различным целям. Вот несколько примечательных из них:

@устарело

Помечает функцию или метод как устаревшие, сигнализируя, что их следует избегать, поскольку они могут быть удалены в будущих версиях.

#[Deprecated("Use newFunction() instead")]
function oldFunction() 
{
    // Function implementation
}

@переопределить

Гарантирует, что метод дочернего класса предназначен для переопределения метода родительского класса.

class Child extends Parent {
    #[Override]
    public function defaultMethod() 
    {
        // Method implementation
    }
}

Если defaultMethod() в конечном итоге изменит свое имя в родительском классе, это больше не является переопределением. В этом случае PHP выдаст предупреждение, поскольку мы явно заявили, что ожидаем переопределения, и предупредит нас о несовпадении.

В любом случае, хорошая IDE должна позволять нам не допускать подобных ошибок.

@SuppressWarnings

Подавляет определенные предупреждения для определенного фрагмента кода.

#[SuppressWarnings("SomeWarning")]
function someFunction() 
{
    // Function implementation
}

Создание пользовательских классов атрибутов

Теперь давайте создадим собственный класс атрибутов. Это полезно, если вы хотите инкапсулировать определенное поведение внутри атрибута.

#[Attribute]
class CustomAttribute 
{
    public string $message;

    public function __construct(string $message) 
    {
        $this->message = $message;
    }
}

Затем вы можете использовать этот пользовательский атрибут для различных элементов:

class MyClass 
{
    #[CustomAttribute("This is a custom attribute")]
    public $myProperty;

    #[CustomAttribute("Another custom attribute")]
    public function myMethod() 
    {
        // Method implementation
    }
}

Примеры использования

Давайте рассмотрим практический пример. Предположим, вы создаете веб-приложение и хотите создать собственный атрибут для определения длины строки:

#[Attribute(Attribute::TARGET_PROPERTY)]
class MaxLength 
{
    public int $maxLength;

    public function __construct(int $maxLength) 
    {
        $this->maxLength = $maxLength;
    }
}

В приведенном выше примере мы ограничили возможность применения атрибута только к свойствам класса. Теперь мы можем использовать его в классе User:

class User 
{
    #[MaxLength(20, message: "Username must be 20 characters or less")]
    public string $username;

    // Other properties and methods
}

Как упоминалось ранее, добавление атрибута к свойству не влияет на выполнение. Но теперь мы можем получить эту информацию, используя отражение, чтобы в конечном итоге предпринять какие-то действия.

Принятие PHP-фреймворками

Наиболее используемые PHP-фреймворки, такие как Symfony и Laravel, уже используют атрибуты, которые фактически заменяют «Аннотации». В Symfony 5.2 или более поздней версии вы можете объявить контроллер и подключить его к маршруту, используя атрибуты:

public class Arrayable implements \ArrayAccess
{
    …

    public function offsetExists($offset)
    {
        return isset($this->data[$offset]);
    }

    …
}

Начиная с версии PHP 8, определение интерфейса ArrayAccess изменилось на:

С помощью атрибутов они обеспечили объявление типа данных для аргументов в функциях смещения. Если при использовании атрибута LanguageLevelTypeAware реализация не предоставляет тип данных для аргументов, она выдает «предупреждение об устаревании».

Но объявление типа данных в аргументах функции нарушает совместимость со старыми версиями PHP, которые не поддерживают объявление типа данных аргументов.

Поскольку это было всего лишь предупреждение о будущих изменениях, мы решили проблему с помощью другого встроенного атрибута PHP для подавления предупреждения:

public class Arrayable implements \ArrayAccess
{
    …

    #[\ReturnTypeWillChange]
    public function offsetExists($offset)
    {
        return isset($this->data[$offset]);
    }

    …
}

Атрибут ReturnTypeWillChange просто сообщает PHP, что мы знаем о будущих изменениях в языке и уже запланировали необходимые обновления.

В частности, это изменение будет обязательно реализовано в PHP 9.

Не забывайте использовать атрибуты разумно, сохраняя свою кодовую базу чистой и хорошо документированной. Это особенно важно при разработке продуктов SaaS, где масштабируемость, удобство обслуживания и эффективность имеют первостепенное значение.

Впервые в инспекторе? Контролируйте свое приложение бесплатно

Инспектор — это инструмент мониторинга выполнения кода, специально разработанный для разработчиков программного обеспечения. Вам не нужно ничего устанавливать на уровне сервера, просто установите пакет композитора и все готово.

В отличие от других сложных универсальных платформ, Inspector очень прост и дружелюбен к PHP. Вы можете попробовать наш пакет Laravel или Symfony.

Если вам нужна эффективная автоматизация, глубокая аналитика и возможность пересылать оповещения и уведомления в вашу среду обмена сообщениями, попробуйте Inspector бесплатно. Зарегистрируйте свой аккаунт.

Или узнайте больше на сайте: https://inspector.dev