Download the PHP package quellabs/annotation-reader without Composer

PHP Annotation Reader

A powerful PHP annotation reader for parsing, processing, and caching docblock annotations in PHP classes.

Overview

The AnnotationReader component provides robust parsing and caching of PHP docblock annotations, allowing you to define metadata directly within your class docblocks. This approach makes your code more self-documenting and reduces the need for separate configuration files.

Features

• Annotation parsing: Parse docblock annotations for classes, properties, and methods
• Import resolution: Automatically resolves class imports for fully qualified annotation names
• Class constant support: Supports fully qualified class constants in annotation parameters (e.g., ObjectName::class)
• Performance optimization: Implements smart caching to improve performance
• Flexible integration: Easy to integrate with your existing projects
• Error handling: Graceful handling of malformed annotations
• Collection support: Returns immutable AnnotationCollection objects with array-like access

Installation

Usage

Basic Usage

Working with AnnotationCollection

All annotation reader methods return an AnnotationCollection object that provides array-like access with a clean, flat structure:

Handling Multiple Annotations

When you have multiple annotations of the same type, the collection provides clean access patterns:

Filtered Results

When filtering annotations, the result maintains the same clean structure:

Array Conversion Methods

The AnnotationCollection provides three different methods to convert the collection to standard PHP arrays, each serving different use cases:

toArray() - Mixed Key Format

The toArray() method creates an array with hybrid indexing that provides both class-name access for the first occurrence of each annotation type and numeric indexing for duplicates:

This format is ideal when you need both convenient class-name access and want to preserve all duplicate annotations in a single array structure.

toIndexedArray() - Linear Format

The toIndexedArray() method returns a simple indexed array containing all annotations in their original order:

This format is perfect for sequential processing, serialization, or when you need a simple list without any special key handling.

toGroupedArray() - Grouped by Class

The toGroupedArray() method organizes annotations by their class names, with each class name mapping to an array of all annotations of that type:

This format is excellent for processing annotations by type, configuration systems that need to handle multiple instances of the same annotation, or when building annotation-driven frameworks.

Choosing the Right Conversion Method

• Use toArray() when you need convenient access to single annotations by class name but also want to preserve duplicates in the same structure
• Use toIndexedArray() for simple sequential processing, serialization, or when working with external APIs that expect indexed arrays
• Use toGroupedArray() when building systems that process annotations by type, handling multiple instances of the same annotation class, or creating configuration arrays

Annotation Format

Annotations are defined in PHP docblocks using the @ symbol followed by the annotation name and optional parameters. The annotation reader supports various parameter formats including strings, numbers, booleans, arrays, and the ::class magic constant.

Basic Annotations

Simple annotations with string, numeric, and boolean parameters:

Using Class Constants

Annotations with ::class magic constants for type-safe class references:

Supported Parameter Types

The annotation reader supports these parameter formats:

• Strings: "value" or 'value'
• Numbers: 42, 3.14
• Booleans: true, false
• Arrays: {"item1", "item2"} or {key="value"}
• Class constants: Only ::class magic constant is supported
• Magic class constant: SomeClass::class
• Fully qualified names: \App\Models\User::class
• Imported classes: User::class (when use App\Models\User; is present)

Mixed Parameter Types

You can combine different parameter types within the same annotation:

Configuration

The AnnotationReader requires a Configuration object that specifies:

• Whether to use annotation caching
• The path to store annotation cache files

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.