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/frostbane/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.

Example:

    class TestClass {
      /**
       * @x 1
       * @y yes!
       */
      private $myVar;
    }

    $reader = new \frostbane\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.

You can point at classes, class methods and class properties.

• Targeting class: $reader = new \frostbane\DocBlockReader\Reader(String $className)
• Targeting method or property: $reader = new \frostbane\DocBlockReader\Reader(String $className, String $name [, String $type = 'method'])

This will initialize DocBlock Reader on method $className::$name or property $className::$name.

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.

To extract parsed properties you have two methods:

• $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 = new \frostbane\DocBlockReader\Reader('MyClass', 'fn');
 $reader->getParameter("awesomeVariable")

will return string I am a string (without quotes).

• $reader->getParameters()

returns array of all parameters (see examples below).

API

• Constructor $reader = new \frostbane\DocBlockReader\Reader(String $className [, String $name [, String $type = 'method'] ])

  Creates Reader pointing at class, class method or class property - based on provided arguments (see Introduction).

• $reader->getParameter(String $key)

Returns value of parameter $key extracted from DocBlock.

• $reader->getParameters()

returns array of all parameters (see examples below).

• $reader->getVariableDeclarations() - See last example below.

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
{
    /**
     * @float_0-0         0.0
     * @float_1-5         1.5
     * @int_1             1
     * @int_0             0
     * @string_2-3 "2.3"
     * @string_1   "1"
     * @string_0   "0"
     * @string_0-0 "0.0"
     * @string_123 "123"
     * @string_4-5 "4.5"
     *
     * @string_abc        abc
     * @string_def  "def"
     *
     * @array1 ["a", "b"]
     * @obj1 {"x": "y"}
     * @obj2 {"x": {"y": "z"}}
     * @obj_array1 {"x": {"y": ["z", "p"]}}
     *
     * @empty1
     * @null1             null
     * @string_null "null"
     *
     * @bool_true         true
     * @bool_false        false
     *
     * @string_tRuE       tRuE
     * @string_fAlSe      fAlSe
     * @string_true  "true"
     * @string_false "false"
     *
     */
    private function MyMethod()
    {
    }
}

$reader = new \frostbane\DocBlockReader\Reader("MyClass", "MyMethod");

var_dump($reader->getParameters());

will print

array (size=25)
  'float_0-0' => float 0
  'float_1-5' => float 1.5
  'int_1' => int 1
  'int_0' => int 0
  'string_2-3' => string '2.3' (length=3)
  'string_1' => string '1' (length=1)
  'string_0' => string '0' (length=1)
  'string_0-0' => string '0.0' (length=3)
  'string_123' => string '123' (length=3)
  'string_4-5' => string '4.5' (length=3)
  'string_abc' => string 'abc' (length=3)
  'string_def' => string 'def' (length=3)
  'array1' =>
    array (size=2)
      0 => string 'a' (length=1)
      1 => string 'b' (length=1)
  'obj1' =>
    array (size=1)
      'x' => string 'y' (length=1)
  'obj2' =>
    array (size=1)
      'x' =>
        array (size=1)
          'y' => string 'z' (length=1)
  'obj_array1' =>
    array (size=1)
      'x' =>
        array (size=1)
          'y' =>
            array (size=2)
              ...
  'empty1' => boolean true
  'null1' => null
  'string_null' => string 'null' (length=4)
  'bool_true' => boolean true
  'bool_false' => boolean false
  'string_tRuE' => string 'tRuE' (length=4)
  'string_fAlSe' => string 'fAlSe' (length=5)
  'string_true' => string 'true' (length=4)
  'string_false' => string 'false' (length=5)

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 \frostbane\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 \frostbane\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 \frostbane\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)