[Sommaire] [Imprimer]

   1  <?php
   2  //
   3  // Definition of eZPHPCreator class
   4  //
   5  // Created on: <28-Nov-2002 08:28:23 amos>
   6  //
   7  // SOFTWARE NAME: eZ publish
   8  // SOFTWARE RELEASE: 3.9.0
   9  // BUILD VERSION: 17785
  10  // COPYRIGHT NOTICE: Copyright (C) 1999-2006 eZ systems AS
  11  // SOFTWARE LICENSE: GNU General Public License v2.0
  12  // NOTICE: >
  13  //   This program is free software; you can redistribute it and/or
  14  //   modify it under the terms of version 2.0  of the GNU General
  15  //   Public License as published by the Free Software Foundation.
  16  //
  17  //   This program is distributed in the hope that it will be useful,
  18  //   but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  //   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  //   GNU General Public License for more details.
  21  //
  22  //   You should have received a copy of version 2.0 of the GNU General
  23  //   Public License along with this program; if not, write to the Free
  24  //   Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  25  //   MA 02110-1301, USA.
  26  //
  27  //
  28  
  29  /*! \file ezphpcreator.php
  30  */
  31  
  32  /*!
  33    \class eZPHPCreator ezphpcreator.php
  34    \ingroup eZUtils
  35    \brief eZPHPCreator provides a simple interface for creating and executing PHP code.
  36  
  37    To create PHP code you must create an instance of this class,
  38    add any number of elements you choose with
  39    addDefine(), addVariable(), addVariableUnset(), addVariableUnsetList(),
  40    addSpace(), addText(), addMethodCall(), addCodePiece(), addComment() and
  41    addInclude().
  42    After that you call store() to write all changes to disk.
  43  
  44  \code
  45  $php = new eZPHPCreator( 'cache', 'code.php' );
  46  
  47  $php->addComment( 'Auto generated' );
  48  $php->addInclude( 'inc.php' );
  49  $php->addVariable( 'count', 10 );
  50  
  51  $php->store();
  52  \endcode
  53  
  54    To restore PHP code you must create an instance of this class,
  55    check if you can restore it with canRestore() then restore variables with restore().
  56    The class will include PHP file and run all code, once the file is done it will
  57    catch any variables you require and return it to you.
  58  
  59  \code
  60  $php = new eZPHPCreator( 'cache', 'code.php' );
  61  
  62  if ( $php->canRestore() )
  63  {
  64      $variables = $php->restore( array( 'max_count' => 'count' ) );
  65      print( "Max count was " . $variables['max_count'] );
  66  }
  67  
  68  $php->close();
  69  \endcode
  70  
  71  */
  72  
  73  define( 'EZ_PHPCREATOR_VARIABLE', 1 );
  74  define( 'EZ_PHPCREATOR_SPACE', 2 );
  75  define( 'EZ_PHPCREATOR_TEXT', 3 );
  76  define( 'EZ_PHPCREATOR_METHOD_CALL', 4 );
  77  define( 'EZ_PHPCREATOR_CODE_PIECE', 5 );
  78  define( 'EZ_PHPCREATOR_EOL_COMMENT', 6 );
  79  define( 'EZ_PHPCREATOR_INCLUDE', 7 );
  80  define( 'EZ_PHPCREATOR_VARIABLE_UNSET', 8 );
  81  define( 'EZ_PHPCREATOR_DEFINE', 9 );
  82  define( 'EZ_PHPCREATOR_VARIABLE_UNSET_LIST', 10 );
  83  define( 'EZ_PHPCREATOR_RAW_VARIABLE', 11 );
  84  
  85  define( 'EZ_PHPCREATOR_VARIABLE_ASSIGNMENT', 1 );
  86  define( 'EZ_PHPCREATOR_VARIABLE_APPEND_TEXT', 2 );
  87  define( 'EZ_PHPCREATOR_VARIABLE_APPEND_ELEMENT', 3 );
  88  
  89  define( 'EZ_PHPCREATOR_INCLUDE_ONCE', 1 );
  90  define( 'EZ_PHPCREATOR_INCLUDE_ALWAYS', 2 );
  91  
  92  define( 'EZ_PPCREATOR_METHOD_CALL_PARAMETER_VALUE', 1 );
  93  define( 'EZ_PHPCREATOR_METHOD_CALL_PARAMETER_VARIABLE', 2 );
  94  
  95  class eZPHPCreator
  96  {
  97      /*!
  98       Initializes the creator with the directory path \a $dir and filename \a $file.
  99      */
 100      function eZPHPCreator( $dir, $file, $prefix = '', $options = array() )
 101      {
 102          $this->PHPDir = $dir;
 103          $this->PHPFile = $file;
 104          $this->FilePrefix = $prefix;
 105          $this->FileResource = false;
 106          $this->Elements = array();
 107          $this->TextChunks = array();
 108          $this->TemporaryCounter = 0;
 109          if ( isset( $options['spacing'] ) and ( $options['spacing'] == 'disabled') )
 110          {
 111              $this->Spacing = false;
 112          }
 113          else
 114          {
 115              $this->Spacing = true;
 116          }
 117  
 118          if ( isset( $options['clustering'] ) )
 119          {
 120              $this->ClusteringEnabled = true;
 121              $this->ClusterFileScope = $options['clustering'];
 122          }
 123          else
 124          {
 125              $this->ClusteringEnabled = false;
 126          }
 127      }
 128  
 129      //@{
 130  
 131      /*!
 132       Adds a new define statement to the code with the name \a $name and value \a $value.
 133       The parameter \a $caseSensitive determines if the define should be made case sensitive or not.
 134  
 135       Example:
 136       \code
 137  $php->addDefine( 'MY_CONSTANT', 5 );
 138       \endcode
 139  
 140       Would result in the PHP code.
 141  
 142       \code
 143  define( 'MY_CONSTANT', 5 );
 144       \endcode
 145  
 146       \param $parameters Optional parameters, can be any of the following:
 147              - \a spacing, The number of spaces to place before each code line, default is \c 0.
 148  
 149       \note \a $name must start with a letter or underscore, followed by any number of letters, numbers, or underscores.
 150             See http://php.net/manual/en/language.constants.php for more information.
 151       \sa http://php.net/manual/en/function.define.php
 152      */
 153      function addDefine( $name, $value, $caseSensitive = true, $parameters = array() )
 154      {
 155          $element = array( EZ_PHPCREATOR_DEFINE,
 156                            $name,
 157                            $value,
 158                            $caseSensitive,
 159                            $parameters );
 160          $this->Elements[] = $element;
 161      }
 162  
 163      /*!
 164       Adds a new raw variable tothe code with the name \a $name and value \a $value.
 165  
 166       Example:
 167       \code
 168  $php->addVariable( 'TransLationRoot', $cache['root'] );
 169       \endcode
 170  
 171       This function makes use of PHP's var_export() function which is optimized
 172       for this task.
 173      */
 174      function addRawVariable( $name, $value )
 175      {
 176          $element = array( EZ_PHPCREATOR_RAW_VARIABLE, $name, $value );
 177          $this->Elements[] = $element;
 178      }
 179  
 180      /*!
 181       Adds a new variable to the code with the name \a $name and value \a $value.
 182  
 183       Example:
 184       \code
 185  $php->addVariable( 'offset', 5  );
 186  $php->addVariable( 'text', 'some more text', EZ_PHPCREATOR_VARIABLE_APPEND_TEXT );
 187  $php->addVariable( 'array', 42, EZ_PHPCREATOR_VARIABLE_APPEND_ELEMENT );
 188       \endcode
 189  
 190       Would result in the PHP code.
 191  
 192       \code
 193  $offset = 5;
 194  $text .= 'some more text';
 195  $array[] = 42;
 196       \endcode
 197  
 198       \param $assignmentType Controls the way the value is assigned, choose one of the following:
 199              - \b EZ_PHPCREATOR_VARIABLE_ASSIGNMENT, assign using \c = (default)
 200              - \b EZ_PHPCREATOR_VARIABLE_APPEND_TEXT, append using text concat operator \c .
 201              - \b EZ_PHPCREATOR_VARIABLE_APPEND_ELEMENT, append element to array using append operator \c []
 202       \param $parameters Optional parameters, can be any of the following:
 203              - \a spacing, The number of spaces to place before each code line, default is \c 0.
 204              - \a full-tree, Whether to displays array values as one large expression (\c true) or
 205                              split it up into multiple variables (\c false)
 206  
 207      */
 208      function addVariable( $name, $value, $assignmentType = EZ_PHPCREATOR_VARIABLE_ASSIGNMENT,
 209                            $parameters = array() )
 210      {
 211          $element = array( EZ_PHPCREATOR_VARIABLE,
 212                            $name,
 213                            $value,
 214                            $assignmentType,
 215                            $parameters );
 216          $this->Elements[] = $element;
 217      }
 218  
 219      /*!
 220       Adds code to unset a variable with the name \a $name.
 221  
 222       Example:
 223       \code
 224  $php->addVariableUnset( 'offset' );
 225       \endcode
 226  
 227       Would result in the PHP code.
 228  
 229       \code
 230  unset( $offset );
 231       \endcode
 232  
 233       \param $parameters Optional parameters, can be any of the following:
 234              - \a spacing, The number of spaces to place before each code line, default is \c 0.
 235  
 236       \sa http://php.net/manual/en/function.unset.php
 237      */
 238      function addVariableUnset( $name,
 239                                 $parameters = array() )
 240      {
 241          $element = array( EZ_PHPCREATOR_VARIABLE_UNSET,
 242                            $name,
 243                            $parameters );
 244          $this->Elements[] = $element;
 245      }
 246  
 247      /*!
 248       Adds code to unset a list of variables with name from \a $list.
 249  
 250       Example:
 251       \code
 252  $php->addVariableUnsetList( array ( 'var1', 'var2' ) );
 253       \endcode
 254  
 255       Would result in the PHP code.
 256  
 257       \code
 258  unset( $var1, $var2 );
 259       \endcode
 260  
 261       \param $parameters Optional parameters, can be any of the following:
 262              - \a spacing, The number of spaces to place before each code line, default is \c 0.
 263  
 264       \sa http://php.net/manual/en/function.unset.php
 265      */
 266      function addVariableUnsetList( $list,
 267                                 $parameters = array() )
 268      {
 269          $element = array( EZ_PHPCREATOR_VARIABLE_UNSET_LIST,
 270                            $list,
 271                            $parameters );
 272          $this->Elements[] = $element;
 273      }
 274  
 275      /*!
 276       Adds some space to the code in form of newlines. The number of lines
 277       is controlled with \a $lines which is \c 1 by default.
 278       You can use this to get more readable PHP code.
 279  
 280       Example:
 281       \code
 282  $php->addSpace( 1 );
 283       \endcode
 284      */
 285      function addSpace( $lines = 1 )
 286      {
 287          $element = array( EZ_PHPCREATOR_SPACE,
 288                            $lines );
 289          $this->Elements[] = $element;
 290      }
 291  
 292      /*!
 293       Adds some plain text to the code. The text will be placed
 294       outside of PHP start and end markers and will in principle
 295       work as printing the text.
 296  
 297       Example:
 298       \code
 299  $php->addText( 'Print me!' );
 300       \endcode
 301      */
 302      function addText( $text )
 303      {
 304          $element = array( EZ_PHPCREATOR_TEXT,
 305                            $text );
 306          $this->Elements[] = $element;
 307      }
 308  
 309      /*!
 310       Adds code to call the method \a $methodName on the object named \a $objectName,
 311       \a $methodParameters should be an array with parameter entries where each entry contains:
 312       - \a 0, The parameter value
 313       - \a 1 (\em optional), The type of parameter, is one of:
 314         - \b EZ_PPCREATOR_METHOD_CALL_PARAMETER_VALUE, Use value directly (default if this entry is missing)
 315         - \b EZ_PHPCREATOR_METHOD_CALL_PARAMETER_VARIABLE, Use value as the name of the variable.
 316  
 317       Optionally the \a $returnValue parameter can be used to decide what should be done
 318       with the return value of the method call. It can either be \c false which means
 319       to do nothing or an array with the following entries.
 320       - \a 0, The name of the variable to assign the value to
 321       - \a 1 (\em optional), The type of assignment, uses the same value as addVariable().
 322  
 323       \param $parameters Optional parameters, can be any of the following:
 324              - \a spacing, The number of spaces to place before each code line, default is \c 0.
 325  
 326       Example:
 327       \code
 328  $php->addMethodCall( 'node', 'name', array(), array( 'name' ) );
 329  $php->addMethodCall( 'php', 'addMethodCall',
 330                       array( array( 'node' ), array( 'name' ) ) );
 331       \endcode
 332  
 333       Would result in the PHP code.
 334  
 335       \code
 336  $name = $node->name();
 337  $php->addMethodCall( 'node', 'name' );
 338       \endcode
 339      */
 340      function addMethodCall( $objectName, $methodName, $methodParameters, $returnValue = false, $parameters = array() )
 341      {
 342          $element = array( EZ_PHPCREATOR_METHOD_CALL,
 343                            $objectName,
 344                            $methodName,
 345                            $methodParameters,
 346                            $returnValue,
 347                            $parameters );
 348          $this->Elements[] = $element;
 349      }
 350  
 351      /*!
 352       Adds custom PHP code to the file, you should only use this a last resort if any
 353       of the other \em add functions done give you the required result.
 354  
 355       \param $code Contains the code as text, the text will not be modified (except for spacing).
 356                    This means that each expression must be ended with a newline even if it's just one.
 357       \param $parameters Optional parameters, can be any of the following:
 358              - \a spacing, The number of spaces to place before each code line, default is \c 0.
 359  
 360       Example:
 361       \code
 362  $php->addCodePiece( "if ( \$value > 2 )\n{\n    \$value = 2;\n}\n" );
 363       \endcode
 364  
 365       Would result in the PHP code.
 366  
 367       \code
 368  if ( $value > 2 )
 369  {
 370      $value = 2;
 371  }
 372       \endcode
 373  
 374      */
 375      function addCodePiece( $code, $parameters = array() )
 376      {
 377          $element = array( EZ_PHPCREATOR_CODE_PIECE,
 378                            $code,
 379                            $parameters );
 380          $this->Elements[] = $element;
 381      }
 382  
 383      /*!
 384       Adds a comment to the code, the comment will be display using multiple end-of-line
 385       comments (//), one for each newline in the text \a $comment.
 386  
 387       \param $eol Whether to add a newline at the last comment line
 388       \param $whitespaceHandling Whether to remove trailing whitespace from each line
 389       \param $parameters Optional parameters, can be any of the following:
 390              - \a spacing, The number of spaces to place before each code line, default is \c 0.
 391  
 392       Example:
 393       \code
 394  $php->addComment( "This file is auto generated\nDo not edit!" );
 395       \endcode
 396  
 397       Would result in the PHP code.
 398  
 399       \code
 400  // This file is auto generated
 401  // Do not edit!
 402       \endcode
 403  
 404      */
 405      function addComment( $comment, $eol = true, $whitespaceHandling = true, $parameters = array() )
 406      {
 407          $element = array( EZ_PHPCREATOR_EOL_COMMENT,
 408                            $comment,
 409                            array_merge( $parameters,
 410                                         array( 'eol' => $eol,
 411                                                'whitespace-handling' => $whitespaceHandling ) ) );
 412          $this->Elements[] = $element;
 413      }
 414  
 415      /*!
 416       Adds an include statement to the code, the file to include is \a $file.
 417  
 418       \param $type What type of include statement to use, can be one of the following:
 419                    - \b EZ_PHPCREATOR_INCLUDE_ONCE, use \em include_once()
 420                    - \b EZ_PHPCREATOR_INCLUDE_ALWAYS, use \em include()
 421       \param $parameters Optional parameters, can be any of the following:
 422              - \a spacing, The number of spaces to place before each code line, default is \c 0.
 423  
 424       Example:
 425       \code
 426  $php->addInclude( 'lib/ezutils/classes/ezphpcreator.php' );
 427       \endcode
 428  
 429       Would result in the PHP code.
 430  
 431       \code
 432  include_once( 'lib/ezutils/classes/ezphpcreator.php' );
 433       \endcode
 434  
 435      */
 436      function addInclude( $file, $type = EZ_PHPCREATOR_INCLUDE_ONCE, $parameters = array() )
 437      {
 438          $element = array( EZ_PHPCREATOR_INCLUDE,
 439                            $file,
 440                            $type,
 441                            $parameters );
 442          $this->Elements[] = $element;
 443      }
 444  
 445      //@}
 446  
 447      /*!
 448       \static
 449       Creates a variable statement with an assignment type and returns it.
 450       \param $variableName The name of the variable
 451       \param $assignmentType What kind of assignment to use, is one of the following;
 452                              - \b EZ_PHPCREATOR_VARIABLE_ASSIGNMENT, assign using \c =
 453                              - \b EZ_PHPCREATOR_VARIABLE_APPEND_TEXT, append to text using \c .
 454                              - \b EZ_PHPCREATOR_VARIABLE_APPEND_ELEMENT, append to array using \c []
 455       \param $variableParameters Optional parameters for the statement
 456              - \a is-reference, whether to do the assignment with reference or not (default is not)
 457      */
 458      function variableNameText( $variableName, $assignmentType, $variableParameters = array() )
 459      {
 460          $variableParameters = array_merge( array( 'is-reference' => false ),
 461                                             $variableParameters );
 462          $isReference = $variableParameters['is-reference'];
 463          $text = '$' . $variableName;
 464          if ( $assignmentType == EZ_PHPCREATOR_VARIABLE_ASSIGNMENT )
 465          {
 466              if ( $isReference )
 467                  $text .= ' =& ';
 468              else
 469                  $text .= ' = ';
 470          }
 471          else if ( $assignmentType == EZ_PHPCREATOR_VARIABLE_APPEND_TEXT )
 472          {
 473              $text .= ' .= ';
 474          }
 475          else if ( $assignmentType == EZ_PHPCREATOR_VARIABLE_APPEND_ELEMENT )
 476          {
 477              if ( $isReference )
 478                  $text .= '[] =& ';
 479              else
 480                  $text .= '[] = ';
 481          }
 482          return $text;
 483      }
 484  
 485      /*!
 486       Creates a text representation of the value \a $value which can
 487       be placed in files and be read back by a PHP parser as it was.
 488       The type of the values determines the output, it can be one of the following.
 489       - boolean, becomes \c true or \c false
 490       - null, becomes \c null
 491       - string, adds \ (backslash) to backslashes, double quotes, dollar signs and newlines.
 492                 Then wraps the whole string in " (double quotes).
 493       - numeric, displays the value as-is.
 494       - array, expands all value recursively using this function
 495       - object, creates a representation of an object creation if the object has \c serializeData implemented.
 496  
 497       \param $column Determines the starting column in which the text will be placed.
 498                      This is used for expanding arrays and objects which can span multiple lines.
 499       \param $iteration The current iteration, starts at 0 and increases with 1 for each recursive call
 500       \param $maxIterations The maximum number of iterations to allow, if the iteration
 501                             exceeds this the array or object will be split into multiple variables.
 502                             Can be set to \c false to the array or object as-is.
 503  
 504       \note This function can be called statically if \a $maxIterations is set to \c false
 505      */
 506      function variableText( $value, $column = 0, $iteration = 0, $maxIterations = 2 )
 507      {
 508          if ( isset( $this->Spacing) and !$this->Spacing )
 509          {
 510              return var_export( $value, true );
 511          }
 512  
 513          if ( is_bool( $value ) )
 514              $text = ( $value ? 'true' : 'false' );
 515          else if ( is_null( $value ) )
 516              $text = 'null';
 517          else if ( is_string( $value ) )
 518          {
 519              $valueText = str_replace( array( "\\",
 520                                               "\"",
 521                                               "\$",
 522                                               "\n" ),
 523                                        array( "\\\\",
 524                                               "\\\"",
 525                                               "\\$",
 526                                               "\\n" ),
 527                                        $value );
 528              $text = "\"$valueText\"";
 529          }
 530          else if ( is_numeric( $value ) )
 531              $text = $value;
 532          else if ( is_object( $value ) )
 533          {
 534              if ( $maxIterations !== false and
 535                   $iteration > $maxIterations )
 536              {
 537                  $temporaryVariableName = $this->temporaryVariableName( 'obj' );
 538                  $this->writeVariable( $temporaryVariableName, $value );
 539                  $text = '$' . $temporaryVariableName;
 540              }
 541              else
 542              {
 543                  $text = '';
 544                  if ( method_exists( $value, 'serializedata' ) )
 545                  {
 546                      $serializeData = $value->serializeData();
 547                      $className = $serializeData['class_name'];
 548                      $text = "new $className(";
 549  
 550                      $column += strlen( $text );
 551                      $parameters = $serializeData['parameters'];
 552                      $variables = $serializeData['variables'];
 553  
 554                      $i = 0;
 555                      foreach ( $parameters as $parameter )
 556                      {
 557                          if ( $i > 0 )
 558                          {
 559                              $text .= ",\n" . str_repeat( ' ', $column );
 560                          }
 561                          $variableName = $variables[$parameter];
 562                          $variableValue = $value->$variableName;
 563                          $keyText = " ";
 564                          /* It is also used statically sometimes, so we need to
 565                           * do this ugly hack */
 566                          if ( $this and ( get_class( $this ) == 'ezphpcreator' ) )
 567                          {
 568                              $text .= $keyText . $this->variableText( $variableValue, $column + strlen( $keyText  ), $iteration + 1, $maxIterations );
 569                          }
 570                          else
 571                          {
 572                              $text .= $keyText . eZPHPCreator::variableText( $variableValue, $column + strlen( $keyText  ), $iteration + 1, $maxIterations );
 573                          }
 574                          ++$i;
 575                      }
 576                      if ( $i > 0 )
 577                          $text .= ' ';
 578  
 579                      $text .= ')';
 580                  }
 581              }
 582          }
 583          else if ( is_array( $value ) )
 584          {
 585              if ( $maxIterations !== false and
 586                   $iteration > $maxIterations )
 587              {
 588                  $temporaryVariableName = $this->temporaryVariableName( 'arr' );
 589                  $this->writeVariable( $temporaryVariableName, $value );
 590                  $text = '$' . $temporaryVariableName;
 591              }
 592              else
 593              {
 594                  $text = 'array(';
 595                  $column += strlen( $text );
 596                  $valueKeys = array_keys( $value );
 597                  $isIndexed = true;
 598                  for ( $i = 0; $i < count( $valueKeys ); ++$i )
 599                  {
 600                      if ( $i !== $valueKeys[$i] )
 601                      {
 602                          $isIndexed = false;
 603                          break;
 604                      }
 605                  }
 606                  $i = 0;
 607                  foreach ( $valueKeys as $key )
 608                  {
 609                      if ( $i > 0 )
 610                      {
 611                          $text .= ",\n" . str_repeat( ' ', $column );
 612                      }
 613                      $element =& $value[$key];
 614                      $keyText = ' ';
 615                      if ( !$isIndexed )
 616                      {
 617                          if ( is_int( $key ) )
 618                              $keyText = $key;
 619                          else
 620                              $keyText = "\"" . str_replace( array( "\\",
 621                                                                    "\"",
 622                                                                    "\n" ),
 623                                                             array( "\\\\",
 624                                                                    "\\\"",
 625                                                                    "\\n" ),
 626                                                             $key ) . "\"";
 627                          $keyText = " $keyText => ";
 628                      }
 629                      /* It is also used statically sometimes, so we need to do
 630                       * this ugly hack */
 631                      if ( $this and ( get_class( $this ) == 'ezphpcreator' ) )
 632                      {
 633                          $text .= $keyText . $this->variableText( $element, $column + strlen( $keyText  ), $iteration + 1, $maxIterations );
 634                      }
 635                      else
 636                      {
 637                          $text .= $keyText . eZPHPCreator::variableText( $element, $column + strlen( $keyText  ), $iteration + 1, $maxIterations );
 638                      }
 639                      ++$i;
 640                  }
 641                  if ( $i > 0 )
 642                      $text .= ' ';
 643                  $text .= ')';
 644              }
 645          }
 646          else
 647              $text = 'null';
 648          return $text;
 649      }
 650  
 651      /*!
 652       \static
 653       Splits \a $text into multiple lines using \a $splitString for splitting.
 654       For each line it will prepend the string \a $spacingString n times as specified by \a $spacing.
 655  
 656       It will try to be smart and not do anything when \a $spacing is set to \c 0.
 657  
 658       \param $skipEmptyLines If \c true it will not prepend the string for empty lines.
 659       \param $spacing Must be a positive number, \c 0 means to not prepend anything.
 660      */
 661      function prependSpacing( $text, $spacing, $skipEmptyLines = true, $spacingString = " ", $splitString = "\n" )
 662      {
 663          if ( $spacing == 0 or !$this->Spacing )
 664              return $text;
 665          $textArray = explode( $splitString, $text );
 666          $newTextArray = array();
 667          foreach ( $textArray as $text )
 668          {
 669              if ( trim( $text ) != '' and $this->Spacing )
 670                  $textLine = str_repeat( $spacingString, $spacing ) . $text;
 671              else
 672                  $textLine = $text;
 673              $newTextArray[] = $textLine;
 674          }
 675          return implode( $splitString, $newTextArray );
 676      }
 677  
 678      //@{
 679  
 680      /*!
 681       Opens the file for writing and sets correct file permissions.
 682       \return The current file resource or \c false if it failed to open the file.
 683       \note The file name and path is supplied to the constructor of this class.
 684       \note Multiple calls to this method will only open the file once.
 685      */
 686      function open( $atomic = false )
 687      {
 688          // VS-DBFILE
 689  
 690          if ( $this->ClusteringEnabled )
 691              return true;
 692  
 693          if ( !$this->FileResource )
 694          {
 695              if ( !file_exists( $this->PHPDir ) )
 696              {
 697                  include_once ( 'lib/ezfile/classes/ezdir.php' );
 698                  $ini =& eZINI::instance();
 699                  $perm = octdec( $ini->variable( 'FileSettings', 'StorageDirPermissions' ) );
 700                  eZDir::mkdir( $this->PHPDir, $perm, true );
 701              }
 702              $path = $this->PHPDir . '/' . $this->PHPFile;
 703              $oldumask = umask( 0 );
 704              $pathExisted = file_exists( $path );
 705              if ( $atomic )
 706              {
 707                  $this->isAtomic = true;
 708                  $this->requestedFilename = $path;
 709                  $uniqid = md5( uniqid( "ezp". getmypid(), true ) );
 710                  $path .= ".$uniqid";
 711                  $this->tmpFilename = $path;
 712              }
 713              $ini =& eZINI::instance();
 714              $perm = octdec( $ini->variable( 'FileSettings', 'StorageFilePermissions' ) );
 715              $this->FileResource = @fopen( $this->FilePrefix . $path, "w" );
 716              if ( !$this->FileResource )
 717                  eZDebug::writeError( "Could not open file '$path' for writing, perhaps wrong permissions" );
 718              if ( $this->FileResource and
 719                   !$pathExisted )
 720                  chmod( $path, $perm );
 721              umask( $oldumask );
 722          }
 723          return $this->FileResource;
 724      }
 725  
 726      /*!
 727       Closes the currently open file if any.
 728      */
 729      function close()
 730      {
 731          // VS-DBFILE
 732  
 733          if ( $this->ClusteringEnabled )
 734              return;
 735  
 736          if ( $this->FileResource )
 737          {
 738              fclose( $this->FileResource );
 739  
 740              if ( $this->isAtomic )
 741              {
 742                  include_once ( 'lib/ezfile/classes/ezfile.php' );
 743                  eZFile::rename( $this->tmpFilename, $this->requestedFilename );
 744              }
 745              $this->FileResource = false;
 746          }
 747      }
 748  
 749      /*!
 750       \return \c true if the file and path already exists.
 751       \note The file name and path is supplied to the constructor of this class.
 752      */
 753      function exists()
 754      {
 755          $path = $this->PHPDir . '/' . $this->PHPFile;
 756          if ( !$this->ClusteringEnabled )
 757              return file_exists( $path );
 758  
 759          // VS-DBFILE
 760  
 761          require_once ( 'kernel/classes/ezclusterfilehandler.php' );
 762          $fileHandler = eZClusterFileHandler::instance();
 763          return $fileHandler->fileExists( $path );
 764      }
 765  
 766      /*!
 767       \return \c true if file exists and can be restored.
 768       \param $timestamp The timestamp to check the modification time of the file against,
 769                         if the modification time is larger or equal to \a $timestamp
 770                         the file can be restored. Otherwise the file is considered too old.
 771       \note The file name and path is supplied to the constructor of this class.
 772      */
 773      function canRestore( $timestamp = false )
 774      {
 775          // VS-DBFILE
 776  
 777          $path = $this->PHPDir . '/' . $this->PHPFile;
 778  
 779          if ( $this->ClusteringEnabled )
 780          {
 781              require_once ( 'kernel/classes/ezclusterfilehandler.php' );
 782              $file = eZClusterFileHandler::instance( $path );
 783              $canRestore= $file->exists();
 784  
 785              if ( $timestamp !== false and $canRestore )
 786              {
 787                  $cacheModifierTime = $file->mtime();
 788                  $canRestore = ( $cacheModifierTime >= $timestamp );
 789              }
 790  
 791              return $canRestore;
 792          }
 793  
 794          $canRestore = file_exists( $path );
 795          if ( $timestamp !== false and
 796               $canRestore )
 797          {
 798              $cacheModifierTime = filemtime( $path );
 799              $canRestore = ( $cacheModifierTime >= $timestamp );
 800          }
 801  
 802          return $canRestore;
 803      }
 804  
 805      /*!
 806       Tries to restore the PHP file and fetch the defined variables in \a $variableDefinitions.
 807       This basically means including the file using include().
 808  
 809       \param $variableDefinitions Associative array with the return variable name being the key
 810                                   matched variable as value.
 811  
 812       \return An associatve array with the variables that were found according to \a $variableDefinitions.
 813  
 814       Example:
 815       \code
 816  $values = $php->restore( array( 'MyValue' => 'node' ) );
 817  print( $values['MyValue'] );
 818       \endcode
 819  
 820       \note The file name and path is supplied to the constructor of this class.
 821      */
 822      function restore( $variableDefinitions )
 823      {
 824          // VS-DBFILE
 825  
 826          $returnVariables = array();
 827          $path = $this->PHPDir . '/' . $this->PHPFile;
 828  
 829          if ( !$this->ClusteringEnabled )
 830              include( $path );
 831          else
 832          {
 833              require_once ( 'kernel/classes/ezclusterfilehandler.php' );
 834              $file = eZClusterFileHandler::instance( $path );
 835              if ( $file->exists() )
 836              {
 837                  $file->fetch();
 838                  include( $path );
 839                  $file->deleteLocal();
 840              }
 841          }
 842  
 843          foreach ( $variableDefinitions as $variableReturnName => $variableName )
 844          {
 845              $variableRequired = true;
 846              $variableDefault = false;
 847              if ( is_array( $variableName ) )
 848              {
 849                  $variableDefinition = $variableName;
 850                  $variableName = $variableDefinition['name'];
 851                  $variableRequired = $variableDefinition['required'];
 852                  if ( isset( $variableDefinition['default'] ) )
 853                      $variableDefault = $variableDefinition['default'];
 854              }
 855              if ( isset( ${$variableName} ) )
 856              {
 857                  $returnVariables[$variableReturnName] = ${$variableName};
 858              }
 859              else if ( $variableRequired )
 860                  eZDebug::writeError( "Variable '$variableName' is not present in cache '$path'",
 861                                       'eZPHPCreator::restore' );
 862              else
 863                  $returnVariables[$variableReturnName] = $variableDefault;
 864          }
 865          return $returnVariables;
 866      }
 867  
 868      /*!
 869       Stores the PHP cache, returns false if the cache file could not be created.
 870      */
 871      function store( $atomic = false )
 872      {
 873          if ( $this->open( $atomic ) )
 874          {
 875              $this->write( "<?php\n" );
 876  
 877              $this->writeElements();
 878  
 879              $this->write( "?>\n" );
 880  
 881              $this->writeChunks();
 882              $this->flushChunks();
 883              $this->close();
 884  
 885              // Write log message to storage.log
 886              include_once ( 'lib/ezutils/classes/ezlog.php' );
 887              eZLog::writeStorageLog( $this->PHPFile, $this->PHPDir . '/' );
 888              return true;
 889          }
 890          else
 891          {
 892              eZDebug::writeError( "Failed to open file '" . $this->PHPDir . '/' . $this->PHPFile . "'",
 893                                   'eZPHPCreator::store' );
 894              return false;
 895          }
 896      }
 897  
 898      /*!
 899       Creates a text string out of all elements and returns it.
 900       \note Calling this multiple times will resulting text processing each time.
 901      */
 902      function fetch( $addPHPMarkers = true )
 903      {
 904          if ( $addPHPMarkers )
 905              $this->write( "<?php\n" );
 906          $this->writeElements();
 907          if ( $addPHPMarkers )
 908              $this->write( "?>\n" );
 909  
 910          $text = implode( '', $this->TextChunks );
 911  
 912          $this->flushChunks();
 913  
 914          return $text;
 915      }
 916  
 917      //@}
 918  
 919      /*!
 920       \private
 921      */
 922      function writeChunks()
 923      {
 924          // VS-DBFILE
 925  
 926          $count = count( $this->TextChunks );
 927  
 928          if ( $this->ClusteringEnabled )
 929          {
 930              $text = '';
 931              for ( $i = 0; $i < $count; ++$i )
 932                  $text .= $this->TextChunks[$i];
 933  
 934              $filePath = $this->FilePrefix . $this->PHPDir . '/' . $this->PHPFile;
 935  
 936              require_once ( 'kernel/classes/ezclusterfilehandler.php' );
 937              $fileHandler = eZClusterFileHandler::instance();
 938              $fileHandler->fileStoreContents( $filePath, $text, $this->ClusterFileScope, 'php' );
 939  
 940              return;
 941          }
 942  
 943          for ( $i = 0; $i < $count; ++$i )
 944          {
 945              $text = $this->TextChunks[$i];
 946              fwrite( $this->FileResource, $text );
 947          }
 948      }
 949  
 950      /*!
 951       \private
 952      */
 953      function flushChunks()
 954      {
 955          $this->TextChunks = array();
 956      }
 957  
 958      /*!
 959       \private
 960      */
 961      function write( $text )
 962      {
 963          $this->TextChunks[] = $text;
 964      }
 965  
 966      /*!
 967       \private
 968      */
 969      function writeElements()
 970      {
 971          $count = count( $this->Elements );
 972          for ( $i = 0; $i < $count; ++$i )
 973          {
 974              $element =& $this->Elements[$i];
 975              if ( $element[0] == EZ_PHPCREATOR_DEFINE )
 976              {
 977                  $this->writeDefine( $element );
 978              }
 979              else if ( $element[0] == EZ_PHPCREATOR_RAW_VARIABLE )
 980              {
 981                  $this->writeRawVariable( $element[1], $element[2] );
 982              }
 983              else if ( $element[0] == EZ_PHPCREATOR_VARIABLE )
 984              {
 985                  $this->writeVariable( $element[1], $element[2], $element[3], $element[4] );
 986              }
 987              else if ( $element[0] == EZ_PHPCREATOR_VARIABLE_UNSET )
 988              {
 989                  $this->writeVariableUnset( $element );
 990              }
 991              else if ( $element[0] == EZ_PHPCREATOR_VARIABLE_UNSET_LIST )
 992              {
 993                  $this->writeVariableUnsetList( $element );
 994              }
 995              else if ( $element[0] == EZ_PHPCREATOR_SPACE )
 996              {
 997                  $this->writeSpace( $element );
 998              }
 999              else if ( $element[0] == EZ_PHPCREATOR_TEXT )
1000              {
1001                  $this->writeText( $element );
1002              }
1003              else if ( $element[0] == EZ_PHPCREATOR_METHOD_CALL )
1004              {
1005                  $this->writeMethodCall( $element );
1006              }
1007              else if ( $element[0] == EZ_PHPCREATOR_CODE_PIECE )
1008              {
1009                  $this->writeCodePiece( $element );
1010              }
1011              else if ( $element[0] == EZ_PHPCREATOR_EOL_COMMENT )
1012              {
1013                  $this->writeComment( $element );
1014              }
1015              else if ( $element[0] == EZ_PHPCREATOR_INCLUDE )
1016              {
1017                  $this->writeInclude( $element );
1018              }
1019          }
1020      }
1021  
1022      /*!
1023       \private
1024      */
1025      function writeDefine( $element )
1026      {
1027          $name = $element[1];
1028          $value = $element[2];
1029          $caseSensitive = $element[3];
1030          $parameters = $element[4];
1031          $text = '';
1032          if ( $this->Spacing )
1033          {
1034              $spacing = 0;
1035              if ( isset( $parameters['spacing'] ) )
1036                  $spacing = $parameters['spacing'];
1037              $text = str_repeat( ' ', $spacing );
1038          }
1039          $nameText = $this->variableText( $name, 0 );
1040          $valueText = $this->variableText( $value, 0 );
1041          $text .= "define( $nameText, $valueText";
1042          if ( !$caseSensitive )
1043              $text .= ", true";
1044          $text .= " );\n";
1045          $this->write( $text );
1046      }
1047  
1048      /*!
1049       \private
1050      */
1051      function writeInclude( $element )
1052      {
1053          $includeFile = $element[1];
1054          $includeType = $element[2];
1055          $parameters = $element[3];
1056          if ( $includeType == EZ_PHPCREATOR_INCLUDE_ONCE )
1057              $includeName = 'include_once';
1058          else if ( $includeType == EZ_PHPCREATOR_INCLUDE_ALWAYS )
1059              $includeName = 'include';
1060          $includeFileText = $this->variableText( $includeFile, 0 );
1061          $text = "$includeName( $includeFileText );\n";
1062          if ( $this->Spacing )
1063          {
1064              $spacing = 0;
1065              if ( isset( $parameters['spacing'] ) )
1066                  $spacing = $parameters['spacing'];
1067              $text = str_repeat( ' ', $spacing ) . $text;
1068          }
1069          $this->write( $text );
1070      }
1071  
1072      /*!
1073       \private
1074      */
1075      function writeComment( $element )
1076      {
1077          $elementAttributes = $element[2];
1078          $spacing = 0;
1079          if ( isset( $elementAttributes['spacing'] ) and $this->Spacing )
1080              $spacing = $elementAttributes['spacing'];
1081          $whitespaceHandling = $elementAttributes['whitespace-handling'];
1082          $eol = $elementAttributes['eol'];
1083          $newCommentArray = array();
1084          $commentArray = explode( "\n", $element[1] );
1085          foreach ( $commentArray as $comment )
1086          {
1087              $textLine = '// ' . $comment;
1088              if ( $whitespaceHandling )
1089              {
1090                  $textLine = rtrim( $textLine );
1091                  $textLine = str_replace( "\t", '    ', $textLine );
1092              }
1093              $textLine = str_repeat( ' ', $spacing ) . $textLine;
1094              $newCommentArray[] = $textLine;
1095          }
1096          $text = implode( "\n", $newCommentArray );
1097          if ( $eol )
1098              $text .= "\n";
1099          $this->write( $text );
1100      }
1101  
1102      /*!
1103       \private
1104      */
1105      function writeSpace( $element )
1106      {
1107          $text = str_repeat( "\n", $element[1] );
1108          $this->write( $text );
1109      }
1110  
1111      /*!
1112       \private
1113      */
1114      function writeCodePiece( $element )
1115      {
1116          $code = $element[1];
1117          $parameters = $element[2];
1118          $spacing = 0;
1119          if ( isset( $parameters['spacing'] ) and $this->Spacing )
1120              $spacing = $parameters['spacing'];
1121          $text = eZPHPCreator::prependSpacing( $code, $spacing );
1122          $this->write( $text );
1123      }
1124  
1125      /*!
1126       \private
1127      */
1128      function writeText( $element )
1129      {
1130          $text = $element[1];
1131          $this->write( "\n?>" );
1132          $this->write( $text );
1133          $this->write( "<?php\n" );
1134      }
1135  
1136      /*!
1137       \private
1138      */
1139      function writeMethodCall( $element )
1140      {
1141          $objectName = $element[1];
1142          $methodName = $element[2];
1143          $parameters = $element[3];
1144          $returnValue = $element[4];
1145          $parameters = $element[5];
1146          $text = '';
1147          $spacing = 0;
1148          if ( isset( $parameters['spacing'] ) and $this->Spacing )
1149              $spacing = $parameters['spacing'];
1150          if ( is_array( $returnValue ) )
1151          {
1152              $variableName = $returnValue[0];
1153              $assignmentType = EZ_PHPCREATOR_VARIABLE_ASSIGNMENT;
1154              if ( isset( $variableValue[1] ) )
1155                  $assignmentType = $variableValue[1];
1156              $text = $this->variableNameText( $variableName, $assignmentType );
1157          }
1158          $text .= '$' . $objectName . '->' . $methodName . '(';
1159          $column = strlen( $text );
1160          $i = 0;
1161          foreach ( $parameters as $parameterData )
1162          {
1163              if ( $i > 0 )
1164                  $text .= ",\n" . str_repeat( ' ', $column );
1165              $parameterType = EZ_PHPCREATOR_METHOD_CALL_PARAMETER_VALUE;
1166              $parameterValue = $parameterData[0];
1167              if ( isset( $parameterData[1] ) )
1168                  $parameterType = $parameterData[1];
1169              if ( $parameterType == EZ_PHPCREATOR_METHOD_CALL_PARAMETER_VALUE )
1170                   $text .= ' ' . $this->variableText( $parameterValue, $column + 1 );
1171              else if ( $parameterType == EZ_PHPCREATOR_METHOD_CALL_PARAMETER_VARIABLE )
1172                  $text .= ' $' . $parameterValue;
1173              ++$i;
1174          }
1175          if ( $i > 0 )
1176              $text .= ' ';
1177          $text .= ");\n";
1178          $text = eZPHPCreator::prependSpacing( $text, $spacing );
1179          $this->write( $text );
1180      }
1181  
1182      /*!
1183       \private
1184      */
1185      function writeVariableUnset( $element )
1186      {
1187          $variableName = $element[1];
1188          $parameters = $element[2];
1189          $spacing = 0;
1190          if ( isset( $parameters['spacing'] ) and $this->Spacing )
1191              $spacing = $parameters['spacing'];
1192          $text = "unset( \$$variableName );\n";
1193          $text = eZPHPCreator::prependSpacing( $text, $spacing );
1194          $this->write( $text );
1195      }
1196  
1197      /*!
1198       \private
1199      */
1200      function writeVariableUnsetList( $element )
1201      {
1202          $variableNames = $element[1];
1203  
1204          if ( count( $variableNames ) )
1205          {
1206              $parameters = $element[2];
1207              $spacing = 0;
1208              if ( isset( $parameters['spacing'] ) and $this->Spacing )
1209                  $spacing = $parameters['spacing'];
1210              $text = 'unset( ';
1211              array_walk( $variableNames, create_function( '&$variableName,$key', '$variableName = "\$" . $variableName;') );
1212              $text .= join( ', ', $variableNames );
1213              $text .= " );\n";
1214              $text = eZPHPCreator::prependSpacing( $text, $spacing );
1215              $this->write( $text );
1216          }
1217      }
1218  
1219      /*!
1220       \private
1221      */
1222      function writeRawVariable( $variableName, $variableValue )
1223      {
1224          $this->write( "\${$variableName} = ". var_export( $variableValue, true). ";\n" );
1225      }
1226  
1227      /*!
1228       \private
1229      */
1230      function writeVariable( $variableName, $variableValue, $assignmentType = EZ_PHPCREATOR_VARIABLE_ASSIGNMENT,
1231                              $variableParameters = array() )
1232      {
1233          $variableParameters = array_merge( array( 'full-tree' => false,
1234                                                    'spacing' => 0 ),
1235                                             $variableParameters );
1236          $fullTree = $variableParameters['full-tree'];
1237          $spacing = $this->Spacing ? $variableParameters['spacing'] : 0;
1238          $text = $this->variableNameText( $variableName, $assignmentType, $variableParameters );
1239          $maxIterations = 2;
1240          if ( $fullTree )
1241              $maxIterations = false;
1242          $text .= $this->variableText( $variableValue, strlen( $text ), 0, $maxIterations );
1243          $text .= ";\n";
1244          $text = eZPHPCreator::prependSpacing( $text, $spacing );
1245          $this->write( $text );
1246      }
1247  
1248      /*!
1249       \private
1250      */
1251      function temporaryVariableName( $prefix )
1252      {
1253          $temporaryCounter =& $this->TemporaryCounter;
1254          $variableName = $prefix . '_' . $temporaryCounter;
1255          ++$temporaryCounter;
1256          return $variableName;
1257      }
1258  
1259      /// \privatesection
1260      var $PHPDir;
1261      var $PHPFile;
1262      var $FileResource;
1263      var $Elements;
1264      var $TextChunks;
1265      var $isAtomic;
1266      var $tmpFilename;
1267      var $requestedFilename;
1268      var $Spacing = true;
1269      var $ClusteringEnabled = false;
1270      var $ClusterFileScope  = false;
1271  }
1272  ?>