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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.codegenerator.reference">
   4     <title>Zend_CodeGenerator Reference</title>
   5
   6     <sect2 id="zend.codegenerator.reference.abstracts">
   7         <title>Abstract Classes and Interfaces</title>
   8
   9         <sect3 id="zend.codegenerator.reference.abstracts.abstract">
  10             <title>Zend_CodeGenerator_Abstract</title>
  11
  12             <para>
  13                 The base class from which all CodeGenerator classes inherit
  14                 provides the minimal functionality necessary. It's <acronym>API</acronym> is as
  15                 follows:
  16             </para>
  17
  18             <programlisting language="php"><![CDATA[
  19 abstract class Zend_CodeGenerator_Abstract
  20 {
  21     final public function __construct(Array $options = array())
  22     public function setOptions(Array $options)
  23     public function setSourceContent($sourceContent)
  24     public function getSourceContent()
  25     protected function _init()
  26     protected function _prepare()
  27     abstract public function generate();
  28     final public function __toString()
  29 }
  30 ]]></programlisting>
  31
  32             <para>
  33                 The constructor first calls <methodname>_init()</methodname> (which is left
  34                 empty for the concrete extending class to implement), then
  35                 passes the <varname>$options</varname> parameter to
  36                 <methodname>setOptions()</methodname>, and finally calls
  37                 <methodname>_prepare()</methodname> (again, to be implemented by an
  38                 extending class).
  39             </para>
  40
  41             <para>
  42                 Like most classes in Zend Framework, <methodname>setOptions()</methodname>
  43                 compares an option key to existing setters in the class, and
  44                 passes the value on to that method if found.
  45             </para>
  46
  47             <para>
  48                 <methodname>__toString()</methodname> is marked as final, and proxies to
  49                 <methodname>generate()</methodname>.
  50             </para>
  51
  52             <para>
  53                 <methodname>setSourceContent()</methodname> and
  54                 <methodname>getSourceContent()</methodname> are intended to either set the
  55                 default content for the code being generated, or to replace said
  56                 content once all generation tasks are complete.
  57             </para>
  58         </sect3>
  59
  60         <sect3 id="zend.codegenerator.reference.abstracts.php-abstract">
  61             <title>Zend_CodeGenerator_Php_Abstract</title>
  62
  63             <para>
  64                 <classname>Zend_CodeGenerator_Php_Abstract</classname> extends
  65                 <classname>Zend_CodeGenerator_Abstract</classname>, and adds some
  66                 properties for tracking whether content has changed as well as
  67                 the amount of indentation that should appear before generated
  68                 content. Its <acronym>API</acronym> is as follows:
  69             </para>
  70
  71             <programlisting language="php"><![CDATA[
  72 abstract class Zend_CodeGenerator_Php_Abstract
  73     extends Zend_CodeGenerator_Abstract
  74 {
  75     public function setSourceDirty($isSourceDirty = true)
  76     public function isSourceDirty()
  77     public function setIndentation($indentation)
  78     public function getIndentation()
  79 }
  80 ]]></programlisting>
  81         </sect3>
  82
  83         <sect3 id="zend.codegenerator.reference.abstracts.php-member-abstract">
  84             <title>Zend_CodeGenerator_Php_Member_Abstract</title>
  85
  86             <para>
  87                 <classname>Zend_CodeGenerator_Php_Member_Abstract</classname> is a base
  88                 class for generating class members -- properties and methods --
  89                 and provides accessors and mutators for establishing visibility;
  90                 whether or not the member is abstract, static, or final; and the
  91                 name of the member. Its <acronym>API</acronym> is as follows:
  92             </para>
  93
  94             <programlisting language="php"><![CDATA[
  95 abstract class Zend_CodeGenerator_Php_Member_Abstract
  96     extends Zend_CodeGenerator_Php_Abstract
  97 {
  98     public function setAbstract($isAbstract)
  99     public function isAbstract()
 100     public function setStatic($isStatic)
 101     public function isStatic()
 102     public function setVisibility($visibility)
 103     public function getVisibility()
 104     public function setName($name)
 105     public function getName()
 106 }
 107 ]]></programlisting>
 108         </sect3>
 109     </sect2>
 110
 111     <sect2 id="zend.codegenerator.reference.concrete">
 112         <title>Concrete CodeGenerator Classes</title>
 113
 114         <sect3 id="zend.codegenerator.reference.concrete.php-body">
 115             <title>Zend_CodeGenerator_Php_Body</title>
 116
 117             <para>
 118                 <classname>Zend_CodeGenerator_Php_Body</classname> is intended for
 119                 generating arbitrary procedural code to include within a file.
 120                 As such, you simply set content for the object, and it will
 121                 return that content when you invoke <methodname>generate()</methodname>.
 122             </para>
 123
 124             <para>
 125                 The <acronym>API</acronym> of the class is as follows:
 126             </para>
 127
 128             <programlisting language="php"><![CDATA[
 129 class Zend_CodeGenerator_Php_Body extends Zend_CodeGenerator_Php_Abstract
 130 {
 131     public function setContent($content)
 132     public function getContent()
 133     public function generate()
 134 }
 135 ]]></programlisting>
 136         </sect3>
 137
 138         <sect3 id="zend.codegenerator.reference.concrete.php-class">
 139             <title>Zend_CodeGenerator_Php_Class</title>
 140
 141             <para>
 142                 <classname>Zend_CodeGenerator_Php_Class</classname> is intended for
 143                 generating <acronym>PHP</acronym> classes. The basic functionality just generates
 144                 the <acronym>PHP</acronym> class itself, as well as optionally the related
 145                 <acronym>PHP</acronym> DocBlock. Classes may implement or inherit from other
 146                 classes, and may be marked as abstract. Utilizing other code generator
 147                 classes, you can also attach class constants, properties, and
 148                 methods.
 149             </para>
 150
 151             <para>
 152                 The <acronym>API</acronym> is as follows:
 153             </para>
 154
 155             <programlisting language="php"><![CDATA[
 156 class Zend_CodeGenerator_Php_Class extends Zend_CodeGenerator_Php_Abstract
 157 {
 158     public static function fromReflection(
 159         Zend_Reflection_Class $reflectionClass
 160     )
 161     public function setDocblock(Zend_CodeGenerator_Php_Docblock $docblock)
 162     public function getDocblock()
 163     public function setName($name)
 164     public function getName()
 165     public function setAbstract($isAbstract)
 166     public function isAbstract()
 167     public function setExtendedClass($extendedClass)
 168     public function getExtendedClass()
 169     public function setImplementedInterfaces(Array $implementedInterfaces)
 170     public function getImplementedInterfaces()
 171     public function setProperties(Array $properties)
 172     public function setProperty($property)
 173     public function getProperties()
 174     public function getProperty($propertyName)
 175     public function setMethods(Array $methods)
 176     public function setMethod($method)
 177     public function getMethods()
 178     public function getMethod($methodName)
 179     public function hasMethod($methodName)
 180     public function isSourceDirty()
 181     public function generate()
 182 }
 183 ]]></programlisting>
 184
 185             <para>
 186                 The <methodname>setProperty()</methodname> method accepts an array of
 187                 information that may be used to generate a
 188                 <classname>Zend_CodeGenerator_Php_Property</classname> instance -- or
 189                 simply an instance of
 190                 <classname>Zend_CodeGenerator_Php_Property</classname>.
 191                 Likewise, <methodname>setMethod()</methodname> accepts either an array of
 192                 information for generating a
 193                 <classname>Zend_CodeGenerator_Php_Method</classname> instance or a
 194                 concrete instance of that class.
 195             </para>
 196
 197             <para>
 198                 Note that <methodname>setDocBlock()</methodname> expects an instance of
 199                 <classname>Zend_CodeGenerator_Php_DocBlock</classname>.
 200             </para>
 201         </sect3>
 202
 203         <sect3 id="zend.codegenerator.reference.concrete.php-docblock">
 204             <title>Zend_CodeGenerator_Php_Docblock</title>
 205
 206             <para>
 207                 <classname>Zend_CodeGenerator_Php_Docblock</classname> can be used to
 208                 generate arbitrary <acronym>PHP</acronym> docblocks, including all the standard
 209                 docblock features: short and long descriptions and annotation
 210                 tags.
 211             </para>
 212
 213             <para>
 214                 Annotation tags may be set using the <methodname>setTag()</methodname> and
 215                 <methodname>setTags()</methodname> methods; these each take either an array
 216                 describing the tag that may be passed to the
 217                 <classname>Zend_CodeGenerator_Php_Docblock_Tag</classname> constructor, or
 218                 an instance of that class.
 219             </para>
 220
 221             <para>
 222                 The <acronym>API</acronym> is as follows:
 223             </para>
 224
 225             <programlisting language="php"><![CDATA[
 226 class Zend_CodeGenerator_Php_Docblock extends Zend_CodeGenerator_Php_Abstract
 227 {
 228     public static function fromReflection(
 229         Zend_Reflection_Docblock $reflectionDocblock
 230     )
 231     public function setShortDescription($shortDescription)
 232     public function getShortDescription()
 233     public function setLongDescription($longDescription)
 234     public function getLongDescription()
 235     public function setTags(Array $tags)
 236     public function setTag($tag)
 237     public function getTags()
 238     public function generate()
 239 }
 240 ]]></programlisting>
 241         </sect3>
 242
 243         <sect3 id="zend.codegenerator.reference.concrete.php-docblock-tag">
 244             <title>Zend_CodeGenerator_Php_Docblock_Tag</title>
 245
 246             <para>
 247                 <classname>Zend_CodeGenerator_Php_Docblock_Tag</classname> is intended for
 248                 creating arbitrary annotation tags for inclusion in <acronym>PHP</acronym>
 249                 docblocks. Tags are expected to contain a name (the portion
 250                 immediately following the '@' symbol) and a description
 251                 (everything following the tag name).
 252             </para>
 253
 254             <para>
 255                 The class <acronym>API</acronym> is as follows:
 256             </para>
 257
 258             <programlisting language="php"><![CDATA[
 259 class Zend_CodeGenerator_Php_Docblock_Tag
 260     extends Zend_CodeGenerator_Php_Abstract
 261 {
 262     public static function fromReflection(
 263         Zend_Reflection_Docblock_Tag $reflectionTag
 264     )
 265     public function setName($name)
 266     public function getName()
 267     public function setDescription($description)
 268     public function getDescription()
 269     public function generate()
 270 }
 271 ]]></programlisting>
 272         </sect3>
 273
 274         <sect3 id="zend.codegenerator.reference.concrete.php-docblock-tag-param">
 275             <title>Zend_CodeGenerator_Php_DocBlock_Tag_Param</title>
 276
 277             <para>
 278                 <classname>Zend_CodeGenerator_Php_DocBlock_Tag_Param</classname> is a
 279                 specialized version of
 280                 <classname>Zend_CodeGenerator_Php_DocBlock_Tag</classname>, and represents
 281                 a method parameter. The tag name is therefor known ("param"),
 282                 but due to the format of this annotation tag, additional
 283                 information is required in order to generate it: the parameter
 284                 name and data type it represents.
 285             </para>
 286
 287             <para>
 288                 The class <acronym>API</acronym> is as follows:
 289             </para>
 290
 291             <programlisting language="php"><![CDATA[
 292 class Zend_CodeGenerator_Php_Docblock_Tag_Param
 293     extends Zend_CodeGenerator_Php_Docblock_Tag
 294 {
 295     public static function fromReflection(
 296         Zend_Reflection_Docblock_Tag $reflectionTagParam
 297     )
 298     public function setDatatype($datatype)
 299     public function getDatatype()
 300     public function setParamName($paramName)
 301     public function getParamName()
 302     public function generate()
 303 }
 304 ]]></programlisting>
 305         </sect3>
 306
 307         <sect3 id="zend.codegenerator.reference.concrete.php-docblock-tag-return">
 308             <title>Zend_CodeGenerator_Php_DocBlock_Tag_Return</title>
 309
 310             <para>
 311                 Like the param docblock tag variant,
 312                 <classname>Zend_CodeGenerator_Php_Docblock_Tab_Return</classname> is an
 313                 annotation tag variant for representing a method return value.
 314                 In this case, the annotation tag name is known ("return"), but
 315                 requires a return type.
 316             </para>
 317
 318             <para>
 319                 The class <acronym>API</acronym> is as follows:
 320             </para>
 321
 322             <programlisting language="php"><![CDATA[
 323 class Zend_CodeGenerator_Php_Docblock_Tag_Param
 324     extends Zend_CodeGenerator_Php_Docblock_Tag
 325 {
 326     public static function fromReflection(
 327         Zend_Reflection_Docblock_Tag $reflectionTagReturn
 328     )
 329     public function setDatatype($datatype)
 330     public function getDatatype()
 331     public function generate()
 332 }
 333 ]]></programlisting>
 334         </sect3>
 335
 336         <sect3 id="zend.codegenerator.reference.concrete.php-file">
 337             <title>Zend_CodeGenerator_Php_File</title>
 338
 339             <para>
 340                 <classname>Zend_CodeGenerator_Php_File</classname> is used to generate
 341                 the full contents of a file that will contain <acronym>PHP</acronym> code. The file
 342                 may contain classes or arbitrary <acronym>PHP</acronym> code, as well as a
 343                 file-level docblock if desired.
 344             </para>
 345
 346             <para>
 347                 When adding classes to the file, you will need to pass either an
 348                 array of information to pass to the
 349                 <classname>Zend_CodeGenerator_Php_Class</classname> constructor, or an
 350                 instance of that class. Similarly, with docblocks, you will need
 351                 to pass information for the
 352                 <classname>Zend_CodeGenerator_Php_Docblock</classname> constructor to
 353                 consume or an instance of the class.
 354             </para>
 355
 356             <para>
 357                 The <acronym>API</acronym> of the class is as follows:
 358             </para>
 359
 360             <programlisting language="php"><![CDATA[
 361 class Zend_CodeGenerator_Php_File extends Zend_CodeGenerator_Php_Abstract
 362 {
 363     public static function fromReflectedFilePath(
 364         $filePath,
 365         $usePreviousCodeGeneratorIfItExists = true,
 366         $includeIfNotAlreadyIncluded = true)
 367     public static function fromReflection(Zend_Reflection_File $reflectionFile)
 368     public function setDocblock(Zend_CodeGenerator_Php_Docblock $docblock)
 369     public function getDocblock()
 370     public function setRequiredFiles($requiredFiles)
 371     public function getRequiredFiles()
 372     public function setClasses(Array $classes)
 373     public function getClass($name = null)
 374     public function setClass($class)
 375     public function setFilename($filename)
 376     public function getFilename()
 377     public function getClasses()
 378     public function setBody($body)
 379     public function getBody()
 380     public function isSourceDirty()
 381     public function generate()
 382 }
 383 ]]></programlisting>
 384         </sect3>
 385
 386         <sect3 id="zend.codegenerator.reference.concrete.php-member-container">
 387             <title>Zend_CodeGenerator_Php_Member_Container</title>
 388
 389             <para>
 390                 <classname>Zend_CodeGenerator_Php_Member_Container</classname> is used
 391                 internally by <classname>Zend_CodeGenerator_Php_Class</classname> to keep
 392                 track of class members -- properties and methods alike. These
 393                 are indexed by name, using the concrete instances of the members
 394                 as values.
 395             </para>
 396
 397             <para>
 398                 The <acronym>API</acronym> of the class is as follows:
 399             </para>
 400
 401             <programlisting language="php"><![CDATA[
 402 class Zend_CodeGenerator_Php_Member_Container extends ArrayObject
 403 {
 404     public function __construct($type = self::TYPE_PROPERTY)
 405 }
 406 ]]></programlisting>
 407         </sect3>
 408
 409         <sect3 id="zend.codegenerator.reference.concrete.php-method">
 410             <title>Zend_CodeGenerator_Php_Method</title>
 411
 412             <para>
 413                 <classname>Zend_CodeGenerator_Php_Method</classname> describes a class
 414                 method, and can generate both the code and the docblock for the
 415                 method. The visibility and status as static,
 416                 abstract, or final may be indicated, per its parent class,
 417                 <classname>Zend_CodeGenerator_Php_Member_Abstract</classname>. Finally,
 418                 the parameters and return value for the method may be specified.
 419             </para>
 420
 421             <para>
 422                 Parameters may be set using <methodname>setParameter()</methodname> or
 423                 <methodname>setParameters()</methodname>. In each case, a parameter should
 424                 either be an array of information to pass to the
 425                 <classname>Zend_CodeGenerator_Php_Parameter</classname> constructor or an
 426                 instance of that class.
 427             </para>
 428
 429             <para>
 430                 The <acronym>API</acronym> of the class is as follows:
 431             </para>
 432
 433             <programlisting language="php"><![CDATA[
 434 class Zend_CodeGenerator_Php_Method
 435     extends Zend_CodeGenerator_Php_Member_Abstract
 436 {
 437     public static function fromReflection(
 438         Zend_Reflection_Method $reflectionMethod
 439     )
 440     public function setDocblock(Zend_CodeGenerator_Php_Docblock $docblock)
 441     public function getDocblock()
 442     public function setFinal($isFinal)
 443     public function setParameters(Array $parameters)
 444     public function setParameter($parameter)
 445     public function getParameters()
 446     public function setBody($body)
 447     public function getBody()
 448     public function generate()
 449 }
 450 ]]></programlisting>
 451         </sect3>
 452
 453         <sect3 id="zend.codegenerator.reference.concrete.php-parameter">
 454             <title>Zend_CodeGenerator_Php_Parameter</title>
 455
 456             <para>
 457                 <classname>Zend_CodeGenerator_Php_Parameter</classname> may be used to
 458                 specify method parameters. Each parameter may have a position
 459                 (if unspecified, the order in which they are registered with the
 460                 method will be used), a default value, and a data type; a
 461                 parameter name is required.
 462             </para>
 463
 464             <para>
 465                 The <acronym>API</acronym> of the class is as follows:
 466             </para>
 467
 468             <programlisting language="php"><![CDATA[
 469 class Zend_CodeGenerator_Php_Parameter extends Zend_CodeGenerator_Php_Abstract
 470 {
 471     public static function fromReflection(
 472         Zend_Reflection_Parameter $reflectionParameter
 473     )
 474     public function setType($type)
 475     public function getType()
 476     public function setName($name)
 477     public function getName()
 478     public function setDefaultValue($defaultValue)
 479     public function getDefaultValue()
 480     public function setPosition($position)
 481     public function getPosition()
 482     public function getPassedByReference()
 483     public function setPassedByReference($passedByReference)
 484     public function generate()
 485 }
 486 ]]></programlisting>
 487
 488             <para>
 489                 There are several problems that might occur when trying to set
 490                 <constant>NULL</constant>, booleans or arrays as default values. For this the value
 491                 holder object <classname>Zend_CodeGenerator_Php_ParameterDefaultValue</classname>
 492                 can be used, for example:
 493             </para>
 494
 495             <programlisting language="php"><![CDATA[
 496 $parameter = new Zend_CodeGenerator_Php_Parameter();
 497 $parameter->setDefaultValue(
 498     new Zend_CodeGenerator_Php_Parameter_DefaultValue("null")
 499 );
 500 $parameter->setDefaultValue(
 501     new Zend_CodeGenerator_Php_Parameter_DefaultValue("array('foo', 'bar')")
 502 );
 503 ]]></programlisting>
 504
 505             <para>
 506                 Internally <methodname>setDefaultValue()</methodname> also converts the values
 507                 which can't be expressed in <acronym>PHP</acronym> into the value holder.
 508             </para>
 509         </sect3>
 510
 511         <sect3 id="zend.codegenerator.reference.concrete.php-property">
 512             <title>Zend_CodeGenerator_Php_Property</title>
 513
 514             <para>
 515                 <classname>Zend_CodeGenerator_Php_Property</classname> describes a class
 516                 property, which may be either a constant or a variable. In each
 517                 case, the property may have an optional default value associated
 518                 with it. Additionally, the visibility of variable properties may
 519                 be set, per the parent class,
 520                 <classname>Zend_CodeGenerator_Php_Member_Abstract</classname>.
 521             </para>
 522
 523             <para>
 524                 The <acronym>API</acronym> of the class is as follows:
 525             </para>
 526
 527             <programlisting language="php"><![CDATA[
 528 class Zend_CodeGenerator_Php_Property
 529     extends Zend_CodeGenerator_Php_Member_Abstract
 530 {
 531     public static function fromReflection(
 532         Zend_Reflection_Property $reflectionProperty
 533     )
 534     public function setConst($const)
 535     public function isConst()
 536     public function setDefaultValue($defaultValue)
 537     public function getDefaultValue()
 538     public function generate()
 539 }
 540 ]]></programlisting>
 541         </sect3>
 542     </sect2>
 543 </sect1>