documentation/manual/en/module_specs/Zend_Reflection-Reference.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.reflection.reference">
   4     <title>Zend_Reflection Reference</title>
   5
   6     <para>
   7         The various classes in <classname>Zend_Reflection</classname> mimic the
   8         <acronym>API</acronym> of <acronym>PHP</acronym>'s <ulink
   9             url="http://php.net/reflection">Reflection <acronym>API</acronym></ulink> - with one
  10         important difference. <acronym>PHP</acronym>'s Reflection <acronym>API</acronym> does not
  11         provide introspection into docblock annotation tags, nor into parameter variable
  12         types or return types.
  13     </para>
  14
  15     <para>
  16         <classname>Zend_Reflection</classname> analyzes method docblock annotations to
  17         determine parameter variable types and the return type. Specifically,
  18         the <code>@param</code> and <code>@return</code> annotations are used.
  19         However, you can also check for any other annotation tags, as well as
  20         the standard "short" and "long" descriptions.
  21     </para>
  22
  23     <para>
  24         Each reflection object in <classname>Zend_Reflection</classname> overrides the
  25         <methodname>getDocblock()</methodname> method to return an instance of
  26         <classname>Zend_Reflection_Docblock</classname>. This class provides introspection
  27         into the docblocks and annotation tags.
  28     </para>
  29
  30     <para>
  31         <classname>Zend_Reflection_File</classname> is a new reflection class that allows
  32         introspection of <acronym>PHP</acronym> files. With it, you can retrieve the classes,
  33         functions, and global <acronym>PHP</acronym> code contained in the file.
  34     </para>
  35
  36     <para>
  37         Finally, the various methods that return other reflection objects
  38         allow a second parameter, the name of the reflection class to use for
  39         the returned reflection object.
  40     </para>
  41
  42     <sect2 id="zend.reflection.reference.docblock">
  43         <title>Zend_Reflection_Docblock</title>
  44
  45         <para>
  46             <classname>Zend_Reflection_Docblock</classname> is the heart of
  47             <classname>Zend_Reflection</classname>'s value-add over <acronym>PHP</acronym>'s
  48             Reflection <acronym>API</acronym>. It provides the following methods:
  49         </para>
  50
  51         <itemizedlist>
  52             <listitem>
  53                 <para>
  54                     <methodname>getContents()</methodname>: returns the full contents of the
  55                     docblock.
  56                 </para>
  57             </listitem>
  58
  59             <listitem>
  60                 <para>
  61                     <methodname>getStartLine()</methodname>: returns the starting position of
  62                     the docblock within the defining file.
  63                 </para>
  64             </listitem>
  65
  66             <listitem>
  67                 <para>
  68                     <methodname>getEndLine()</methodname>: get last line of docblock within the
  69                     defining file.
  70                 </para>
  71             </listitem>
  72
  73             <listitem>
  74                 <para>
  75                     <methodname>getShortDescription()</methodname>: get the short, one-line
  76                     description (usually the first line of the docblock).
  77                 </para>
  78             </listitem>
  79
  80             <listitem>
  81                 <para>
  82                     <methodname>getLongDescription()</methodname>: get the long description from
  83                     the docblock.
  84                 </para>
  85             </listitem>
  86
  87             <listitem>
  88                 <para>
  89                     <methodname>hasTag($name)</methodname>: determine if the docblock has the
  90                     given annotation tag.
  91                 </para>
  92             </listitem>
  93
  94             <listitem>
  95                 <para>
  96                     <methodname>getTag($name)</methodname>: Retrieve the given annotation tag
  97                     reflection object, or a boolean <constant>FALSE</constant> if it's not
  98                     present.
  99                 </para>
 100             </listitem>
 101
 102             <listitem>
 103                 <para>
 104                     <methodname>getTags($filter)</methodname>: Retrieve all tags, or all tags
 105                     matching the given <varname>$filter</varname> string. The tags
 106                     returned will be an array of
 107                     <classname>Zend_Reflection_Docblock_Tag</classname> objects.
 108                 </para>
 109             </listitem>
 110         </itemizedlist>
 111     </sect2>
 112
 113     <sect2 id="zend.reflection.reference.docblock-tag">
 114         <title>Zend_Reflection_Docblock_Tag</title>
 115
 116         <para>
 117             <classname>Zend_Reflection_Docblock_Tag</classname> provides reflection for
 118             individual annotation tags. Most tags consist of only a name and a
 119             description. In the case of some special tags, the class provides a
 120             factory method for retrieving an instance of the appropriate class.
 121         </para>
 122
 123         <para>
 124             The following methods are defined for
 125             <classname>Zend_Reflection_Docblock_Tag</classname>:
 126         </para>
 127
 128         <itemizedlist>
 129             <listitem>
 130                 <para>
 131                     <methodname>factory($tagDocblockLine)</methodname>: instantiate the
 132                     appropriate tag reflection class and return it.
 133                 </para>
 134             </listitem>
 135
 136             <listitem>
 137                 <para>
 138                     <methodname>getName()</methodname>: return the annotation tag name.
 139                 </para>
 140             </listitem>
 141
 142             <listitem>
 143                 <para>
 144                     <methodname>getDescription()</methodname>: return the annotation
 145                     description.
 146                 </para>
 147             </listitem>
 148         </itemizedlist>
 149     </sect2>
 150
 151     <sect2 id="zend.reflection.reference.docblock-tag-param">
 152         <title>Zend_Reflection_Docblock_Tag_Param</title>
 153
 154         <para>
 155             <classname>Zend_Reflection_Docblock_Tag_Param</classname> is a specialized
 156             version of <classname>Zend_Reflection_Docblock_Tag</classname>. The
 157             <code>@param</code> annotation tag description consists of the
 158             parameter type, variable name, and variable description. It adds the
 159             following methods to <classname>Zend_Reflection_Docblock_Tag</classname>:
 160         </para>
 161
 162         <itemizedlist>
 163             <listitem>
 164                 <para>
 165                     <methodname>getType()</methodname>: return the parameter variable type.
 166                 </para>
 167             </listitem>
 168
 169             <listitem>
 170                 <para>
 171                     <methodname>getVariableName()</methodname>: return the parameter variable
 172                     name.
 173                 </para>
 174             </listitem>
 175         </itemizedlist>
 176     </sect2>
 177
 178     <sect2 id="zend.reflection.reference.docblock-tag-return">
 179         <title>Zend_Reflection_Docblock_Tag_Return</title>
 180
 181         <para>
 182             Like <classname>Zend_Reflection_Docblock_Tag_Param</classname>,
 183             <classname>Zend_Reflection_Docblock_Tag_Return</classname> is a specialized
 184             version of <classname>Zend_Reflection_Docblock_Tag</classname>. The
 185             <code>@return</code> annotation tag description consists of the
 186             return type and variable description. It adds the following method
 187             to <classname>Zend_Reflection_Docblock_Tag</classname>:
 188         </para>
 189
 190         <itemizedlist>
 191             <listitem>
 192                 <para>
 193                     <methodname>getType()</methodname>: return the return type.
 194                 </para>
 195             </listitem>
 196         </itemizedlist>
 197     </sect2>
 198
 199     <sect2 id="zend.reflection.reference.file">
 200         <title>Zend_Reflection_File</title>
 201
 202         <para>
 203             <classname>Zend_Reflection_File</classname> provides introspection into
 204             <acronym>PHP</acronym> files. With it, you can introspect the classes, functions, and
 205             bare <acronym>PHP</acronym> code defined in a file. It defines the following methods:
 206         </para>
 207
 208         <itemizedlist>
 209             <listitem>
 210                 <para>
 211                     <methodname>getFileName()</methodname>: retrieve the filename of the file
 212                     being reflected.
 213                 </para>
 214             </listitem>
 215
 216             <listitem>
 217                 <para>
 218                     <methodname>getStartLine()</methodname>: retrieve the starting line of the
 219                     file (always "1").
 220                 </para>
 221             </listitem>
 222
 223             <listitem>
 224                 <para>
 225                     <methodname>getEndLine()</methodname> retrieve the last line / number of
 226                     lines in the file.
 227                 </para>
 228             </listitem>
 229
 230             <listitem>
 231                 <para>
 232                     <code>getDocComment($reflectionClass =
 233                         'Zend_Reflection_Docblock')</code>: retrive the file-level
 234                     docblock reflection object.
 235                 </para>
 236             </listitem>
 237
 238             <listitem>
 239                 <para>
 240                     <code>getClasses($reflectionClass =
 241                         'Zend_Reflection_Class')</code>: retrieve an array of
 242                     reflection objects, one for each class defined in the file.
 243                 </para>
 244             </listitem>
 245
 246             <listitem>
 247                 <para>
 248                     <code>getFunctions($reflectionClass =
 249                         'Zend_Reflection_Function')</code>: retrieve an array of
 250                     reflection objects, one for each function defined in the file.
 251                 </para>
 252             </listitem>
 253
 254             <listitem>
 255                 <para>
 256                     <code>getClass($name = null, $reflectionClass =
 257                         'Zend_Reflection_Class')</code>: retrieve the reflection
 258                     object for a single class.
 259                 </para>
 260             </listitem>
 261
 262             <listitem>
 263                 <para>
 264                     <methodname>getContents()</methodname>: retrieve the full contents of the
 265                     file.
 266                 </para>
 267             </listitem>
 268         </itemizedlist>
 269     </sect2>
 270
 271     <sect2 id="zend.reflection.reference.class">
 272         <title>Zend_Reflection_Class</title>
 273
 274         <para>
 275             <classname>Zend_Reflection_Class</classname> extends
 276             <code>ReflectionClass</code>, and follows its <acronym>API</acronym>. It adds one
 277             additional method, <methodname>getDeclaringFile()</methodname>, which may be
 278             used to retrieve the <classname>Zend_Reflection_File</classname> reflection
 279             object for the defining file.
 280         </para>
 281
 282         <para>
 283             Additionally, the following methods add an additional argument for
 284             specifying the reflection class to use when fetching a reflection
 285             object:
 286         </para>
 287
 288         <itemizedlist>
 289             <listitem>
 290                 <para>
 291                     <methodname>getDeclaringFile($reflectionClass =
 292                         'Zend_Reflection_File')</methodname>
 293                 </para>
 294             </listitem>
 295
 296             <listitem>
 297                 <para>
 298                     <methodname>getDocblock($reflectionClass =
 299                         'Zend_Reflection_Docblock')</methodname>
 300                 </para>
 301             </listitem>
 302
 303             <listitem>
 304                 <para>
 305                     <methodname>getInterfaces($reflectionClass =
 306                         'Zend_Reflection_Class')</methodname>
 307                 </para>
 308             </listitem>
 309
 310             <listitem>
 311                 <para>
 312                     <methodname>getMethod($reflectionClass = 'Zend_Reflection_Method')</methodname>
 313                 </para>
 314             </listitem>
 315
 316             <listitem>
 317                 <para>
 318                     <methodname>getMethods($filter = -1, $reflectionClass =
 319                         'Zend_Reflection_Method')</methodname>
 320                 </para>
 321             </listitem>
 322
 323             <listitem><para>
 324                 <methodname>getParentClass($reflectionClass = 'Zend_Reflection_Class')</methodname>
 325             </para></listitem>
 326
 327             <listitem>
 328                 <para>
 329                     <code>getProperty($name, $reflectionClass = 'Zend_Reflection_Property')</code>
 330                 </para>
 331             </listitem>
 332
 333             <listitem>
 334                 <para>
 335                     <code>getProperties($filter = -1, $reflectionClass =
 336                         'Zend_Reflection_Property')</code>
 337                 </para>
 338             </listitem>
 339         </itemizedlist>
 340     </sect2>
 341
 342     <sect2 id="zend.reflection.reference.extension">
 343         <title>Zend_Reflection_Extension</title>
 344
 345         <para>
 346             <classname>Zend_Reflection_Extension</classname> extends
 347             <code>ReflectionExtension</code>, and follows its <acronym>API</acronym>. It overrides
 348             the following methods to add an additional argument for specifying
 349             the reflection class to use when fetching a reflection object:
 350         </para>
 351
 352         <itemizedlist>
 353             <listitem>
 354                 <para>
 355                     <code>getFunctions($reflectionClass =
 356                         'Zend_Reflection_Function')</code>: retrieve an array of
 357                     reflection objects representing the functions defined by the extension.
 358                 </para>
 359             </listitem>
 360
 361             <listitem>
 362                 <para>
 363                     <code>getClasses($reflectionClass =
 364                         'Zend_Reflection_Class')</code>: retrieve an array of
 365                     reflection objects representing the classes defined by the extension.
 366                 </para>
 367             </listitem>
 368         </itemizedlist>
 369     </sect2>
 370
 371     <sect2 id="zend.reflection.reference.function">
 372         <title>Zend_Reflection_Function</title>
 373
 374         <para>
 375             <classname>Zend_Reflection_Function</classname> adds a method for retrieving
 376             the function return type, as well as overrides several methods to
 377             allow specifying the reflection class to use for returned reflection
 378             objects.
 379         </para>
 380
 381         <itemizedlist>
 382             <listitem>
 383                 <para>
 384                     <code>getDocblock($reflectionClass =
 385                         'Zend_Reflection_Docblock')</code>: retrieve the function
 386                     docblock reflection object.
 387                 </para>
 388             </listitem>
 389
 390             <listitem>
 391                 <para>
 392                     <code>getParameters($reflectionClass =
 393                         'Zend_Reflection_Parameter')</code>: retrieve an array of
 394                     all function parameter reflection objects.
 395                 </para>
 396             </listitem>
 397
 398             <listitem>
 399                 <para>
 400                     <methodname>getReturn()</methodname>: retrieve the return type reflection
 401                     object.
 402                 </para>
 403             </listitem>
 404         </itemizedlist>
 405     </sect2>
 406
 407     <sect2 id="zend.reflection.reference.method">
 408         <title>Zend_Reflection_Method</title>
 409
 410         <para>
 411             <classname>Zend_Reflection_Method</classname> mirrors
 412             <classname>Zend_Reflection_Function</classname>, and only overrides one
 413             additional method:
 414         </para>
 415
 416         <itemizedlist>
 417             <listitem>
 418                 <para>
 419                     <code>getParentClass($reflectionClass =
 420                         'Zend_Reflection_Class')</code>: retrieve the parent class
 421                     reflection object.
 422                 </para>
 423             </listitem>
 424         </itemizedlist>
 425     </sect2>
 426
 427     <sect2 id="zend.reflection.reference.parameter">
 428         <title>Zend_Reflection_Parameter</title>
 429
 430         <para>
 431             <classname>Zend_Reflection_Parameter</classname> adds a method for retrieving
 432             the parameter type, as well as overrides methods to allow specifying
 433             the reflection class to use on returned reflection objects.
 434         </para>
 435
 436         <itemizedlist>
 437             <listitem>
 438                 <para>
 439                     <code>getDeclaringClass($reflectionClass =
 440                         'Zend_Reflection_Class')</code>: get the declaring class of
 441                     the parameter as a reflection object (if available).
 442                 </para>
 443             </listitem>
 444
 445             <listitem>
 446                 <para>
 447                     <code>getClass($reflectionClass =
 448                         'Zend_Reflection_Class')</code>: get the class of
 449                     the parameter as a reflection object (if available).
 450                 </para>
 451             </listitem>
 452
 453             <listitem>
 454                 <para>
 455                     <code>getDeclaringFunction($reflectionClass =
 456                         'Zend_Reflection_Function')</code>: get the function of
 457                     the parameter as a reflection object (if available).
 458                 </para>
 459             </listitem>
 460
 461             <listitem>
 462                 <para>
 463                     <methodname>getType()</methodname>: get the parameter type.
 464                 </para>
 465             </listitem>
 466         </itemizedlist>
 467     </sect2>
 468
 469     <sect2 id="zend.reflection.reference.property">
 470         <title>Zend_Reflection_Property</title>
 471
 472         <para>
 473             <classname>Zend_Reflection_Property</classname> overrides a single method in
 474             order to allow specifying the returned reflection object class:
 475         </para>
 476
 477         <itemizedlist>
 478             <listitem>
 479                 <para>
 480                     <code>getDeclaringClass($reflectionClass =
 481                         'Zend_Reflection_Class')</code>: retrieve the declaring
 482                     class of the property as a reflection object.
 483                 </para>
 484             </listitem>
 485         </itemizedlist>
 486     </sect2>
 487 </sect1>