[Sommaire] [Imprimer]

   1  <?php
   2  /*
   3   * Session Management for PHP3
   4   *
   5   * (C) Copyright 1999-2000 NetUSE GmbH
   6   *                    Kristian Koehntopp
   7   *
   8   * $Id: template.class.php,v 1.6 2003/06/06 19:09:50 dhaun Exp $
   9   *
  10   */
  11  
  12  /*
  13   * Change log since version 7.2c
  14   *
  15   * Bug fixes to version 7.2c compiled by Richard Archer <rha@juggernaut.com.au>:
  16   * (credits given to first person to post a diff to phplib mailing list)
  17   *
  18   * Normalised all comments and whitespace (rha)
  19   * replaced "$handle" with "$varname" and "$h" with "$v" throughout (from phplib-devel)
  20   * added braces around all one-line if statements in: get_undefined, loadfile and halt (rha)
  21   * set_var was missing two sets of braces (rha)
  22   * added a couple of "return true" statements (rha)
  23   * set_unknowns had "keep" as default instead of "remove" (from phplib-devel)
  24   * set_file failed to check for empty strings if passed an array of filenames (phplib-devel)
  25   * remove @ from call to preg_replace in subst -- report errors if there are any (NickM)
  26   * set_block unnecessarily required a newline in the template file (Marc Tardif)
  27   * pparse now calls this->finish to replace undefined vars (Layne Weathers)
  28   * get_var now checks for unset varnames (NickM & rha)
  29   * get_var when passed an array used the array key instead of the value (rha)
  30   * get_vars now uses a call to get_var rather than this->varvals to prevent undefined var warning (rha)
  31   * in finish, the replacement string referenced an unset variable (rha)
  32   * loadfile would try to load a file if the varval had been set to "" (rha)
  33   * in get_undefined, only match non-whitespace in variable tags as in finish (Layne Weathers & rha)
  34   * more elegant fix to the problem of subst stripping '$n', '\n' and '\\' strings (rha)
  35   *
  36   *
  37   * Changes in functionality which go beyond bug fixes:
  38   *
  39   * changed debug handling so set, get and internals can be tracked separately (rha)
  40   * added debug statements throughout to track most function calls (rha)
  41   * debug output contained raw HTML -- is now escaped with htmlentities (rha)
  42   * Alter regex in set_block to remove more whitespace around BEGIN/END tags to improve HTML layout (rha)
  43   * Add "append" option to set_var, works just like append in parse (dale at linuxwebpro.com, rha)
  44   * Altered parse so that append is honored if passed an array (Brian)
  45   * Converted comments and documentation to phpdoc style (rha)
  46   * Added clear_var to set the value of variables to "" (rha)
  47   * Added unset_var to usset variables (rha)
  48   *
  49   */
  50  
  51  /**
  52   * The template class allows you to keep your HTML code in some external files
  53   * which are completely free of PHP code, but contain replacement fields.
  54   * The class provides you with functions which can fill in the replacement fields
  55   * with arbitrary strings. These strings can become very large, e.g. entire tables.
  56   *
  57   * Note: If you think that this is like FastTemplates, read carefully. It isn't.
  58   *
  59   */
  60  
  61  class Template
  62  {
  63   /**
  64    * Serialization helper, the name of this class.
  65    *
  66    * @var       string
  67    * @access    public
  68    */
  69    var $classname = "Template";
  70  
  71   /**
  72    * Determines how much debugging output Template will produce.
  73    * This is a bitwise mask of available debug levels:
  74    * 0 = no debugging
  75    * 1 = debug variable assignments
  76    * 2 = debug calls to get variable
  77    * 4 = debug internals (outputs all function calls with parameters).
  78    *
  79    * Note: setting $this->debug = true will enable debugging of variable
  80    * assignments only which is the same behaviour as versions up to release 7.2d.
  81    *
  82    * @var       int
  83    * @access    public
  84    */
  85    var $debug    = false;
  86  
  87   /**
  88    * The base directory from which template files are loaded.
  89    *
  90    * @var       string
  91    * @access    private
  92    * @see       set_root
  93    */
  94    var $root     = ".";
  95  
  96   /**
  97    * A hash of strings forming a translation table which translates variable names
  98    * into names of files containing the variable content.
  99    * $file[varname] = "filename";
 100    *
 101    * @var       array
 102    * @access    private
 103    * @see       set_file
 104    */
 105    var $file     = array();
 106  
 107   /**
 108    * A hash of strings forming a translation table which translates variable names
 109    * into regular expressions for themselves.
 110    * $varkeys[varname] = "/varname/"
 111    *
 112    * @var       array
 113    * @access    private
 114    * @see       set_var
 115    */
 116    var $varkeys  = array();
 117  
 118   /**
 119    * A hash of strings forming a translation table which translates variable names
 120    * into values for their respective varkeys.
 121    * $varvals[varname] = "value"
 122    *
 123    * @var       array
 124    * @access    private
 125    * @see       set_var
 126    */
 127    var $varvals  = array();
 128  
 129   /**
 130    * Determines how to output variable tags with no assigned value in templates.
 131    *
 132    * @var       string
 133    * @access    private
 134    * @see       set_unknowns
 135    */
 136    var $unknowns = "remove";
 137  
 138   /**
 139    * Determines how Template handles error conditions.
 140    * "yes"      = the error is reported, then execution is halted
 141    * "report"   = the error is reported, then execution continues by returning "false"
 142    * "no"       = errors are silently ignored, and execution resumes reporting "false"
 143    *
 144    * @var       string
 145    * @access    public
 146    * @see       halt
 147    */
 148    var $halt_on_error  = "yes";
 149  
 150   /**
 151    * The last error message is retained in this variable.
 152    *
 153    * @var       string
 154    * @access    public
 155    * @see       halt
 156    */
 157    var $last_error     = "";
 158  
 159   /******************************************************************************
 160    * Class constructor. May be called with two optional parameters.
 161    * The first parameter sets the template directory the second parameter
 162    * sets the policy regarding handling of unknown variables.
 163    *
 164    * usage: Template([string $root = "."], [string $unknowns = "remove"])
 165    *
 166    * @param     $root        path to template directory
 167    * @param     $string      what to do with undefined variables
 168    * @see       set_root
 169    * @see       set_unknowns
 170    * @access    public
 171    * @return    void
 172    */
 173    function Template($root = ".", $unknowns = "remove") {
 174      if ($this->debug & 4) {
 175        echo "<p><b>Template:</b> root = $root, unknowns = $unknowns</p>\n";
 176      }
 177      $this->set_root($root);
 178      $this->set_unknowns($unknowns);
 179    }
 180  
 181  
 182   /******************************************************************************
 183    * Checks that $root is a valid directory and if so sets this directory as the
 184    * base directory from which templates are loaded by storing the value in
 185    * $this->root. Relative filenames are prepended with the path in $this->root.
 186    *
 187    * Returns true on success, false on error.
 188    *
 189    * usage: set_root(string $root)
 190    *
 191    * @param     $root         string containing new template directory
 192    * @see       root
 193    * @access    public
 194    * @return    boolean
 195    */
 196    function set_root($root) {
 197      if ($this->debug & 4) {
 198        echo "<p><b>set_root:</b> root = $root</p>\n";
 199      }
 200      if (substr ($root, -1) == '/') {
 201        $root = substr ($root, 0, -1);
 202      }
 203      if (!is_dir($root)) {
 204        $this->halt("set_root: $root is not a directory.");
 205        return false;
 206      }
 207  
 208      $this->root = $root;
 209      return true;
 210    }
 211  
 212  
 213   /******************************************************************************
 214    * Sets the policy for dealing with unresolved variable names.
 215    *
 216    * unknowns defines what to do with undefined template variables
 217    * "remove"   = remove undefined variables
 218    * "comment"  = replace undefined variables with comments
 219    * "keep"     = keep undefined variables
 220    *
 221    * Note: "comment" can cause unexpected results when the variable tag is embedded
 222    * inside an HTML tag, for example a tag which is expected to be replaced with a URL.
 223    *
 224    * usage: set_unknowns(string $unknowns)
 225    *
 226    * @param     $unknowns         new value for unknowns
 227    * @see       unknowns
 228    * @access    public
 229    * @return    void
 230    */
 231    function set_unknowns($unknowns = "remove") {
 232      if ($this->debug & 4) {
 233        echo "<p><b>unknowns:</b> unknowns = $unknowns</p>\n";
 234      }
 235      $this->unknowns = $unknowns;
 236    }
 237  
 238  
 239   /******************************************************************************
 240    * Defines a filename for the initial value of a variable.
 241    *
 242    * It may be passed either a varname and a file name as two strings or
 243    * a hash of strings with the key being the varname and the value
 244    * being the file name.
 245    *
 246    * The new mappings are stored in the array $this->file.
 247    * The files are not loaded yet, but only when needed.
 248    *
 249    * Returns true on success, false on error.
 250    *
 251    * usage: set_file(array $filelist = (string $varname => string $filename))
 252    * or
 253    * usage: set_file(string $varname, string $filename)
 254    *
 255    * @param     $varname      either a string containing a varname or a hash of varname/file name pairs.
 256    * @param     $filename     if varname is a string this is the filename otherwise filename is not required
 257    * @access    public
 258    * @return    boolean
 259    */
 260    function set_file($varname, $filename = "") {
 261      if (!is_array($varname)) {
 262        if ($this->debug & 4) {
 263          echo "<p><b>set_file:</b> (with scalar) varname = $varname, filename = $filename</p>\n";
 264        }
 265        if ($filename == "") {
 266          $this->halt("set_file: For varname $varname filename is empty.");
 267          return false;
 268        }
 269        $this->file[$varname] = $this->filename($filename);
 270      } else {
 271        reset($varname);
 272        while(list($v, $f) = each($varname)) {
 273          if ($this->debug & 4) {
 274            echo "<p><b>set_file:</b> (with array) varname = $v, filename = $f</p>\n";
 275          }
 276          if ($f == "") {
 277            $this->halt("set_file: For varname $v filename is empty.");
 278            return false;
 279          }
 280          $this->file[$v] = $this->filename($f);
 281        }
 282      }
 283      return true;
 284    }
 285  
 286  
 287   /******************************************************************************
 288    * A variable $parent may contain a variable block defined by:
 289    * &lt;!-- BEGIN $varname --&gt; content &lt;!-- END $varname --&gt;. This function removes
 290    * that block from $parent and replaces it with a variable reference named $name.
 291    * The block is inserted into the varkeys and varvals hashes. If $name is
 292    * omitted, it is assumed to be the same as $varname.
 293    *
 294    * Blocks may be nested but care must be taken to extract the blocks in order
 295    * from the innermost block to the outermost block.
 296    *
 297    * Returns true on success, false on error.
 298    *
 299    * usage: set_block(string $parent, string $varname, [string $name = ""])
 300    *
 301    * @param     $parent       a string containing the name of the parent variable
 302    * @param     $varname      a string containing the name of the block to be extracted
 303    * @param     $name         the name of the variable in which to store the block
 304    * @access    public
 305    * @return    boolean
 306    */
 307    function set_block($parent, $varname, $name = "") {
 308      if ($this->debug & 4) {
 309        echo "<p><b>set_block:</b> parent = $parent, varname = $varname, name = $name</p>\n";
 310      }
 311      if (!$this->loadfile($parent)) {
 312        $this->halt("set_block: unable to load $parent.");
 313        return false;
 314      }
 315      if ($name == "") {
 316        $name = $varname;
 317      }
 318  
 319      $str = $this->get_var($parent);
 320      $reg = "/[ \t]*<!--\s+BEGIN $varname\s+-->\s*?\n?(\s*.*?\n?)\s*<!--\s+END $varname\s+-->\s*?\n?/sm";
 321      preg_match_all($reg, $str, $m);
 322      $str = preg_replace($reg, "{" . "$name}", $str);
 323      $this->set_var($varname, $m[1][0]);
 324      $this->set_var($parent, $str);
 325      return true;
 326    }
 327  
 328  
 329   /******************************************************************************
 330    * This functions sets the value of a variable.
 331    *
 332    * It may be called with either a varname and a value as two strings or an
 333    * an associative array with the key being the varname and the value being
 334    * the new variable value.
 335    *
 336    * The function inserts the new value of the variable into the $varkeys and
 337    * $varvals hashes. It is not necessary for a variable to exist in these hashes
 338    * before calling this function.
 339    *
 340    * An optional third parameter allows the value for each varname to be appended
 341    * to the existing variable instead of replacing it. The default is to replace.
 342    * This feature was introduced after the 7.2d release.
 343    *
 344    *
 345    * usage: set_var(string $varname, [string $value = ""], [boolean $append = false])
 346    * or
 347    * usage: set_var(array $varname = (string $varname => string $value), [mixed $dummy_var], [boolean $append = false])
 348    *
 349    * @param     $varname      either a string containing a varname or a hash of varname/value pairs.
 350    * @param     $value        if $varname is a string this contains the new value for the variable otherwise this parameter is ignored
 351    * @param     $append       if true, the value is appended to the variable's existing value
 352    * @access    public
 353    * @return    void
 354    */
 355    function set_var($varname, $value = "", $append = false) {
 356      if (!is_array($varname)) {
 357        if (!empty($varname)) {
 358          if ($this->debug & 1) {
 359            printf("<b>set_var:</b> (with scalar) <b>%s</b> = '%s'<br>\n", $varname, htmlentities($value));
 360          }
 361          $this->varkeys[$varname] = "/".$this->varname($varname)."/";
 362          if ($append && isset($this->varvals[$varname])) {
 363            $this->varvals[$varname] .= $value;
 364          } else {
 365            $this->varvals[$varname] = $value;
 366          }
 367        }
 368      } else {
 369        reset($varname);
 370        while(list($k, $v) = each($varname)) {
 371          if (!empty($k)) {
 372            if ($this->debug & 1) {
 373              printf("<b>set_var:</b> (with array) <b>%s</b> = '%s'<br>\n", $k, htmlentities($v));
 374            }
 375            $this->varkeys[$k] = "/".$this->varname($k)."/";
 376            if ($append && isset($this->varvals[$k])) {
 377              $this->varvals[$k] .= $v;
 378            } else {
 379              $this->varvals[$k] = $v;
 380            }
 381          }
 382        }
 383      }
 384    }
 385  
 386  
 387   /******************************************************************************
 388    * This functions clears the value of a variable.
 389    *
 390    * It may be called with either a varname as a string or an array with the 
 391    * values being the varnames to be cleared.
 392    *
 393    * The function sets the value of the variable in the $varkeys and $varvals 
 394    * hashes to "". It is not necessary for a variable to exist in these hashes
 395    * before calling this function.
 396    *
 397    *
 398    * usage: clear_var(string $varname)
 399    * or
 400    * usage: clear_var(array $varname = (string $varname))
 401    *
 402    * @param     $varname      either a string containing a varname or an array of varnames.
 403    * @access    public
 404    * @return    void
 405    */
 406    function clear_var($varname) {
 407      if (!is_array($varname)) {
 408        if (!empty($varname)) {
 409          if ($this->debug & 1) {
 410            printf("<b>clear_var:</b> (with scalar) <b>%s</b><br>\n", $varname);
 411          }
 412          $this->set_var($varname, "");
 413        }
 414      } else {
 415        reset($varname);
 416        while(list($k, $v) = each($varname)) {
 417          if (!empty($v)) {
 418            if ($this->debug & 1) {
 419              printf("<b>clear_var:</b> (with array) <b>%s</b><br>\n", $v);
 420            }
 421            $this->set_var($v, "");
 422          }
 423        }
 424      }
 425    }
 426  
 427  
 428   /******************************************************************************
 429    * This functions unsets a variable completely.
 430    *
 431    * It may be called with either a varname as a string or an array with the 
 432    * values being the varnames to be cleared.
 433    *
 434    * The function removes the variable from the $varkeys and $varvals hashes.
 435    * It is not necessary for a variable to exist in these hashes before calling
 436    * this function.
 437    *
 438    *
 439    * usage: unset_var(string $varname)
 440    * or
 441    * usage: unset_var(array $varname = (string $varname))
 442    *
 443    * @param     $varname      either a string containing a varname or an array of varnames.
 444    * @access    public
 445    * @return    void
 446    */
 447    function unset_var($varname) {
 448      if (!is_array($varname)) {
 449        if (!empty($varname)) {
 450          if ($this->debug & 1) {
 451            printf("<b>unset_var:</b> (with scalar) <b>%s</b><br>\n", $varname);
 452          }
 453          unset($this->varkeys[$varname]);
 454          unset($this->varvals[$varname]);
 455        }
 456      } else {
 457        reset($varname);
 458        while(list($k, $v) = each($varname)) {
 459          if (!empty($v)) {
 460            if ($this->debug & 1) {
 461              printf("<b>unset_var:</b> (with array) <b>%s</b><br>\n", $v);
 462            }
 463            unset($this->varkeys[$v]);
 464            unset($this->varvals[$v]);
 465          }
 466        }
 467      }
 468    }
 469  
 470  
 471   /******************************************************************************
 472    * This function fills in all the variables contained within the variable named
 473    * $varname. The resulting value is returned as the function result and the
 474    * original value of the variable varname is not changed. The resulting string
 475    * is not "finished", that is, the unresolved variable name policy has not been
 476    * applied yet.
 477    *
 478    * Returns: the value of the variable $varname with all variables substituted.
 479    *
 480    * usage: subst(string $varname)
 481    *
 482    * @param     $varname      the name of the variable within which variables are to be substituted
 483    * @access    public
 484    * @return    string
 485    */
 486    function subst($varname) {
 487      $varvals_quoted = array();
 488      if ($this->debug & 4) {
 489        echo "<p><b>subst:</b> varname = $varname</p>\n";
 490      }
 491      if (!$this->loadfile($varname)) {
 492        $this->halt("subst: unable to load $varname.");
 493        return false;
 494      }
 495  
 496      // quote the replacement strings to prevent bogus stripping of special chars
 497      reset($this->varvals);
 498      while(list($k, $v) = each($this->varvals)) {
 499        $varvals_quoted[$k] = preg_replace(array('/\\\\/', '/\$/'), array('\\\\\\\\', '\\\\$'), $v);
 500      }
 501  
 502      $str = $this->get_var($varname);
 503      $str = preg_replace($this->varkeys, $varvals_quoted, $str);
 504      return $str;
 505    }
 506  
 507  
 508   /******************************************************************************
 509    * This is shorthand for print $this->subst($varname). See subst for further
 510    * details.
 511    *
 512    * Returns: always returns false.
 513    *
 514    * usage: psubst(string $varname)
 515    *
 516    * @param     $varname      the name of the variable within which variables are to be substituted
 517    * @access    public
 518    * @return    false
 519    * @see       subst
 520    */
 521    function psubst($varname) {
 522      if ($this->debug & 4) {
 523        echo "<p><b>psubst:</b> varname = $varname</p>\n";
 524      }
 525      print $this->subst($varname);
 526  
 527      return false;
 528    }
 529  
 530  
 531   /******************************************************************************
 532    * The function substitutes the values of all defined variables in the variable
 533    * named $varname and stores or appends the result in the variable named $target.
 534    *
 535    * It may be called with either a target and a varname as two strings or a
 536    * target as a string and an array of variable names in varname.
 537    *
 538    * The function inserts the new value of the variable into the $varkeys and
 539    * $varvals hashes. It is not necessary for a variable to exist in these hashes
 540    * before calling this function.
 541    *
 542    * An optional third parameter allows the value for each varname to be appended
 543    * to the existing target variable instead of replacing it. The default is to
 544    * replace.
 545    *
 546    * If $target and $varname are both strings, the substituted value of the
 547    * variable $varname is inserted into or appended to $target.
 548    *
 549    * If $handle is an array of variable names the variables named by $handle are
 550    * sequentially substituted and the result of each substitution step is
 551    * inserted into or appended to in $target. The resulting substitution is
 552    * available in the variable named by $target, as is each intermediate step
 553    * for the next $varname in sequence. Note that while it is possible, it
 554    * is only rarely desirable to call this function with an array of varnames
 555    * and with $append = true. This append feature was introduced after the 7.2d
 556    * release.
 557    *
 558    * Returns: the last value assigned to $target.
 559    *
 560    * usage: parse(string $target, string $varname, [boolean $append])
 561    * or
 562    * usage: parse(string $target, array $varname = (string $varname), [boolean $append])
 563    *
 564    * @param     $target      a string containing the name of the variable into which substituted $varnames are to be stored
 565    * @param     $varname     if a string, the name the name of the variable to substitute or if an array a list of variables to be substituted
 566    * @param     $append      if true, the substituted variables are appended to $target otherwise the existing value of $target is replaced
 567    * @access    public
 568    * @return    string
 569    * @see       subst
 570    */
 571    function parse($target, $varname, $append = false) {
 572      if (!is_array($varname)) {
 573        if ($this->debug & 4) {
 574          echo "<p><b>parse:</b> (with scalar) target = $target, varname = $varname, append = $append</p>\n";
 575        }
 576        $str = $this->subst($varname);
 577        if ($append) {
 578          $this->set_var($target, $this->get_var($target) . $str);
 579        } else {
 580          $this->set_var($target, $str);
 581        }
 582      } else {
 583        reset($varname);
 584        while(list($i, $v) = each($varname)) {
 585          if ($this->debug & 4) {
 586            echo "<p><b>parse:</b> (with array) target = $target, i = $i, varname = $v, append = $append</p>\n";
 587          }
 588          $str = $this->subst($v);
 589          if ($append) {
 590            $this->set_var($target, $this->get_var($target) . $str);
 591          } else {
 592            $this->set_var($target, $str);
 593          }
 594        }
 595      }
 596  
 597      if ($this->debug & 4) {
 598        echo "<p><b>parse:</b> completed</p>\n";
 599      }
 600      return $str;
 601    }
 602  
 603  
 604   /******************************************************************************
 605    * This is shorthand for print $this->parse(...) and is functionally identical.
 606    * See parse for further details.
 607    *
 608    * Returns: always returns false.
 609    *
 610    * usage: pparse(string $target, string $varname, [boolean $append])
 611    * or
 612    * usage: pparse(string $target, array $varname = (string $varname), [boolean $append])
 613    *
 614    * @param     $target      a string containing the name of the variable into which substituted $varnames are to be stored
 615    * @param     $varname     if a string, the name the name of the variable to substitute or if an array a list of variables to be substituted
 616    * @param     $append      if true, the substituted variables are appended to $target otherwise the existing value of $target is replaced
 617    * @access    public
 618    * @return    false
 619    * @see       parse
 620    */
 621    function pparse($target, $varname, $append = false) {
 622      if ($this->debug & 4) {
 623        echo "<p><b>pparse:</b> passing parameters to parse...</p>\n";
 624      }
 625      print $this->finish($this->parse($target, $varname, $append));
 626      return false;
 627    }
 628  
 629  
 630   /******************************************************************************
 631    * This function returns an associative array of all defined variables with the
 632    * name as the key and the value of the variable as the value.
 633    *
 634    * This is mostly useful for debugging. Also note that $this->debug can be used
 635    * to echo all variable assignments as they occur and to trace execution.
 636    *
 637    * Returns: a hash of all defined variable values keyed by their names.
 638    *
 639    * usage: get_vars()
 640    *
 641    * @access    public
 642    * @return    array
 643    * @see       $debug
 644    */
 645    function get_vars() {
 646      if ($this->debug & 4) {
 647        echo "<p><b>get_vars:</b> constructing array of vars...</p>\n";
 648      }
 649      reset($this->varkeys);
 650      while(list($k, $v) = each($this->varkeys)) {
 651        $result[$k] = $this->get_var($k);
 652      }
 653      return $result;
 654    }
 655  
 656  
 657   /******************************************************************************
 658    * This function returns the value of the variable named by $varname.
 659    * If $varname references a file and that file has not been loaded yet, the
 660    * variable will be reported as empty.
 661    *
 662    * When called with an array of variable names this function will return a a
 663    * hash of variable values keyed by their names.
 664    *
 665    * Returns: a string or an array containing the value of $varname.
 666    *
 667    * usage: get_var(string $varname)
 668    * or
 669    * usage: get_var(array $varname)
 670    *
 671    * @param     $varname     if a string, the name the name of the variable to get the value of, or if an array a list of variables to return the value of
 672    * @access    public
 673    * @return    string or array
 674    */
 675    function get_var($varname) {
 676      if (!is_array($varname)) {
 677        if (isset($this->varvals[$varname])) {
 678          $str = $this->varvals[$varname];
 679        } else {
 680          $str = "";
 681        }
 682        if ($this->debug & 2) {
 683          printf ("<b>get_var</b> (with scalar) <b>%s</b> = '%s'<br>\n", $varname, htmlentities($str));
 684        }
 685        return $str;
 686      } else {
 687        reset($varname);
 688        while(list($k, $v) = each($varname)) {
 689          if (isset($this->varvals[$v])) {
 690            $str = $this->varvals[$v];
 691          } else {
 692            $str = "";
 693          }
 694          if ($this->debug & 2) {
 695            printf ("<b>get_var:</b> (with array) <b>%s</b> = '%s'<br>\n", $v, htmlentities($str));
 696          }
 697          $result[$v] = $str;
 698        }
 699        return $result;
 700      }
 701    }
 702  
 703  
 704   /******************************************************************************
 705    * This function returns a hash of unresolved variable names in $varname, keyed
 706    * by their names (that is, the hash has the form $a[$name] = $name).
 707    *
 708    * Returns: a hash of varname/varname pairs or false on error.
 709    *
 710    * usage: get_undefined(string $varname)
 711    *
 712    * @param     $varname     a string containing the name the name of the variable to scan for unresolved variables
 713    * @access    public
 714    * @return    array
 715    */
 716    function get_undefined($varname) {
 717      if ($this->debug & 4) {
 718        echo "<p><b>get_undefined:</b> varname = $varname</p>\n";
 719      }
 720      if (!$this->loadfile($varname)) {
 721        $this->halt("get_undefined: unable to load $varname.");
 722        return false;
 723      }
 724  
 725      preg_match_all("/{([^ \t\r\n}]+)}/", $this->get_var($varname), $m);
 726      $m = $m[1];
 727      if (!is_array($m)) {
 728        return false;
 729      }
 730  
 731      reset($m);
 732      while(list($k, $v) = each($m)) {
 733        if (!isset($this->varkeys[$v])) {
 734          if ($this->debug & 4) {
 735           echo "<p><b>get_undefined:</b> undefined: $v</p>\n";
 736          }
 737          $result[$v] = $v;
 738        }
 739      }
 740  
 741      if (count($result)) {
 742        return $result;
 743      } else {
 744        return false;
 745      }
 746    }
 747  
 748  
 749   /******************************************************************************
 750    * This function returns the finished version of $str. That is, the policy
 751    * regarding unresolved variable names will be applied to $str.
 752    *
 753    * Returns: a finished string derived from $str and $this->unknowns.
 754    *
 755    * usage: finish(string $str)
 756    *
 757    * @param     $str         a string to which to apply the unresolved variable policy
 758    * @access    public
 759    * @return    string
 760    * @see       set_unknowns
 761    */
 762    function finish($str) {
 763      switch ($this->unknowns) {
 764        case "keep":
 765        break;
 766  
 767        case "remove":
 768          $str = preg_replace('/{[^ \t\r\n}]+}/', "", $str);
 769        break;
 770  
 771        case "comment":
 772          $str = preg_replace('/{([^ \t\r\n}]+)}/', "<!-- Template variable \\1 undefined -->", $str);
 773        break;
 774      }
 775  
 776      return $str;
 777    }
 778  
 779  
 780   /******************************************************************************
 781    * This function prints the finished version of the value of the variable named
 782    * by $varname. That is, the policy regarding unresolved variable names will be
 783    * applied to the variable $varname then it will be printed.
 784    *
 785    * usage: p(string $varname)
 786    *
 787    * @param     $varname     a string containing the name of the variable to finish and print
 788    * @access    public
 789    * @return    void
 790    * @see       set_unknowns
 791    * @see       finish
 792    */
 793    function p($varname) {
 794      print $this->finish($this->get_var($varname));
 795    }
 796  
 797  
 798   /******************************************************************************
 799    * This function returns the finished version of the value of the variable named
 800    * by $varname. That is, the policy regarding unresolved variable names will be
 801    * applied to the variable $varname and the result returned.
 802    *
 803    * Returns: a finished string derived from the variable $varname.
 804    *
 805    * usage: get(string $varname)
 806    *
 807    * @param     $varname     a string containing the name of the variable to finish
 808    * @access    public
 809    * @return    void
 810    * @see       set_unknowns
 811    * @see       finish
 812    */
 813    function get($varname) {
 814      return $this->finish($this->get_var($varname));
 815    }
 816  
 817  
 818   /******************************************************************************
 819    * When called with a relative pathname, this function will return the pathname
 820    * with $this->root prepended. Absolute pathnames are returned unchanged.
 821    *
 822    * Returns: a string containing an absolute pathname.
 823    *
 824    * usage: filename(string $filename)
 825    *
 826    * @param     $filename    a string containing a filename
 827    * @access    private
 828    * @return    string
 829    * @see       set_root
 830    */
 831    function filename($filename) {
 832      if ($this->debug & 4) {
 833        echo "<p><b>filename:</b> filename = $filename</p>\n";
 834      }
 835      if (substr($filename, 0, 1) != "/") {
 836        $filename = $this->root."/".$filename;
 837      }
 838  
 839      if (!file_exists($filename)) {
 840        $this->halt("filename: file $filename does not exist.");
 841      }
 842      return $filename;
 843    }
 844  
 845  
 846   /******************************************************************************
 847    * This function will construct a regexp for a given variable name with any
 848    * special chars quoted.
 849    *
 850    * Returns: a string containing an escaped variable name.
 851    *
 852    * usage: varname(string $varname)
 853    *
 854    * @param     $varname    a string containing a variable name
 855    * @access    private
 856    * @return    string
 857    */
 858    function varname($varname) {
 859      return preg_quote("{".$varname."}");
 860    }
 861  
 862  
 863   /******************************************************************************
 864    * If a variable's value is undefined and the variable has a filename stored in
 865    * $this->file[$varname] then the backing file will be loaded and the file's
 866    * contents will be assigned as the variable's value.
 867    *
 868    * Note that the behaviour of this function changed slightly after the 7.2d
 869    * release. Where previously a variable was reloaded from file if the value
 870    * was empty, now this is not done. This allows a variable to be loaded then
 871    * set to "", and also prevents attempts to load empty variables. Files are
 872    * now only loaded if $this->varvals[$varname] is unset.
 873    *
 874    * Returns: true on success, false on error.
 875    *
 876    * usage: loadfile(string $varname)
 877    *
 878    * @param     $varname    a string containing the name of a variable to load
 879    * @access    private
 880    * @return    boolean
 881    * @see       set_file
 882    */
 883    function loadfile($varname) {
 884      if ($this->debug & 4) {
 885        echo "<p><b>loadfile:</b> varname = $varname</p>\n";
 886      }
 887  
 888      if (!isset($this->file[$varname])) {
 889        // $varname does not reference a file so return
 890        if ($this->debug & 4) {
 891          echo "<p><b>loadfile:</b> varname $varname does not reference a file</p>\n";
 892        }
 893        return true;
 894      }
 895  
 896      if (isset($this->varvals[$varname])) {
 897        // will only be unset if varname was created with set_file and has never been loaded
 898        // $varname has already been loaded so return
 899        if ($this->debug & 4) {
 900          echo "<p><b>loadfile:</b> varname $varname is already loaded</p>\n";
 901        }
 902        return true;
 903      }
 904      $filename = $this->file[$varname];
 905  
 906      /* use @file here to avoid leaking filesystem information if there is an error */
 907      $str = implode("", @file($filename));
 908      if (empty($str)) {
 909        $this->halt("loadfile: While loading $varname, $filename does not exist or is empty.");
 910        return false;
 911      }
 912  
 913      if ($this->debug & 4) {
 914        printf("<b>loadfile:</b> loaded $filename into $varname<br>\n");
 915      }
 916      $this->set_var($varname, $str);
 917  
 918      return true;
 919    }
 920  
 921  
 922   /******************************************************************************
 923    * This function is called whenever an error occurs and will handle the error
 924    * according to the policy defined in $this->halt_on_error. Additionally the
 925    * error message will be saved in $this->last_error.
 926    *
 927    * Returns: always returns false.
 928    *
 929    * usage: halt(string $msg)
 930    *
 931    * @param     $msg         a string containing an error message
 932    * @access    private
 933    * @return    void
 934    * @see       $halt_on_error
 935    */
 936    function halt($msg) {
 937      $this->last_error = $msg;
 938  
 939      if ($this->halt_on_error != "no") {
 940        $this->haltmsg($msg);
 941      }
 942  
 943      if ($this->halt_on_error == "yes") {
 944        die("<b>Halted.</b>");
 945      }
 946  
 947      return false;
 948    }
 949  
 950  
 951   /******************************************************************************
 952    * This function prints an error message.
 953    * It can be overridden by your subclass of Template. It will be called with an
 954    * error message to display.
 955    *
 956    * usage: haltmsg(string $msg)
 957    *
 958    * @param     $msg         a string containing the error message to display
 959    * @access    public
 960    * @return    void
 961    * @see       halt
 962    */
 963    function haltmsg($msg) {
 964      printf("<b>Template Error:</b> %s<br>\n", $msg);
 965    }
 966  
 967  }
 968  ?>