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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.codegenerator.examples">
   4     <title>Zend_CodeGenerator Examples</title>
   5
   6     <example id="zend.codegenerator.examples.class">
   7         <title>Generating PHP classes</title>
   8
   9         <para>
  10             The following example generates an empty class with a class-level
  11             DocBlock.
  12         </para>
  13
  14         <programlisting language="php"><![CDATA[
  15 $foo      = new Zend_CodeGenerator_Php_Class();
  16 $docblock = new Zend_CodeGenerator_Php_Docblock(array(
  17     'shortDescription' => 'Sample generated class',
  18     'longDescription'  => 'This is a class generated with Zend_CodeGenerator.',
  19     'tags'             => array(
  20         array(
  21             'name'        => 'version',
  22             'description' => '$Rev:$',
  23         ),
  24         array(
  25             'name'        => 'license',
  26             'description' => 'New BSD',
  27         ),
  28     ),
  29 ));
  30 $foo->setName('Foo')
  31     ->setDocblock($docblock);
  32 echo $foo->generate();
  33 ]]></programlisting>
  34
  35         <para>
  36             The above code will result in the following:
  37         </para>
  38
  39         <programlisting language="php"><![CDATA[
  40 /**
  41  * Sample generated class
  42  *
  43  * This is a class generated with Zend_CodeGenerator.
  44  *
  45  * @version $Rev:$
  46  * @license New BSD
  47  *
  48  */
  49 class Foo
  50 {
  51
  52 }
  53 ]]></programlisting>
  54     </example>
  55
  56     <example id="zend.codegenerator.examples.class-properties">
  57         <title>Generating PHP classes with class properties</title>
  58
  59         <para>
  60             Building on the previous example, we now add properties to our
  61             generated class.
  62         </para>
  63
  64         <programlisting language="php"><![CDATA[
  65 $foo      = new Zend_CodeGenerator_Php_Class();
  66 $docblock = new Zend_CodeGenerator_Php_Docblock(array(
  67     'shortDescription' => 'Sample generated class',
  68     'longDescription'  => 'This is a class generated with Zend_CodeGenerator.',
  69     'tags'             => array(
  70         array(
  71             'name'        => 'version',
  72             'description' => '$Rev:$',
  73         ),
  74         array(
  75             'name'        => 'license',
  76             'description' => 'New BSD',
  77         ),
  78     ),
  79 ));
  80 $foo->setName('Foo')
  81     ->setDocblock($docblock)
  82     ->setProperties(array(
  83         array(
  84             'name'         => '_bar',
  85             'visibility'   => 'protected',
  86             'defaultValue' => 'baz',
  87         ),
  88         array(
  89             'name'         => 'baz',
  90             'visibility'   => 'public',
  91             'defaultValue' => 'bat',
  92         ),
  93         array(
  94             'name'         => 'bat',
  95             'const'        => true,
  96             'defaultValue' => 'foobarbazbat',
  97         ),
  98     ));
  99 echo $foo->generate();
 100 ]]></programlisting>
 101
 102         <para>
 103             The above results in the following class definition:
 104         </para>
 105
 106         <programlisting language="php"><![CDATA[
 107 /**
 108  * Sample generated class
 109  *
 110  * This is a class generated with Zend_CodeGenerator.
 111  *
 112  * @version $Rev:$
 113  * @license New BSD
 114  *
 115  */
 116 class Foo
 117 {
 118
 119     protected $_bar = 'baz';
 120
 121     public $baz = 'bat';
 122
 123     const bat = 'foobarbazbat';
 124
 125 }
 126 ]]></programlisting>
 127     </example>
 128
 129     <example id="zend.codegenerator.examples.class-methods">
 130         <title>Generating PHP classes with class methods</title>
 131
 132         <para>
 133             <classname>Zend_CodeGenerator_Php_Class</classname> allows you to attach
 134             methods with optional content to your classes. Methods may be
 135             attached as either arrays or concrete
 136             <classname>Zend_CodeGenerator_Php_Method</classname> instances.
 137         </para>
 138
 139         <programlisting language="php"><![CDATA[
 140 $foo      = new Zend_CodeGenerator_Php_Class();
 141 $docblock = new Zend_CodeGenerator_Php_Docblock(array(
 142     'shortDescription' => 'Sample generated class',
 143     'longDescription'  => 'This is a class generated with Zend_CodeGenerator.',
 144     'tags'             => array(
 145         array(
 146             'name'        => 'version',
 147             'description' => '$Rev:$',
 148         ),
 149         array(
 150             'name'        => 'license',
 151             'description' => 'New BSD',
 152         ),
 153     ),
 154 ));
 155 $foo->setName('Foo')
 156     ->setDocblock($docblock)
 157     ->setProperties(array(
 158         array(
 159             'name'         => '_bar',
 160             'visibility'   => 'protected',
 161             'defaultValue' => 'baz',
 162         ),
 163         array(
 164             'name'         => 'baz',
 165             'visibility'   => 'public',
 166             'defaultValue' => 'bat',
 167         ),
 168         array(
 169             'name'         => 'bat',
 170             'const'        => true,
 171             'defaultValue' => 'foobarbazbat',
 172         ),
 173     ))
 174     ->setMethods(array(
 175         // Method passed as array
 176         array(
 177             'name'       => 'setBar',
 178             'parameters' => array(
 179                 array('name' => 'bar'),
 180             ),
 181             'body'       => '$this->_bar = $bar;' . "\n" . 'return $this;',
 182             'docblock'   => new Zend_CodeGenerator_Php_Docblock(array(
 183                 'shortDescription' => 'Set the bar property',
 184                 'tags'             => array(
 185                     new Zend_CodeGenerator_Php_Docblock_Tag_Param(array(
 186                         'paramName' => 'bar',
 187                         'datatype'  => 'string'
 188                     )),
 189                     new Zend_CodeGenerator_Php_Docblock_Tag_Return(array(
 190                         'datatype'  => 'string',
 191                     )),
 192                 ),
 193             )),
 194         ),
 195         // Method passed as concrete instance
 196         new Zend_CodeGenerator_Php_Method(array(
 197             'name' => 'getBar',
 198             'body'       => 'return $this->_bar;',
 199             'docblock'   => new Zend_CodeGenerator_Php_Docblock(array(
 200                 'shortDescription' => 'Retrieve the bar property',
 201                 'tags'             => array(
 202                     new Zend_CodeGenerator_Php_Docblock_Tag_Return(array(
 203                         'datatype'  => 'string|null',
 204                     )),
 205                 ),
 206             )),
 207         )),
 208     ));
 209
 210 echo $foo->generate();
 211 ]]></programlisting>
 212
 213         <para>
 214             The above generates the following output:
 215         </para>
 216
 217         <programlisting language="php"><![CDATA[
 218 /**
 219  * Sample generated class
 220  *
 221  * This is a class generated with Zend_CodeGenerator.
 222  *
 223  * @version $Rev:$
 224  * @license New BSD
 225  */
 226 class Foo
 227 {
 228
 229     protected $_bar = 'baz';
 230
 231     public $baz = 'bat';
 232
 233     const bat = 'foobarbazbat';
 234
 235     /**
 236      * Set the bar property
 237      *
 238      * @param string bar
 239      * @return string
 240      */
 241     public function setBar($bar)
 242     {
 243         $this->_bar = $bar;
 244         return $this;
 245     }
 246
 247     /**
 248      * Retrieve the bar property
 249      *
 250      * @return string|null
 251      */
 252     public function getBar()
 253     {
 254         return $this->_bar;
 255     }
 256
 257 }
 258 ]]></programlisting>
 259     </example>
 260
 261     <example id="zend.codegenerator.examples.file">
 262         <title>Generating PHP files</title>
 263
 264         <para>
 265             <classname>Zend_CodeGenerator_Php_File</classname> can be used to generate the
 266             contents of a <acronym>PHP</acronym> file. You can include classes as well as arbitrary
 267             content body. When attaching classes, you should attach either
 268             concrete <classname>Zend_CodeGenerator_Php_Class</classname> instances or an
 269             array defining the class.
 270         </para>
 271
 272         <para>
 273             In the example below, we will assume you've defined
 274             <varname>$foo</varname> per one of the class definitions in a previous
 275             example.
 276         </para>
 277
 278         <programlisting language="php"><![CDATA[
 279 $file = new Zend_CodeGenerator_Php_File(array(
 280     'classes'  => array($foo);
 281     'docblock' => new Zend_CodeGenerator_Php_Docblock(array(
 282         'shortDescription' => 'Foo class file',
 283         'tags'             => array(
 284             array(
 285                 'name'        => 'license',
 286                 'description' => 'New BSD',
 287             ),
 288         ),
 289     )),
 290     'body'     => 'define(\'APPLICATION_ENV\', \'testing\');',
 291 ));
 292 ]]></programlisting>
 293
 294         <para>
 295             Calling <methodname>generate()</methodname> will generate the code -- but not
 296             write it to a file. You will need to capture the contents and write
 297             them to a file yourself. As an example:
 298         </para>
 299
 300         <programlisting language="php"><![CDATA[
 301 $code = $file->generate();
 302 file_put_contents('Foo.php', $code);
 303 ]]></programlisting>
 304
 305         <para>
 306             The above will generate the following file:
 307         </para>
 308
 309         <programlisting language="php"><![CDATA[
 310 <?php
 311 /**
 312  * Foo class file
 313  *
 314  * @license New BSD
 315  */
 316
 317 /**
 318  * Sample generated class
 319  *
 320  * This is a class generated with Zend_CodeGenerator.
 321  *
 322  * @version $Rev:$
 323  * @license New BSD
 324  */
 325 class Foo
 326 {
 327
 328     protected $_bar = 'baz';
 329
 330     public $baz = 'bat';
 331
 332     const bat = 'foobarbazbat';
 333
 334     /**
 335      * Set the bar property
 336      *
 337      * @param string bar
 338      * @return string
 339      */
 340     public function setBar($bar)
 341     {
 342         $this->_bar = $bar;
 343         return $this;
 344     }
 345
 346     /**
 347      * Retrieve the bar property
 348      *
 349      * @return string|null
 350      */
 351     public function getBar()
 352     {
 353         return $this->_bar;
 354     }
 355
 356 }
 357
 358 define('APPLICATION_ENV', 'testing');
 359 ]]></programlisting>
 360     </example>
 361
 362     <example id="zend.codegenerator.examples.reflection-file">
 363         <title>Seeding PHP file code generation via reflection</title>
 364
 365         <para>
 366             You can add <acronym>PHP</acronym> code to an existing <acronym>PHP</acronym> file
 367             using the code generator. To do so, you need to first do reflection on it. The
 368             static method <methodname>fromReflectedFileName()</methodname> allows you to do
 369             this.
 370         </para>
 371
 372         <programlisting language="php"><![CDATA[
 373 $generator = Zend_CodeGenerator_Php_File::fromReflectedFileName($path);
 374 $body = $generator->getBody();
 375 $body .= "\n\$foo->bar();";
 376 file_put_contents($path, $generator->generate());
 377 ]]></programlisting>
 378     </example>
 379
 380     <example id="zend.codegenerator.examples.reflection-class">
 381         <title>Seeding PHP class generation via reflection</title>
 382
 383         <para>
 384             You may add code to an existing class. To do so, first use the
 385             static <methodname>fromReflection()</methodname> method to map the class into a
 386             generator object. From there, you may add additional properties or
 387             methods, and then regenerate the class.
 388         </para>
 389
 390         <programlisting language="php"><![CDATA[
 391 $generator = Zend_CodeGenerator_Php_Class::fromReflection(
 392     new Zend_Reflection_Class($class)
 393 );
 394 $generator->setMethod(array(
 395     'name'       => 'setBaz',
 396     'parameters' => array(
 397         array('name' => 'baz'),
 398     ),
 399     'body'       => '$this->_baz = $baz;' . "\n" . 'return $this;',
 400     'docblock'   => new Zend_CodeGenerator_Php_Docblock(array(
 401         'shortDescription' => 'Set the baz property',
 402         'tags'             => array(
 403             new Zend_CodeGenerator_Php_Docblock_Tag_Param(array(
 404                 'paramName' => 'baz',
 405                 'datatype'  => 'string'
 406             )),
 407             new Zend_CodeGenerator_Php_Docblock_Tag_Return(array(
 408                 'datatype'  => 'string',
 409             )),
 410         ),
 411     )),
 412 ));
 413 $code = $generator->generate();
 414 ]]></programlisting>
 415     </example>
 416 </sect1>