Phalcon Annotations

Annotations\Adapter\AbstractAdapter

This is the base class for Phalcon\Annotations adapters

The adapters supply read() and write(). This class does not declare them, the same as in cphalcon.

@method mixed read(string $key) @method mixed write(string $key, Reflection $data)

Uses Phalcon\Annotations\Collection · Phalcon\Annotations\Exception · Phalcon\Annotations\Reader · Phalcon\Annotations\ReaderInterface · Phalcon\Annotations\Reflection · Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Properties

Methods

get()

public function get( mixed $className ): Reflection;

Parses or retrieves all the annotations found in a class

getAnnotationsLimit()

public function getAnnotationsLimit(): int;

Returns the configured annotations-cache cap (0 = unlimited). See setAnnotationsLimit().

getConstant()

public function getConstant(
    string $className,
    string $constantName
): Collection;

Returns the annotations found in a specific constant

getConstants()

public function getConstants( string $className ): array;

Returns the annotations found in all the class’ constants

getMethod()

public function getMethod(
    string $className,
    string $methodName
): Collection;

Returns the annotations found in a specific method

getMethods()

public function getMethods( string $className ): array;

Returns the annotations found in all the class’ methods

getProperties()

public function getProperties( string $className ): array;

Returns the annotations found in all the class’ properties

getProperty()

public function getProperty(
    string $className,
    string $propertyName
): Collection;

Returns the annotations found in a specific property

getReader()

public function getReader(): ReaderInterface;

Returns the annotation reader

setAnnotationsLimit()

public function setAnnotationsLimit( int $annotationsLimit );

Caps the number of class entries retained in the annotations cache. 0 disables the cap (the default; preserves the original unbounded behavior). When the cap is exceeded, the cache is cleared and repopulated on subsequent reads.

setReader()

public function setReader( ReaderInterface $reader );

Sets the annotations parser

Annotations\Adapter\AdapterInterface

This interface must be implemented by adapters in Phalcon\Annotations

Uses Phalcon\Annotations\Collection · Phalcon\Annotations\ReaderInterface · Phalcon\Annotations\Reflection · Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Methods

get()

public function get( string $className ): Reflection;

Parses or retrieves all the annotations found in a class

getConstant()

public function getConstant(
    string $className,
    string $constantName
): Collection;

Returns the annotations found in a specific constant

getConstants()

public function getConstants( string $className ): array;

Returns the annotations found in all the class’ constants

getMethod()

public function getMethod(
    string $className,
    string $methodName
): Collection;

Returns the annotations found in a specific method

getMethods()

public function getMethods( string $className ): array;

Returns the annotations found in all the class’ methods

getProperties()

public function getProperties( string $className ): array;

Returns the annotations found in all the class’ methods

getProperty()

public function getProperty(
    string $className,
    string $propertyName
): Collection;

Returns the annotations found in a specific property

getReader()

public function getReader(): ReaderInterface;

Returns the annotation reader

setReader()

public function setReader( ReaderInterface $reader );

Sets the annotations parser

Annotations\Adapter\Apcu

Stores the parsed annotations in APCu. This adapter is suitable for production

use Phalcon\Annotations\Adapter\Apcu;

$annotations = new Apcu();

Uses Phalcon\Annotations\Reflection · Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Properties

Methods

__construct()

public function __construct( array $options = [] );

Phalcon\Annotations\Adapter\Apcu constructor

read()

public function read( string $key ): bool|Reflection;

Reads parsed annotations from APCu

write()

public function write(
    string $key,
    Reflection $data
): bool;

Writes parsed annotations to APCu

Annotations\Adapter\Memory

Stores the parsed annotations in memory. This adapter is the suitable development/testing

Uses Phalcon\Annotations\Reflection · Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Properties

Methods

__construct()

public function __construct( array $options = [] );

read()

public function read( string $key ): bool|Reflection;

Reads parsed annotations from memory

write()

public function write(
    string $key,
    Reflection $data
): void;

Writes parsed annotations to memory

Annotations\Adapter\Stream

Stores the parsed annotations in files. This adapter is suitable for production

use Phalcon\Annotations\Adapter\Stream;

$annotations = new Stream(
    [
        "annotationsDir" => "app/cache/annotations/",
    ]
);

Uses Phalcon\Annotations\Annotation · Phalcon\Annotations\Collection · Phalcon\Annotations\Exceptions\AnnotationsDirectoryNotWritable · Phalcon\Annotations\Exceptions\CannotReadAnnotationData · Phalcon\Annotations\Reflection · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Support\Traits\FilePathTrait · Phalcon\Traits\Php\FileTrait

Method Summary

Properties

Methods

__construct()

public function __construct( array $options = [] );

Phalcon\Annotations\Adapter\Stream constructor

read()

public function read( string $key ): bool|int|Reflection;

Reads parsed annotations from files

write()

public function write(
    string $key,
    Reflection $data
): void;

Writes parsed annotations to files

Annotations\Annotation

Represents a single annotation in an annotations collection

Uses Phalcon\Annotations\Docblock\Scanner\Opcode · Phalcon\Annotations\Exceptions\UnknownAnnotationExpression · Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Constants

Properties

Methods

__construct()

public function __construct( array $reflectionData );

Phalcon\Annotations\Annotation constructor

getArgument()

public function getArgument( int|string $position ): mixed;

Returns an argument in a specific position

getArguments()

public function getArguments(): array;

Returns the expression arguments

getExprArguments()

public function getExprArguments(): array;

Returns the expression arguments without resolving

getExpression()

public function getExpression( array $expr ): mixed;

Resolves an annotation expression

getName()

public function getName(): string|null;

Returns the annotation’s name

getNamedArgument()

public function getNamedArgument( string $name ): mixed;

Returns a named argument

getNamedParameter()

public function getNamedParameter( string $name ): mixed;

Returns a named parameter

hasArgument()

public function hasArgument( int|string $position ): bool;

Returns an argument in a specific position

numberArguments()

public function numberArguments(): int;

Returns the number of arguments that the annotation has

Annotations\AnnotationsFactory

Factory to create annotations components

Uses Phalcon\Annotations\Adapter\AdapterInterface · Phalcon\Annotations\Adapter\Apcu · Phalcon\Annotations\Adapter\Memory · Phalcon\Annotations\Adapter\Stream · Phalcon\Config\ConfigInterface · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Factory\AbstractFactory

Method Summary

Methods

__construct()

public function __construct( array $services = [] );

AdapterFactory constructor.

load()

public function load( mixed $config ): AdapterInterface;

Factory to create an instance from a Config object

newInstance()

public function newInstance(
    string $name,
    array $options = []
): AdapterInterface;

Create a new instance of the adapter

getExceptionClass()

protected function getExceptionClass(): string;

getServices()

protected function getServices(): array;

Returns the available adapters

Annotations\AttributesReader

Parses PHP attributes returning an array with the found annotations

The array has the same shape as the one of Phalcon\Annotations\Reader, so the adapters, Reflection, Collection and Annotation do not know which reader made it.

PHP resolves the value of an attribute argument, so there is no parse tree to walk. Each value goes in a node of the type Annotation::T_RESOLVED, which Annotation::getExpression() gives back without a change.

Uses Phalcon\Annotations\Docblock\Scanner\Opcode · Phalcon\Contracts\Annotations\AnnotationsTypes · ReflectionAttribute · ReflectionClass · ReflectionException

Method Summary

Constants

Methods

parse()

public function parse( string $className ): array;

Reads attributes from the class, its constants, properties and methods

buildArguments()

protected function buildArguments( array $attributeArguments ): array;

Makes the argument list of one attribute. PHP resolved the values already, so each one goes in a node that Annotation::getExpression() gives back without a change. An integer key is a positional argument and a string key is a named one.

buildNodes()

protected function buildNodes(
    array $attributes,
    string $file,
    int $line
): array;

Makes the node list of one target from its attributes

resolveName()

protected function resolveName( string $name ): string;

Gives the name that the collection matches on.

An attribute of the Phalcon\Annotations namespace gets the short name, so that #[Column] and @Column give the same name. Every other attribute keeps the full class name, so that an attribute of another library cannot take the place of a Phalcon one.

Extend this reader and override this method to give the same short name to the attributes of your own namespace.

Annotations\Collection

Represents a collection of annotations. This class allows to traverse a group of annotations easily

// Traverse annotations
foreach ($classAnnotations as $annotation) {
    echo "Name=", $annotation->getName(), PHP_EOL;
}

// Check if the annotations has a specific
var_dump($classAnnotations->has("Cacheable"));

// Get an specific annotation in the collection
$annotation = $classAnnotations->get("Cacheable");

The class cannot carry an @implements Iterator<int, Annotation> tag. current() returns false past the end of the collection, while Psalm’s Iterator stub requires TValue|null there. Narrowing the iteration would mean changing that return to null, which is a v7 signature change.

Uses Countable · Iterator · Phalcon\Annotations\Exceptions\AnnotationNotFound · Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Properties

Methods

__construct()

public function __construct( array $reflectionData = [] );

Phalcon\Annotations\Collection constructor

count()

public function count(): int;

Returns the number of annotations in the collection

current()

public function current(): mixed;

Returns the current annotation in the iterator

get()

public function get( string $name ): Annotation;

Returns the first annotation that match a name

getAll()

public function getAll( string $name ): array;

Returns all the annotations that match a name

getAnnotations()

public function getAnnotations(): array;

Returns the internal annotations as an array

has()

public function has( string $name ): bool;

Check if an annotation exists in a collection

key()

public function key(): int;

Returns the current position/key in the iterator

next()

public function next(): void;

Moves the internal iteration pointer to the next position

rewind()

public function rewind(): void;

Rewinds the internal iterator

valid()

public function valid(): bool;

Check if the current annotation in the iterator is valid

Annotations\Exception

Class for exceptions thrown by Phalcon\Annotations

Annotations\Exceptions\AnnotationNotFound

Uses Phalcon\Annotations\Exception

Method Summary

Methods

__construct()

public function __construct( string $name );

Annotations\Exceptions\AnnotationsDirectoryNotWritable

Uses Phalcon\Annotations\Exception

Method Summary

Methods

__construct()

public function __construct();

Annotations\Exceptions\CannotReadAnnotationData

Uses RuntimeException

Method Summary

Methods

__construct()

public function __construct();

Annotations\Exceptions\UnknownAnnotationExpression

Uses Phalcon\Annotations\Exception

Method Summary

Methods

__construct()

public function __construct( string $type );

Annotations\Models\MetaData\Column

Describes a model column. It is the attribute form of @Column.

The parameter names are camelCase, because PSR-12 does not allow snake_case. The metadata strategy reads the two spellings. The default value is defaultValue and not default, because default is a Zephir keyword.

Uses Attribute

Method Summary

Properties

Methods

__construct()

public function __construct(
    string|null $column = null,
    string $type = "string",
    int|null $length = null,
    bool $nullable = false,
    bool $skipOnInsert = false,
    bool $skipOnUpdate = false,
    bool $allowEmptyString = false,
    mixed $defaultValue = null
);

Annotations\Models\MetaData\Identity

Marks a property as the identity column. It is the attribute form of @Identity.

Uses Attribute

Annotations\Models\MetaData\Primary

Marks a property as part of the primary key. It is the attribute form of @Primary.

Uses Attribute

Annotations\Models\MetaData\Source

Names the table of a model. No framework code reads it today.

Uses Attribute

Method Summary

Properties

Methods

__construct()

public function __construct( string $table );

Annotations\Reader

Parses docblocks returning an array with the found annotations

Uses Phalcon\Annotations\Docblock\Exception · Phalcon\Annotations\Docblock\Parser\Parser · Phalcon\Contracts\Annotations\AnnotationsTypes · ReflectionClass · ReflectionClassConstant

Method Summary

Methods

parse()

public function parse( string $className ): array;

Reads annotations from the class docblocks, its methods and/or properties

parseDocBlock()

public static function parseDocBlock(
    string $docBlock,
    mixed $file = null,
    mixed $line = null
): array|false;

Parses a raw doc block returning the annotations found

Annotations\ReaderInterface

Reads the annotations of a class and returns them as an array

Phalcon\Annotations\Reader reads the docblocks and Phalcon\Annotations\AttributesReader reads the PHP attributes. The two give the same array shape, so the adapter and the classes after it do not know which reader made it.

Uses Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Methods

parse()

public function parse( string $className ): array;

Reads annotations from the class, its constants, properties and methods

Annotations\Reflection

Allows to manipulate the annotations reflection in an OO manner

use Phalcon\Annotations\Reader;
use Phalcon\Annotations\Reflection;

// Parse the annotations in a class
$reader = new Reader();
$parsing = $reader->parse("MyComponent");

// Create the reflection
$reflection = new Reflection($parsing);

// Get the annotations in the class docblock
$classAnnotations = $reflection->getClassAnnotations();

Uses Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Properties

Methods

__construct()

public function __construct( array $reflectionData = [] );

getClassAnnotations()

public function getClassAnnotations(): Collection|null;

Returns the annotations found in the class docblock

getConstantsAnnotations()

public function getConstantsAnnotations(): array;

Returns the annotations found in the constants’ docblocks

getMethodsAnnotations()

public function getMethodsAnnotations(): array;

Returns the annotations found in the methods’ docblocks

getPropertiesAnnotations()

public function getPropertiesAnnotations(): array;

Returns the annotations found in the properties’ docblocks

getReflectionData()

public function getReflectionData(): array;

Returns the raw parsing intermediate definitions used to construct the reflection

Annotations\Router\Connect

Marks a method as a CONNECT route. It is the attribute form of @Connect.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Delete

Marks a method as a DELETE route. It is the attribute form of @Delete.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Get

Marks a method as a GET route. It is the attribute form of @Get.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Head

Marks a method as a HEAD route. It is the attribute form of @Head.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Options

Marks a method as a OPTIONS route. It is the attribute form of @Options.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Patch

Marks a method as a PATCH route. It is the attribute form of @Patch.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Post

Marks a method as a POST route. It is the attribute form of @Post.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Purge

Marks a method as a PURGE route. It is the attribute form of @Purge.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Put

Marks a method as a PUT route. It is the attribute form of @Put.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\Route

Marks a method as a route. It is the attribute form of @Route.

The annotations service never makes an instance of this class. It reads the arguments with ReflectionAttribute::getArguments(). The class gives the name, the targets and the signature that an IDE and a static analyzer read.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $route,
    array|string|null $methods = null,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);

Annotations\Router\RoutePrefix

Sets the prefix of every route of a controller. It is the attribute form of @RoutePrefix.

Uses Attribute

Method Summary

Properties

Methods

__construct()

public function __construct( string $prefix );

Annotations\Router\Trace

Marks a method as a TRACE route. It is the attribute form of @Trace.

Uses Attribute · Phalcon\Contracts\Annotations\AnnotationsTypes · Phalcon\Http\Message\RequestMethodInterface

Method Summary

Methods

__construct()

public function __construct(
    string $route,
    string|null $name = null,
    array $paths = [],
    array $converters = [],
    array|string|null $beforeMatch = null
);