Download the PHP package herrera-io/annotations without Composer
On this page you can find all versions of the php package herrera-io/annotations. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download herrera-io/annotations
More information about herrera-io/annotations
Files in herrera-io/annotations
Package annotations
Short Description A tokenizer for Doctrine annotations.
License MIT
Homepage https://github.com/herrera-io/php-annotations
Informations about the package annotations
Annotations
The Annotations library is for tokenizing and converting Doctrine-styled annotations. Unlike the Doctrine Annotations library, this one does not require that classes or constants exist, nor are they evaluated.
The
DocLexer
class from the Doctrine Annotations library is used to generate the tokens from the annotated docblocks. This library handles the filtering, validation, and conversion of those tokens.
Example
Installation
Add it as a Composer dependency:
Tokenizing
To tokenize a docblock comment, you will first need to create an instance of
Tokenizer
. The object can be re-used to parse as many docblocks as needed:
The ignore()
method allows you to specify a list of annotations to ignore.
By default, none are ignored, so it may be beneficial to register the default
list provided by Doctrine:
The $aliases
argument allows you to specify a list of aliases that may
have been used for the name of the annotation. For example. it is common
practice to shorten the name of Doctrine ORM annotations using the following:
The $aliases
example demonstrates how only the ORM
namespace alias will
be mapped to Doctrine\ORM\Mapping
. Additional aliases can be specified at
the same time:
The value of $parsed
is an array of tokens. Each token will contain the
token's numeric identifier, followed by the value parsed from the docblock
(if applicable).
You can find a reference of the token identifiers here.
This example docblock:
will yield the following tokens in $tokens
:
Converting
Once you have parsed a docblock for its tokens, you may find the need to convert
the list of tokens into another format. Before I cover the available converters,
I need to show you how to create an instance of Tokens
and Sequence
which
are consumed by the converters.
Tokens and Sequence
Converters use either the Tokens
or Sequence
class when converting a list
of tokens into an alternative format. The Tokens
class acts like an array,
but it will also validate the tokens as they are being used. The Sequence
class is an extension of Tokens
, but it also validates the order in which
the tokens are used.
The converters only require that you use Tokens
, but they are compatible
with the Sequence
class as well. The only time you may find need for the
Sequence
class is for debugging annotation issues, or if you are accepting
tokens from anything besides the Tokenizer
class.
Creating an instance of either class is very simple:
To Array
An instance of ToArray
is used to convert tokens to a simple array.
The value of $array
is an array of objects. Each object represents a single
annotation in the docblock. Each object will have two properties: name
and
values
. Any values contained in ()
will be in values
, including nested
annotations.
The following example:
will result with the following array:
To String
An instance of ToString
is used to convert tokens to their string
representation.
Using this example:
The result will be similar, but without any of the formatting:
While formatting is supported by the string converter, it is very limited in the number of options it provides:
setBreakChar($char)
— Sets the line break character. (default:\n
)setIndentChar($char)
— Sets the indentation character. (default:setIndentSize($size)
— Sets the indentation size. (default:0
(zero))useColonSpace($bool)
— Toggles whether a space should be added after a colon that is used for assignment. (default:false
) (example:@Name({key: "value"})
)
With a minor modification:
We can get a formatted string returned back to us:
To XML
An instance of ToXml
is used to convert tokens to an XML document.
Using this example:
will result in the following XML:
You can also validate annotation XML using ToXml::validate($input)
, where
$input
can be an XML string or an instance of DOMDocument
. If you only
need access to the XML schema, you can get the file path using the class
constant ToXml::SCHEMA
.
While you may be able to get the schema path using the
HERRERA_ANNOTATIONS_SCHEMA
constant, I don't recommend it. It isn't available until the ToXml class is loaded, and the the name is not guaranteed to be consistent.