README.md

   1 # PHP Simple Annotations
   2
   3 ## Installation
   4
   5 Get [composer](http://getcomposer.org/) and learn to use it.
   6
   7 Library is on [packagist](https://packagist.org/packages/jan-swiecki/simple-annotations).
   8
   9 If you refuse to use composer then instead of `include_once "vendor/autoload.php"` use `include_once "src/DocBlockReader/Reader.php"`.
  10
  11 ## API
  12
  13 DocBlock variable names does not matter. DocBlock Reader converts type of values basing on the context (see examples).
  14
  15 * `$reader = new \DocBlockReader\Reader(String $className, String $methodName)`
  16
  17  Initialize DocBlock Reader on `$className::$methodName`.
  18
  19 * `$reader->getParameter(String $key)`
  20
  21  Returns DocBlock value of parameter `$key`. E.g.
  22
  23  ```php
  24  <?php
  25  class MyClass
  26  {
  27      /**
  28       * @awesomeVariable "I am a string"
  29       */
  30      public function fn()
  31      {
  32
  33      }
  34  }
  35  ```
  36
  37  then `$reader->getParameter("awesomeVariable")` will return string `I am a string` (without quotes).
  38
  39 * `$reader->getParameters()`
  40
  41  returns array of all parameters (see examples below).
  42
  43 * `$reader->getVariableDeclarations()`
  44
  45  See last example.
  46
  47 ## Examples
  48
  49 Examples based on ReaderTest.php.
  50
  51 ### Type conversion example
  52
  53 ```php
  54 <?php
  55
  56 include_once "vendor/autoload.php";
  57
  58 class MyClass
  59 {
  60         /**
  61          * @var0 1.5
  62          * @var1 1
  63          * @var2 "123"
  64          * @var3 abc
  65          * @var4 ["a", "b"]
  66          * @var5 {"x": "y"}
  67          * @var6 {"x": {"y": "z"}}
  68          * @var7 {"x": {"y": ["z", "p"]}}
  69          *
  70          * @var8
  71          * @var9 null
  72          *
  73          * @var10 true
  74          * @var11 tRuE
  75          * @var12 false
  76          * @var13 null
  77          *
  78          */
  79         private function MyMethod()
  80         {
  81         }
  82 };
  83
  84 $reader = new DocBlockReader\Reader("MyClass", "MyMethod");
  85
  86 var_dump($reader->getParameters());
  87 ```
  88
  89 will print
  90
  91
  92 <pre class='xdebug-var-dump' dir='ltr'>
  93 <b>array</b> <i>(size=14)</i>
  94   'var0' <font color='#888a85'>=&gt;</font> <small>float</small> <font color='#f57900'>1.5</font>
  95   'var1' <font color='#888a85'>=&gt;</font> <small>int</small> <font color='#4e9a06'>1</font>
  96   'var2' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'123'</font> <i>(length=3)</i>
  97   'var3' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'abc'</font> <i>(length=3)</i>
  98   'var4' <font color='#888a85'>=&gt;</font>
  99     <b>array</b> <i>(size=2)</i>
 100       0 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'a'</font> <i>(length=1)</i>
 101       1 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'b'</font> <i>(length=1)</i>
 102   'var5' <font color='#888a85'>=&gt;</font>
 103     <b>array</b> <i>(size=1)</i>
 104       'x' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'y'</font> <i>(length=1)</i>
 105   'var6' <font color='#888a85'>=&gt;</font>
 106     <b>array</b> <i>(size=1)</i>
 107       'x' <font color='#888a85'>=&gt;</font>
 108         <b>array</b> <i>(size=1)</i>
 109           'y' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'z'</font> <i>(length=1)</i>
 110   'var7' <font color='#888a85'>=&gt;</font>
 111     <b>array</b> <i>(size=1)</i>
 112       'x' <font color='#888a85'>=&gt;</font>
 113         <b>array</b> <i>(size=1)</i>
 114           'y' <font color='#888a85'>=&gt;</font>
 115             <b>array</b> <i>(size=2)</i>
 116               0 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'z'</font> <i>(length=1)</i>
 117               1 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'p'</font> <i>(length=1)</i>
 118   'var8' <font color='#888a85'>=&gt;</font> <small>boolean</small> <font color='#75507b'>true</font>
 119   'var9' <font color='#888a85'>=&gt;</font> <font color='#3465a4'>null</font>
 120   'var10' <font color='#888a85'>=&gt;</font> <small>boolean</small> <font color='#75507b'>true</font>
 121   'var11' <font color='#888a85'>=&gt;</font> <small>boolean</small> <font color='#75507b'>true</font>
 122   'var12' <font color='#888a85'>=&gt;</font> <small>boolean</small> <font color='#75507b'>false</font>
 123   'var13' <font color='#888a85'>=&gt;</font> <font color='#3465a4'>null</font>
 124 </pre>
 125
 126 ### Multi value example
 127
 128 ```php
 129 <?php
 130
 131 include_once "vendor/autoload.php";
 132
 133 class MyClass
 134 {
 135         /**
 136          * @var x
 137          * @var2 1024
 138          * @param string x
 139          * @param integer y
 140          * @param array z
 141          */
 142         private function MyMethod()
 143         {
 144         }
 145 };
 146
 147 $reader = new DocBlockReader\Reader("MyClass", "MyMethod");
 148
 149 var_dump($reader->getParameters());
 150 ```
 151
 152 will print
 153
 154
 155 <pre class='xdebug-var-dump' dir='ltr'>
 156 <b>array</b> <i>(size=3)</i>
 157   'var' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'x'</font> <i>(length=1)</i>
 158   'var2' <font color='#888a85'>=&gt;</font> <small>int</small> <font color='#4e9a06'>1024</font>
 159   'param' <font color='#888a85'>=&gt;</font>
 160     <b>array</b> <i>(size=3)</i>
 161       0 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'string x'</font> <i>(length=8)</i>
 162       1 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'integer y'</font> <i>(length=9)</i>
 163       2 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'array z'</font> <i>(length=7)</i>
 164 </pre>
 165
 166 ### Variables on the same line
 167
 168 ```php
 169 <?php
 170
 171 include_once "vendor/autoload.php";
 172
 173 class MyClass
 174 {
 175         /**
 176          * @get @post
 177          * @ajax
 178          * @postParam x @postParam y
 179          * @postParam z
 180          */
 181         private function MyMethod()
 182         {
 183         }
 184 };
 185
 186 $reader = new DocBlockReader\Reader("MyClass", "MyMethod");
 187
 188 var_dump($reader->getParameters());
 189 ```
 190
 191 will print
 192
 193 <pre class='xdebug-var-dump' dir='ltr'>
 194 <b>array</b> <i>(size=4)</i>
 195   'get' <font color='#888a85'>=&gt;</font> <small>boolean</small> <font color='#75507b'>true</font>
 196   'post' <font color='#888a85'>=&gt;</font> <small>boolean</small> <font color='#75507b'>true</font>
 197   'ajax' <font color='#888a85'>=&gt;</font> <small>boolean</small> <font color='#75507b'>true</font>
 198   'postParam' <font color='#888a85'>=&gt;</font>
 199     <b>array</b> <i>(size=3)</i>
 200       0 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'x'</font> <i>(length=1)</i>
 201       1 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'y'</font> <i>(length=1)</i>
 202       2 <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'z'</font> <i>(length=1)</i>
 203 </pre>
 204
 205 ### Variable declarations functionality example
 206
 207 I found below functionality useful for filtering `$_GET`/`$_POST` data in CodeIgniter. Hopefully I will soon release my CodeIgniter's modification.
 208
 209 ```php
 210 <?php
 211
 212 include_once "vendor/autoload.php";
 213
 214 class MyClass
 215 {
 216         /**
 217          * @param string var1
 218          * @param integer var2
 219          */
 220         private function MyMethod()
 221         {
 222         }
 223 };
 224
 225 $reader = new DocBlockReader\Reader("MyClass", "MyMethod");
 226
 227 var_dump($reader->getVariableDeclarations("param"));
 228 ```
 229
 230 will print
 231
 232 <pre class='xdebug-var-dump' dir='ltr'>
 233 <b>array</b> <i>(size=2)</i>
 234   0 <font color='#888a85'>=&gt;</font>
 235     <b>array</b> <i>(size=2)</i>
 236       'type' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'string'</font> <i>(length=6)</i>
 237       'name' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'var1'</font> <i>(length=4)</i>
 238   1 <font color='#888a85'>=&gt;</font>
 239     <b>array</b> <i>(size=2)</i>
 240       'type' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'integer'</font> <i>(length=7)</i>
 241       'name' <font color='#888a85'>=&gt;</font> <small>string</small> <font color='#cc0000'>'var2'</font> <i>(length=4)</i>
 242 </pre>