rudra/annotation

Class & Method Annotation Reader

v26.1 2025-12-26 16:18 UTC

Requires

• php: >=8.3
• rudra/docs: v26.1
• rudra/exception: v26.1

MPL-2.0

• Korotkov Danila

• annotations
• annotation
• rudra
• annotation-processing

README

Annotations and attributes reader / Читатель аннотаций и атрибутов | API

Installation / Установка

composer require rudra/annotation

Modern metadata reader for PHP 8+ attributes with legacy annotation support.

Современный читатель метаданных для атрибутов PHP 8+ с поддержкой устаревших аннотаций.

Using / Использование

$annotation = new Annotation();

🎯 Recommended: PHP 8+ Attributes / Рекомендуемый способ: Атрибуты PHP 8+

$annotation->getAttributes(PageController::class);
$annotation->getAttributes(PageController::class, "indexAction");

#[Routing(url:'')]
#[Defaults(name:'user1', lastname:'sample', age:'0', address:['country' => 'Russia', 'state' => 'Tambov'], phone:'000-00000000')]
#[assertResult(false)]
#[Validate(name:'min:150', phone:'max:9')]
#[Middleware('Middleware', params:['int1' => '123'])]
#[Annotation("param1", param2:'param2', param3:['param1', 'param2' => 'param2'])]
class PageController
{
    #[Routing(url:'')]
    #[Defaults(name:'user1', lastname:'sample', age:'0', address:['country' => 'Russia', 'state' => 'Tambov'], phone:'000-00000000')]
    #[assertResult(false)]
    #[Validate(name:'min:150', phone:'max:9')]
    #[Middleware('Middleware', params:['int1' => '123'])]
    #[Annotation("param1", param2:'param2', param3:['param1', 'param2' => 'param2'])]
    public function indexAction()
    {
        // Your code
    }        
}

📜 Legacy: Annotations / Устаревший способ: Аннотации

Note: Annotations are supported for backward compatibility with legacy projects. For new projects, use PHP 8+ attributes.

Примечание: Аннотации поддерживаются для обратной совместимости с легаси-проектами. Для новых проектов используйте атрибуты PHP 8+.

$annotation->getAnnotations(PageController::class);
$annotation->getAnnotations(PageController::class, "indexAction");

/**
 * @Routing(url = '')
 * @Defaults(name = 'user1', lastname = 'sample', age='0', address = {country : 'Russia'; state : 'Tambov'}, phone = '000-00000000')
 * @assertResult(false)
 * @Validate(name = 'min:150', phone = 'max:9')
 * @Middleware('Middleware', params = {int1 : '123'})
 * @Annotation(param1, param2 = 'param2', param3={param1;param2:'param2'})
 */
class PageController
{
    /**
     * @Routing(url = '')
     * @Defaults(name = 'user1', lastname = 'sample', age='0', address = {country : 'Russia'; state : 'Tambov'}, phone = '000-00000000')
     * @assertResult(false)
     * @Validate(name = 'min:150', phone = 'max:9')
     * @Middleware('Middleware', params = {int1 : '123'})
     * @Annotation(param1, param2 = 'param2', param3={param1;param2:'param2'})
     */
    public function indexAction()
    {
        // Your code
    }        
}

📊 Result in both cases / Результат чтения в обоих случаях:

[
    'Routing' => [['url' => ""]],
    'Defaults' => [
        [
            'name' => "user1",
            'lastname' => "sample",
            'age' => "0",
            'address' => [
                'country' => "Russia",
                'state' => "Tambov",
            ],
            'phone' => "000-00000000",
        ],
    ],
    'assertResult' => [["false"]],
    'Validate' => [
        [
            'name' => "min:150",
            'phone' => "max:9",
        ],
    ],
    'Middleware' => [
        [
            "'Middleware'",
            'params' => [
                'int1' => '123',
            ],
        ],
    ],
    "Annotation" => [
        [
            "param1",
            "param2" => "param2",
            "param3" => [
                "param1",
                "param2" => "param2",
            ],
        ],
    ],
];

⚠️ Known Limitations / Известные ограничения

When using nested arrays (in curly braces {}), ensure that the values do not contain the array assignment symbol (:). The parser uses simple splitting by this symbol and does not escape it inside quotes. String values (with =) are handled correctly even if they contain multiple = symbols.

При использовании вложенных массивов (в фигурных скобках {}) убедитесь, что значения не содержат символ присваивания массива (:). Парсер использует простое разделение по этому символу и не экранирует его внутри кавычек. Строковые значения (с =) обрабатываются корректно, даже если они содержат несколько символов =.

✅ Works correctly / Работает корректно:

/**
 * @Config(settings={theme:'dark'; lang:'ru'})
 * @Routing(url='http://site.com?a=1&b=2')
 */

❌ Breaks array parsing / Ломает парсинг массива:

/**
 * @Config(settings={url:'http://site.com:8080'})
 */

Note: These limitations apply only to legacy annotations. PHP 8+ attributes do not have these restrictions.

Примечание: Эти ограничения касаются только устаревших аннотаций. Атрибуты PHP 8+ не имеют этих ограничений.

✅ All cases work correctly / Все случаи работают корректно:

#[Config(settings: ['theme' => 'dark', 'lang' => 'ru'])]
#[Routing(url: 'http://site.com?a=1&b=2')]
#[Config(settings: ['url' => 'http://site.com:8080'])] // ✅ Works!

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0) — a free, open-source license that:

• Requires preservation of copyright and license notices,
• Allows commercial and non-commercial use,
• Requires that any modifications to the original files remain open under MPL-2.0,
• Permits combining with proprietary code in larger works.

📄 Full license text: LICENSE
🌐 Official MPL-2.0 page: https://mozilla.org/MPL/2.0/

Проект распространяется под лицензией Mozilla Public License 2.0 (MPL-2.0). Это означает:

• Вы можете свободно использовать, изменять и распространять код.
• При изменении файлов, содержащих исходный код из этого репозитория, вы обязаны оставить их открытыми под той же лицензией.
• Вы обязаны сохранять уведомления об авторстве и ссылку на оригинал.
• Вы можете встраивать код в проприетарные проекты, если исходные файлы остаются под MPL.

📄 Полный текст лицензии (на английском): LICENSE
🌐 Официальная страница: https://mozilla.org/MPL/2.0/