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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.codegenerator.introduction">
   4     <title>Introduction</title>
   5
   6     <para>
   7         <classname>Zend_CodeGenerator</classname> provides facilities to generate
   8         arbitrary code using an object oriented interface, both to create new
   9         code as well as to update existing code. While the current
  10         implementation is limited to generating <acronym>PHP</acronym> code, you can easily extend
  11         the base class in order to provide code generation for other tasks:
  12         JavaScript, configuration files, apache vhosts, etc.
  13     </para>
  14
  15     <sect2 id="zend.codegenerator.introduction.theory">
  16         <title>Theory of Operation</title>
  17
  18         <para>
  19             In the most typical use case, you will simply instantiate a code
  20             generator class and either pass it the appropriate configuration or
  21             configure it after instantiation. To generate the code, you will
  22             simply echo the object or call its <methodname>generate()</methodname> method.
  23         </para>
  24
  25         <programlisting language="php"><![CDATA[
  26 // Passing configuration to the constructor:
  27 $file = new Zend_CodeGenerator_Php_File(array(
  28     'classes' => array(
  29         new Zend_CodeGenerator_Php_Class(array(
  30             'name'    => 'World',
  31             'methods' => array(
  32                 new Zend_CodeGenerator_Php_Method(array(
  33                     'name' => 'hello',
  34                     'body' => 'echo \'Hello world!\';',
  35                 )),
  36             ),
  37         )),
  38     )
  39 ));
  40
  41 // Configuring after instantiation
  42 $method = new Zend_CodeGenerator_Php_Method();
  43 $method->setName('hello')
  44        ->setBody('echo \'Hello world!\';');
  45
  46 $class = new Zend_CodeGenerator_Php_Class();
  47 $class->setName('World')
  48       ->setMethod($method);
  49
  50 $file = new Zend_CodeGenerator_Php_File();
  51 $file->setClass($class);
  52
  53 // Render the generated file
  54 echo $file;
  55
  56 // or write it to a file:
  57 file_put_contents('World.php', $file->generate());
  58 ]]></programlisting>
  59
  60         <para>
  61             Both of the above samples will render the same result:
  62         </para>
  63
  64         <programlisting language="php"><![CDATA[
  65 <?php
  66
  67 class World
  68 {
  69
  70     public function hello()
  71     {
  72         echo 'Hello world!';
  73     }
  74
  75 }
  76 ]]></programlisting>
  77
  78         <para>
  79             Another common use case is to update existing code -- for instance,
  80             to add a method to a class. In such a case, you must first inspect
  81             the existing code using reflection, and then add your new method.
  82             <classname>Zend_CodeGenerator</classname> makes this trivially simple, by
  83             leveraging <link linkend="zend.reflection">Zend_Reflection</link>.
  84         </para>
  85
  86         <para>
  87             As an example, let's say we've saved the above to the file
  88             "<filename>World.php</filename>", and have already included it. We could then do the
  89             following:
  90         </para>
  91
  92         <programlisting language="php"><![CDATA[
  93 $class = Zend_CodeGenerator_Php_Class::fromReflection(
  94     new Zend_Reflection_Class('World')
  95 );
  96
  97 $method = new Zend_CodeGenerator_Php_Method();
  98 $method->setName('mrMcFeeley')
  99        ->setBody('echo \'Hello, Mr. McFeeley!\';');
 100 $class->setMethod($method);
 101
 102 $file = new Zend_CodeGenerator_Php_File();
 103 $file->setClass($class);
 104
 105 // Render the generated file
 106 echo $file;
 107
 108 // Or, better yet, write it back to the original file:
 109 file_put_contents('World.php', $file->generate());
 110 ]]></programlisting>
 111
 112         <para>
 113             The resulting class file will now look like this:
 114         </para>
 115
 116         <programlisting language="php"><![CDATA[
 117 <?php
 118
 119 class World
 120 {
 121
 122     public function hello()
 123     {
 124         echo 'Hello world!';
 125     }
 126
 127     public function mrMcFeeley()
 128     {
 129         echo 'Hellow Mr. McFeeley!';
 130     }
 131
 132 }
 133 ]]></programlisting>
 134     </sect2>
 135 </sect1>