PHP Simple Annotations
Installation
Get composer and learn to use it., (*1)
Library is on packagist., (*2)
If you refuse to use composer then instead of include_once "vendor/autoload.php" use include_once "src/DocBlockReader/Reader.php"., (*3)
Test
You need PHPUnit. After you get it run:, (*4)
> git clone https://github.com/jan-swiecki/php-simple-annotations
> cd php-simple-annotations
> composer install
> phpunit
Introduction
This library gives you the ability to extract and auto-parse DocBlock comment blocks., (*5)
Example:, (*6)
class TestClass {
/**
* @x 1
* @y yes!
*/
private $myVar;
}
$reader = new \DocBlockReader\Reader('TestClass', 'myVar', 'property');
$x = $reader->getParameter("x"); // 1 (with number type)
$y = $reader->getParameter("y"); // "yes!" (with string type)
So as you can see to do this you need to construct Reader object and target it at something. Then you extract data., (*7)
You can point at classes, class methods and class properties., (*8)
- Targeting class:
$reader = new \DocBlockReader\Reader(String $className)
-
Targeting method or property: $reader = new \DocBlockReader\Reader(String $className, String $name [, String $type = 'method']), (*9)
This will initialize DocBlock Reader on method $className::$name or property $className::$name., (*10)
To choose method use only two arguments or provide third argument as method string value. To get property value put property string value in third argument., (*11)
To extract parsed properties you have two methods:, (*12)
-
$reader->getParameter(String $key), (*13)
Returns DocBlock value of parameter $key. E.g., (*14)
<?php
class MyClass
{
/**
* @awesomeVariable "I am a string"
*/
public function fn()
{
}
}
then, (*15)
$reader = new \DocBlockReader\Reader('MyClass', 'fn');
$reader->getParameter("awesomeVariable")
will return string I am a string (without quotes)., (*16)
-
$reader->getParameters(), (*17)
returns array of all parameters (see examples below)., (*18)
API
-
Constructor $reader = new \DocBlockReader\Reader(String $className [, String $name [, String $type = 'method'] ]), (*19)
Creates Reader pointing at class, class method or class property - based on provided arguments (see Introduction)., (*20)
-
$reader->getParameter(String $key), (*21)
Returns value of parameter $key extracted from DocBlock., (*22)
-
$reader->getParameters(), (*23)
returns array of all parameters (see examples below)., (*24)
-
$reader->getVariableDeclarations() - See last example below., (*25)
Examples
Examples based on ReaderTest.php., (*26)
Note: DocBlock Reader converts type of values basing on the context (see below)., (*27)
Type conversion example
<?php
include_once "vendor/autoload.php";
class MyClass
{
/**
* @var0 1.5
* @var1 1
* @var2 "123"
* @var3 abc
* @var4 ["a", "b"]
* @var5 {"x": "y"}
* @var6 {"x": {"y": "z"}}
* @var7 {"x": {"y": ["z", "p"]}}
*
* @var8
* @var9 null
*
* @var10 true
* @var11 tRuE
* @var12 false
* @var13 null
*
*/
private function MyMethod()
{
}
};
$reader = new DocBlockReader\Reader("MyClass", "MyMethod");
var_dump($reader->getParameters());
will print, (*28)
array (size=14)
'var0' => float 1.5
'var1' => int 1
'var2' => string '123' (length=3)
'var3' => string 'abc' (length=3)
'var4' =>
array (size=2)
0 => string 'a' (length=1)
1 => string 'b' (length=1)
'var5' =>
array (size=1)
'x' => string 'y' (length=1)
'var6' =>
array (size=1)
'x' =>
array (size=1)
'y' => string 'z' (length=1)
'var7' =>
array (size=1)
'x' =>
array (size=1)
'y' =>
array (size=2)
0 => string 'z' (length=1)
1 => string 'p' (length=1)
'var8' => boolean true
'var9' => null
'var10' => boolean true
'var11' => boolean true
'var12' => boolean false
'var13' => null
Multi value example
<?php
include_once "vendor/autoload.php";
class MyClass
{
/**
* @var x
* @var2 1024
* @param string x
* @param integer y
* @param array z
*/
private function MyMethod()
{
}
};
$reader = new DocBlockReader\Reader("MyClass", "MyMethod");
var_dump($reader->getParameters());
will print, (*29)
array (size=3)
'var' => string 'x' (length=1)
'var2' => int 1024
'param' =>
array (size=3)
0 => string 'string x' (length=8)
1 => string 'integer y' (length=9)
2 => string 'array z' (length=7)
Variables on the same line
<?php
include_once "vendor/autoload.php";
class MyClass
{
/**
* @get @post
* @ajax
* @postParam x @postParam y
* @postParam z
*/
private function MyMethod()
{
}
};
$reader = new DocBlockReader\Reader("MyClass", "MyMethod");
var_dump($reader->getParameters());
will print, (*30)
array (size=4)
'get' => boolean true
'post' => boolean true
'ajax' => boolean true
'postParam' =>
array (size=3)
0 => string 'x' (length=1)
1 => string 'y' (length=1)
2 => string 'z' (length=1)
Variable declarations functionality example
I found below functionality useful for filtering $_GET/$_POST data in CodeIgniter. Hopefully I will soon release my CodeIgniter's modification., (*31)
<?php
include_once "vendor/autoload.php";
class MyClass
{
/**
* @param string var1
* @param integer var2
*/
private function MyMethod()
{
}
};
$reader = new DocBlockReader\Reader("MyClass", "MyMethod");
var_dump($reader->getVariableDeclarations("param"));
will print, (*32)
array (size=2)
0 =>
array (size=2)
'type' => string 'string' (length=6)
'name' => string 'var1' (length=4)
1 =>
array (size=2)
'type' => string 'integer' (length=7)
'name' => string 'var2' (length=4)
Wallogit.com
