zonuexe/simple-annotations

Simple annotation parser

0.3.1 2016-08-19 16:47 UTC

Requires

• php: >= 5.4.0

Requires (Dev)

• etsy/phan: ^0.6.0
• phpunit/phpunit: ^4.8|^5.5

MIT

• Jan Święcki
• USAMI Kenta

• annotations
• parser
• annotation
• docblock

README

Installation

Get composer and learn to use it.

Library is on packagist.

If you refuse to use composer then instead of include_once "vendor/autoload.php" use include_once "src/DocBlockReader/Reader.php".

Test

You need PHPUnit. After you get it run:

> git clone https://github.com/jan-swiecki/php-simple-annotations
> cd php-simple-annotations
> composer install
> phpunit

API

• $reader = new \DocBlockReader\Reader(String $className)

Initialize DocBlock Reader on class $className

• $reader = new \DocBlockReader\Reader(String $className, String $methodName)

Initialize DocBlock Reader on method $className::$methodName

• $reader->getParameter(String $key)

Returns DocBlock value of parameter $key. E.g.

<?php
class MyClass
{
    /**
     * @awesomeVariable "I am a string"
     */
    public function fn()
    {

    }
}

then $reader->getParameter("awesomeVariable") will return string I am a string (without quotes).

• $reader->getParameters()

returns array of all parameters (see examples below).

• $reader->getVariableDeclarations()

See last example.

Examples

Examples based on ReaderTest.php.

Note: DocBlock Reader converts type of values basing on the context (see below).

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

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' => string 'tRuE' (length=4)
  '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

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

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.

<?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

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)