Template.php

   1 <?php
   2 /*=====================================================================*\
   3 || ###################################################################
   4 || # Blue Static ISSO Framework
   5 || # Copyright ©2002-[#]year[#] Blue Static
   6 || #
   7 || # This program is free software; you can redistribute it and/or modify
   8 || # it under the terms of the GNU General Public License as published by
   9 || # the Free Software Foundation; version [#]gpl[#] of the License.
  10 || #
  11 || # This program is distributed in the hope that it will be useful, but
  12 || # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13 || # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  14 || # more details.
  15 || #
  16 || # You should have received a copy of the GNU General Public License along
  17 || # with this program; if not, write to the Free Software Foundation, Inc.,
  18 || # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  19 || ###################################################################
  20 \*=====================================================================*/
  21
  22 /**
  23 * Database-Driven Template System (template.php)
  24 *
  25 * @package      ISSO
  26 */
  27
  28 require_once('ISSO/Functions.php');
  29
  30 /**
  31 * File-Based Template System
  32 *
  33 * This framework merely replaces the template loading functions with
  34 * file-system based ones. It has an optional caching system in which
  35 * template data will remain stored in the database as long as the filesystem
  36 * file is modified. To do this, pass a table name to setDatabaseCache() and make sure
  37 * there's a DB module that has access to a table with this schema:
  38 *
  39 * CREATE TABLE template (filename VARCHAR (250) NOT NULL, template TEXT NOT NULL, timestamp INT NOT NULL);
  40 *
  41 * @author               Blue Static
  42 * @copyright    Copyright ©2002 - [#]year[#], Blue Static
  43 * @version              $Revision$
  44 * @package              ISSO
  45 *
  46 */
  47 class BSTemplate
  48 {
  49         /**
  50         * The path, from the path of the application, where templates are stored
  51         * @var  string
  52         */
  53         private $templateDir = '';
  54
  55         /**
  56         * The extension all the template files have
  57         * @var  string
  58         */
  59         private $extension = 'tpl';
  60
  61         /**
  62         * The database table name for the template cache
  63         * @var string
  64         */
  65         private $dbCacheTable = null;
  66
  67         /**
  68         * The name of the function phrases are fetched with
  69         * @var  string
  70         */
  71         private $langcall = 'gettext';
  72
  73         /**
  74         * The name of the function phrases are sprintf() parsed with
  75         * @var  string
  76         */
  77         private $langconst = 'sprintf';
  78
  79         /**
  80         * Array of pre-compiled templates that are stored to decrease server load
  81         * @var  array
  82         */
  83         protected $cache = array();
  84
  85         /**
  86         * A list of the number of times each template has been used
  87         * @var  array
  88         */
  89         protected $usage = array();
  90
  91         /**
  92         * A list of templates that weren't cached, but are still used
  93         * @var  array
  94         */
  95         protected $uncached = array();
  96
  97         /**
  98         * Whether or not the page has been flush()'d already
  99         * @var  bool
 100         */
 101         private $doneflush = false;
 102
 103         /**
 104         * The name of a function that is called before template parsing of phrases and conditionals occurs
 105         * @var  string
 106         */
 107         private $preParseHook = ':undefined:';
 108
 109         // ###################################################################
 110         /**
 111         * Sets the template directory name
 112         *
 113         * @param        string  Template directory name
 114         */
 115         public function setTemplateDirectory($dir)
 116         {
 117                 $this->templateDir = BSFunctions::FetchSourcePath($dir);
 118         }
 119
 120         // ###################################################################
 121         /**
 122         * Sets the file extension for the templates
 123         *
 124         * @param        string  File extension
 125         */
 126         public function setExtension($ext)
 127         {
 128                 $this->extension = $ext;
 129         }
 130
 131         // ###################################################################
 132         /**
 133         * Sets the name of the table to access for the datbase cache
 134         *
 135         * @param        string  DB table name
 136         */
 137         public function setDatabaseCache($table)
 138         {
 139                 $this->dbCacheTable = $table;
 140         }
 141
 142         // ###################################################################
 143         /**
 144         * Sets the pre-parse hook method which is called before any other
 145         * processing is done on the template.
 146         *
 147         * @param        string  Method name
 148         */
 149         public function setPreParseHook($hook)
 150         {
 151                 $this->preParseHook = $hook;
 152         }
 153
 154         // ###################################################################
 155         /**
 156         * Takes an array of template names, loads them, and then stores a
 157         * parsed version for optimum speed.
 158         *
 159         * @param        array   List of template names to be cached
 160         */
 161         public function cache($namearray)
 162         {
 163                 if (sizeof($this->cache) > 0)
 164                 {
 165                         trigger_error('You cannot cache templates more than once per initialization');
 166                 }
 167                 else
 168                 {
 169                         $dbCache = array();
 170                         if ($this->dbCacheTable)
 171                         {
 172                                 $db =& BSRegister::GetType('Db');
 173                                 $cache = $db->query("SELECT * FROM {$this->dbCacheTable} WHERE filename IN ('" . implode("', '", $namearray) . "')");
 174                                 while ($tpl = $db->fetchArray($cache))
 175                                 {
 176                                         $time = filemtime(BSRegister::GetAppPath() . $this->templateDir . $tpl['filename'] . '.' . $this->extension);
 177                                         $template = $tpl['template'];
 178                                         if ($time > $tpl['timestamp'])
 179                                         {
 180                                                 $template = $this->_parseTemplate($this->_loadTemplate($tpl['filename']));
 181                                                 $db->query("UPDATE {$this->dbCacheTable} SET template = '" . $db->escapeString($template) . "', timestamp = " . TIMENOW . " WHERE filename = '" . $tpl['filename'] . "'");
 182                                                 $tpl['template'] = $template;
 183                                         }
 184                                         $dbCache["$tpl[filename]"] = $template;
 185                                 }
 186                         }
 187                         foreach ($namearray AS $name)
 188                         {
 189                                 if ($this->dbCacheTable)
 190                                 {
 191                                         if (isset($dbCache["$name"]))
 192                                         {
 193                                                 $template = $dbCache["$name"];
 194                                         }
 195                                         else
 196                                         {
 197                                                 $template = $this->_parseTemplate($this->_loadTemplate($name));
 198                                                 $db->query("INSERT INTO {$this->dbCacheTable} (filename, template, timestamp) VALUES ('$name', '" . $db->escapeString($template) . "', " . TIMENOW . ")");
 199                                         }
 200                                 }
 201                                 else
 202                                 {
 203                                         $template = $this->_parseTemplate($this->_loadTemplate($name));
 204                                 }
 205
 206                                 $this->cache["$name"] = $template;
 207                                 $this->usage["$name"] = 0;
 208                         }
 209                 }
 210         }
 211
 212         // ###################################################################
 213         /**
 214         * Loads a template from the cache or the _load function and stores the
 215         * parsed version of it
 216         *
 217         * @param        string  The name of the template
 218         *
 219         * @return       string  A parsed and loaded template
 220         */
 221         public function fetch($name)
 222         {
 223                 if (isset($this->cache["$name"]))
 224                 {
 225                         $template = $this->cache["$name"];
 226                 }
 227                 else
 228                 {
 229                         $this->uncached[] = $name;
 230                         BSRegister::Debug("Manually loading template '$name'");
 231                         $template = $this->_loadTemplate($name);
 232                         $template = $this->_parseTemplate($template);
 233                 }
 234
 235                 if (!isset($this->usage["$name"]))
 236                 {
 237                         $this->usage["$name"] = 0;
 238                 }
 239
 240                 $this->usage["$name"]++;
 241
 242                 return $template;
 243         }
 244
 245         // ###################################################################
 246         /**
 247         * Output a template fully compiled to the browser
 248         *
 249         * @param        string  Compiled and ready template
 250         */
 251         public function flush($template)
 252         {
 253                 ob_start();
 254
 255                 if (empty($template))
 256                 {
 257                         trigger_error('There was no output to print');
 258                         exit;
 259                 }
 260
 261                 if ($this->doneflush)
 262                 {
 263                         trigger_error('A template has already been sent to the output buffer');
 264                         exit;
 265                 }
 266
 267                 $debugBlock = '';
 268                 if (BSRegister::GetDebug())
 269                 {
 270                         if (defined('SVN') AND preg_match('#^\$Id:?#', constant('SVN')))
 271                         {
 272                                 $debugBlock .= preg_replace('#\$' . 'Id: (.+?) ([0-9].+?) [0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}(.+?) (.+?) \$#', "\n<br />\n" . '<div align="center"><strong>\1</strong> &mdash; r\2</div>', constant('SVN'));
 273                         }
 274
 275                         if (defined('ISSO_MT_START'))
 276                         {
 277                                 $debugBlock .= "\n<div align=\"center\">Executed in " . round(BSFunctions::FetchMicrotimeDiff(ISSO_MT_START), 10) . ' seconds</div>';
 278                         }
 279
 280                         $debugBlock .= "\n<br /><div align=\"center\">" . BSRegister::GetDebugList() . "</div>";
 281
 282                         $optlist = array();
 283                         $usage = array();
 284                         foreach ($this->usage AS $name => $count)
 285                         {
 286                                 if (in_array($name, $this->uncached))
 287                                 {
 288                                         $optlist[] = $name . '[' . $count . ']';
 289                                 }
 290                                 $usage[] = $name . " ($count)";
 291                         }
 292                         $sizeof = sizeof($this->uncached);
 293                         if ($sizeof > 0)
 294                         {
 295                                 $debugBlock .= "<br /><div style=\"color: red\" align=\"center\"><strong>Uncached Template(s):</strong> $sizeof ( " . implode(' &nbsp; ', $optlist) . " )</div>\n";
 296                         }
 297
 298                         $debugBlock .= (sizeof($this->uncached) < 1 ? "<br />\n" : '') . "<div align=\"center\"><select><option>Template Usage (" . array_sum($this->usage) . ")</option>";
 299                         foreach ($usage AS $tpl)
 300                         {
 301                                 $debugBlock .= "<option>--- $tpl</option>";
 302                         }
 303                         $debugBlock .= "</select></div>\n";
 304
 305                         if (BSRegister::GetType('Db'))
 306                         {
 307                                 $queries = BSRegister::GetType('Db')->getHistory();
 308
 309                                 $debugBlock .= "<br />\n" . '<table cellpadding="4" cellspacing="1" border="0" align="center" width="30%" style="background-color: rgb(60, 60, 60); color: white">' . "\n\t" . '<tr><td><strong>Query Debug</strong></td></tr>';
 310
 311                                 foreach ($queries AS $query)
 312                                 {
 313                                         $debugBlock .= "\n\t<tr style=\"background-color: rgb(230, 230, 230); color: black\">";
 314                                         $debugBlock .= "\n\t\t<td>";
 315                                         $debugBlock .= "\n\t\t\t$query[query]\n\n\t\t\t<div style=\"font-size: 9px;\">($query[time])</div>\n<!--\n$query[trace]\n-->\n\t\t</td>\n\t</tr>";
 316                                 }
 317
 318                                 $debugBlock .= "\n</table>\n\n\n";
 319                         }
 320                 }
 321
 322                 $template = str_replace('</body>', $debugBlock . '</body>', $template);
 323
 324                 print($template);
 325         }
 326
 327         // ###################################################################
 328         /**
 329         * Loads an additional template from the database
 330         *
 331         * @param        string  The name of the template
 332         *
 333         * @return       string  Template data from the database
 334         */
 335         protected function _loadTemplate($name)
 336         {
 337                 $path = BSRegister::GetAppPath() . $this->templateDir . $name . '.' . $this->extension;
 338                 if (is_file($path))
 339                 {
 340                         if (($template = @file_get_contents($path)) !== false)
 341                         {
 342                                 return $template;
 343                         }
 344                         else
 345                         {
 346                                 trigger_error("Could not load the template '$path'");
 347                                 exit;
 348                         }
 349                 }
 350                 else
 351                 {
 352                         trigger_error("Could not load the template '$path'");
 353                         exit;
 354                 }
 355         }
 356
 357         // ###################################################################
 358         /**
 359         * A wrapper for all the parsing functions and compiling functins
 360         *
 361         * @param        string  Unparsed template data
 362         *
 363         * @return       string  Parsed template data
 364         */
 365         protected function _parseTemplate($template)
 366         {
 367                 $template = str_replace('"', '\"', $template);
 368
 369                 if (function_exists($this->preParseHook))
 370                 {
 371                         $template = call_user_func($this->preParseHook, $template);
 372                 }
 373
 374                 $template = $this->_parseBlocksAndTokens($template);
 375                 $template = $this->_parsePhrases($template);
 376                 $template = $this->_parseConditionals($template);
 377                 return $template;
 378         }
 379
 380         // ###################################################################
 381         /**
 382         * Parses anything with curly braces {} (including phrases)
 383         *
 384         * @param        string  Template data
 385         *
 386         * @return       string  Parsed template data
 387         */
 388         private function _parseBlocksAndTokens($template)
 389         {
 390                 $stack = array();
 391                 $tokens = array();
 392
 393                 while (1)
 394                 {
 395                         for ($i = 0; $i < strlen($template); $i++)
 396                         {
 397                                 // we've run through the template and there's nothing in the stack--done
 398                                 if ($i == strlen($template) - 1 AND sizeof($stack) == 0)
 399                                 {
 400                                         return $template;
 401                                 }
 402
 403                                 if ($template[$i] == '{')
 404                                 {
 405                                         // ignore escaped sequences
 406                                         if ($template[$i - 1] != '\\')
 407                                         {
 408                                                 array_push($stack, $i);
 409                                         }
 410                                 }
 411                                 else if ($template[$i] == '}')
 412                                 {
 413                                         // there's no stack so it was probably escaped
 414                                         if (sizeof($stack) == 0)
 415                                         {
 416                                                 continue;
 417                                         }
 418                                         // we're good and nested
 419                                         else if (sizeof($stack) == 1)
 420                                         {
 421                                                 $open = array_pop($stack);
 422                                                 $token = substr($template, $open, $i - $open + 1);
 423                                                 $template = str_replace($token, $this->_parseToken($token), $template);
 424                                                 break;
 425                                         }
 426                                         // just pop it off
 427                                         else
 428                                         {
 429                                                 array_pop($stack);
 430                                         }
 431                                 }
 432                         }
 433                 }
 434         }
 435
 436         // ###################################################################
 437         /**
 438         * Parses a curly brace token {}
 439         *
 440         * @param        string  Token
 441         *
 442         * @return       string  Parsed value
 443         */
 444         private function _parseToken($token)
 445         {
 446                 // knock of the braces
 447                 $token = substr($token, 1, strlen($token) - 2);
 448
 449                 // language token
 450                 if ($token[0] == '@' AND $token[1] == '\\' AND $token[2] == '"')
 451                 {
 452                         return '" . ' . $this->langcall . '(\'' . str_replace(array('\\\"', "'"), array('"', "\'"), substr($token, 3, strlen($token) - 5)) . '\')' . ' . "';
 453                 }
 454                 // normal PHP code
 455                 else
 456                 {
 457                         return '" . (' . $token . ') . "';
 458                 }
 459         }
 460
 461         // ###################################################################
 462         /**
 463         * Prepares language and locale information inside templates
 464         *
 465         * @param        string  Template data to be processed
 466         *
 467         * @return       string  Language-ready template data
 468         */
 469         private function _parsePhrases($template)
 470         {
 471                 $tagStart = '<lang ';
 472                 $tagEnd = '</lang>';
 473
 474                 $start = -1; // start of open tag
 475                 $end = -1; // start of the close tag
 476                 $varEnd = -1; // end of the open tag
 477
 478                 while ($start <= strlen($template))
 479                 {
 480                         // reset
 481                         $varMap = array(); // storage for all the substitution indices
 482
 483                         // Find the start language object tag
 484                         $start = strpos($template, $tagStart, $end + 1);
 485                         if ($start === false)
 486                         {
 487                                 break;
 488                         }
 489
 490                         // look ahead to parse out all the variables
 491                         $i = $start + strlen($tagStart); // current position
 492                         $capture = ''; // current capture
 493                         $capturePos = $i; // the place to start capturing
 494                         $varNum = -1; // variable placeholder index
 495                         while ($i < strlen($template))
 496                         {
 497                                 if ($template[$i] == '=')
 498                                 {
 499                                         // backtrack to find the previous variable substitution
 500                                         $backPos = $i;
 501                                         while ($backPos >= $start)
 502                                         {
 503                                                 if ($template[$backPos] == '"')
 504                                                 {
 505                                                         // startPosition + length(startTag) + length(=\")
 506                                                         $varMap[intval($varNum)] = BSFunctions::Substring($template, $capturePos + 3, $backPos - 1);
 507                                                         // remove our old substitution from the capture
 508                                                         $capture = BSFunctions::Substring($template, $backPos + 1, $i);
 509                                                         break;
 510                                                 }
 511                                                 $backPos--;
 512                                         }
 513
 514                                         // do we have a valid index?
 515                                         if (intval($capture) > 0)
 516                                         {
 517                                                 // set aside the index and restart capturing
 518                                                 $varNum = $capture;
 519                                                 $capture = '';
 520                                                 $capturePos = $i;
 521                                         }
 522                                         else
 523                                         {
 524                                                 trigger_error('Invalid language variable index "' . $capture . '"');
 525                                         }
 526                                 }
 527                                 else if ($template[$i] == '>' AND $template[$i - 1] == '"')
 528                                 {
 529                                         // the final variable substitution
 530                                         $varMap[intval($varNum)] = BSFunctions::Substring($template, $capturePos + 3, $i - 2);
 531                                         $varEnds = $i;
 532                                         break;
 533                                 }
 534
 535                                 $capture .= $template[$i];
 536                                 $i++;
 537                         }
 538
 539                         // locate the end tag
 540                         $end = strpos($template, $tagEnd, $i);
 541                         if ($end === false)
 542                         {
 543                                 break;
 544                         }
 545
 546                         // this is the string that gets variable replacement
 547                         $str = BSFunctions::Substring($template, $varEnds + 1, $end);
 548
 549                         // create the complete varmap
 550
 551                         for ($i = max(array_keys($varMap)); $i > 0; $i--)
 552                         {
 553                                 if (!isset($varMap[$i]))
 554                                 {
 555                                         $varMap[$i] = '<strong>[MISSING SUBSTITUTION INDEX: ' . $i . ']</strong>';
 556                                 }
 557                         }
 558
 559                         // put all the keys in corresponding argument order
 560                         ksort($varMap);
 561
 562                         // FINALLY, construct the call to sprintf()
 563                         $template = substr_replace($template, '" . ' . $this->langconst . '(\'' . $str . '\', "' . implode('", "', $varMap) . '") . "', $start, ($end + strlen($tagEnd)) - $start);
 564                 }
 565
 566                 return $template;
 567         }
 568
 569         // ###################################################################
 570         /**
 571         * Parser for in-line template conditionals
 572         *
 573         * @param        string  Template data awaiting processing
 574         *
 575         * @return       string  Parsed template data
 576         */
 577         private function _parseConditionals($template)
 578         {
 579                 // tag data
 580                 $tag_start = '<if condition=\"';
 581                 $tag_start_end = '\">';
 582                 $tag_else = '<else />';
 583                 $tag_end = '</if>';
 584
 585                 // tag stack
 586                 $stack = array();
 587
 588                 // the information about the current active tag
 589                 $tag_full = array();
 590                 $parsed = array();
 591
 592                 // start at 0
 593                 $offset = 0;
 594
 595                 while (1)
 596                 {
 597                         if (strpos($template, $tag_start) === false)
 598                         {
 599                                 break;
 600                         }
 601
 602                         for ($i = $offset; $i < strlen($template); $i++)
 603                         {
 604                                 // we've found ourselves a conditional!
 605                                 if (substr($template, $i, strlen($tag_start)) == $tag_start)
 606                                 {
 607                                         // push the position into the tag stack
 608                                         if ($tag_full)
 609                                         {
 610                                                 array_push($stack, $i);
 611                                         }
 612                                         else
 613                                         {
 614                                                 $tag_full['posi'] = $i;
 615                                         }
 616                                 }
 617                                 // locate else tags
 618                                 else if (substr($template, $i, strlen($tag_else)) == $tag_else)
 619                                 {
 620                                         if (sizeof($stack) == 0 AND !isset($tag_full['else']))
 621                                         {
 622                                                 $tag_full['else'] = $i;
 623                                         }
 624                                 }
 625                                 // do we have an end tag?
 626                                 else if (substr($template, $i, strlen($tag_end)) == $tag_end)
 627                                 {
 628                                         if (sizeof($stack) != 0)
 629                                         {
 630                                                 array_pop($stack);
 631                                                 continue;
 632                                         }
 633
 634                                         // calculate the position of the end tag
 635                                         $tag_full['posf'] = $i + strlen($tag_end) - 1;
 636
 637                                         // extract the entire conditional from the template
 638                                         $fullspread = substr($template, $tag_full['posi'], $tag_full['posf'] - $tag_full['posi'] + 1);
 639
 640                                         // remove the beginning tag
 641                                         $conditional = substr($fullspread, strlen($tag_start));
 642
 643                                         // find the end of the expression
 644                                         $temp_end = strpos($conditional, $tag_start_end);
 645
 646                                         // save the expression
 647                                         $parsed[0] = stripslashes(substr($conditional, 0, $temp_end));
 648
 649                                         // remove the expression from the conditional
 650                                         $conditional = substr($conditional, strlen($parsed[0]) + strlen($tag_start_end));
 651
 652                                         // remove the tailing end tag
 653                                         $conditional = substr($conditional, 0, strlen($conditional) - strlen($tag_end));
 654
 655                                         // handle the else
 656                                         if (isset($tag_full['else']))
 657                                         {
 658                                                 // now relative to the start of the <if>
 659                                                 $relpos = $tag_full['else'] - $tag_full['posi'];
 660
 661                                                 // calculate the length of the expression and opening tag
 662                                                 $length = strlen($parsed[0]) + strlen($tag_start) + strlen($tag_start_end);
 663
 664                                                 // relative to the start of iftrue
 665                                                 $elsepos = $relpos - $length;
 666
 667                                                 $parsed[1] = substr($conditional, 0, $elsepos);
 668                                                 $parsed[2] = substr($conditional, $elsepos + strlen($tag_else));
 669                                         }
 670                                         // no else to handle
 671                                         else
 672                                         {
 673                                                 $parsed[1] = $conditional;
 674                                                 $parsed[2] = '';
 675                                         }
 676
 677                                         // final parsed output
 678                                         $parsed = '" . ((' . stripslashes($parsed[0]) . ') ? "' . $parsed[1] . '" : "' . $parsed[2] . '") . "';
 679
 680                                         // replace the conditional
 681                                         $template = str_replace($fullspread, $parsed, $template);
 682
 683                                         // reset the parser
 684                                         $offset = $tag_full['posi'] + strlen($tag_start) + strlen($tag_start_end);
 685                                         $tag_full = array();
 686                                         $stack = array();
 687                                         $parsed = array();
 688                                         unset($fullspread, $conditional, $temp_end, $relpos, $length, $elsepos);
 689                                         break;
 690                                 }
 691                         }
 692                 }
 693
 694                 return $template;
 695         }
 696 }
 697
 698 // ###################################################################
 699 /**
 700 * Debugging function used to print characters in a string that are
 701 * around a certain position.
 702 *
 703 * @access       private
 704 *
 705 * @param        string  The haystack string
 706 * @param        integer Position to print around
 707 */
 708 function print_around($str, $pos)
 709 {
 710         echo '>>> PA >>>>>>>>[';
 711         echo htmlspecialchars($str[ $pos - 5 ]);
 712         echo htmlspecialchars($str[ $pos - 4 ]);
 713         echo htmlspecialchars($str[ $pos - 3 ]);
 714         echo htmlspecialchars($str[ $pos - 2 ]);
 715         echo htmlspecialchars($str[ $pos - 1 ]);
 716         echo '©';
 717         echo htmlspecialchars($str[ $pos + 0 ]);
 718         echo htmlspecialchars($str[ $pos + 1 ]);
 719         echo htmlspecialchars($str[ $pos + 2 ]);
 720         echo htmlspecialchars($str[ $pos + 3 ]);
 721         echo htmlspecialchars($str[ $pos + 4 ]);
 722         echo htmlspecialchars($str[ $pos + 5 ]);
 723         echo ']<<<<<<<< PA <<<';
 724 }
 725
 726 /*=====================================================================*\
 727 || ###################################################################
 728 || # $HeadURL$
 729 || # $Id$
 730 || ###################################################################
 731 \*=====================================================================*/
 732 ?>