Source for file File.php

Documentation is available at File.php

  1. <?php
  2.  
  3. /**
  4.  * represents a Dwoo template contained in a file
  5.  *
  6.  * This software is provided 'as-is', without any express or implied warranty.
  7.  * In no event will the authors be held liable for any damages arising from the use of this software.
  8.  *
  9.  * @author     Jordi Boggiano <j.boggiano@seld.be>
  10.  * @copyright  Copyright (c) 2008, Jordi Boggiano
  11.  * @license    http://dwoo.org/LICENSE   Modified BSD License
  12.  * @link       http://dwoo.org/
  13.  * @version    1.0.0
  14.  * @date       2008-10-23
  15.  * @package    Dwoo
  16.  */
  17. class Dwoo_Template_File extends Dwoo_Template_String
  18. {
  19.     /**
  20.      * template filename
  21.      *
  22.      * @var string 
  23.      */
  24.     protected $file;
  25.  
  26.     /**
  27.      * include path(s) to look into to find this template
  28.      *
  29.      * @var array 
  30.      */
  31.     protected $includePath = null;
  32.  
  33.     /**
  34.      * resolved path cache when looking for a file in multiple include paths
  35.      *
  36.      * this is reset when the include path is changed
  37.      *
  38.      * @var string 
  39.      */
  40.     protected $resolvedPath = null;
  41.  
  42.     /**
  43.      * creates a template from a file
  44.      *
  45.      * @param string $file the path to the template file, make sure it exists
  46.      * @param int $cacheTime duration of the cache validity for this template,
  47.      *                           if null it defaults to the Dwoo instance that will
  48.      *                           render this template
  49.      * @param string $cacheId the unique cache identifier of this page or anything else that
  50.      *                            makes this template's content unique, if null it defaults
  51.      *                            to the current url
  52.      * @param string $compileId the unique compiled identifier, which is used to distinguish this
  53.      *                              template from others, if null it defaults to the filename+bits of the path
  54.      * @param mixed $includePath a string for a single path to look into for the given file, or an array of paths
  55.      */
  56.     public function __construct($file, $cacheTime = null, $cacheId = null, $compileId = null, $includePath = null)
  57.     {
  58.         $this->file = $file;
  59.         $this->name = basename($file);
  60.         $this->cacheTime = $cacheTime;
  61.  
  62.         if ($compileId !== null) {
  63.             $this->compileId = str_replace('../', '__', strtr($compileId, '\\%?=!:;'.PATH_SEPARATOR, '/-------'));
  64.         }
  65.  
  66.         if ($cacheId !== null) {
  67.             $this->cacheId = str_replace('../', '__', strtr($cacheId, '\\%?=!:;'.PATH_SEPARATOR, '/-------'));
  68.         }
  69.  
  70.         if (is_string($includePath)) {
  71.             $this->includePath = array($includePath);
  72.         } elseif (is_array($includePath)) {
  73.             $this->includePath = $includePath;
  74.         }
  75.     }
  76.  
  77.     /**
  78.      * sets the include path(s) to where the given template filename must be looked up
  79.      *
  80.      * @param mixed $paths the path to look into, can be string for a single path or an array of paths
  81.      */
  82.     public function setIncludePath($paths)
  83.     {
  84.         if (is_array($paths) === false) {
  85.             $paths = array($paths);
  86.         }
  87.  
  88.         $this->includePath = $paths;
  89.         $this->resolvedPath = null;
  90.     }
  91.  
  92.     /**
  93.      * return the current include path(s)
  94.      *
  95.      * @return array 
  96.      */
  97.     public function getIncludePath()
  98.     {
  99.         return $this->includePath;
  100.     }
  101.     
  102.  
  103.     
  104.     /**
  105.      * Checks if compiled file is valid (exists and it's the modification is greater or
  106.      * equal to the modification time of the template file)
  107.      * 
  108.      * @param string file
  109.      * @return boolean True cache file existance and it's modification time
  110.      */
  111.     protected function isValidCompiledFile($file) {
  112.         return parent::isValidCompiledFile($file) && (int)$this->getUid() <= filemtime($file);
  113.     }
  114.  
  115.     /**
  116.      * returns the template source of this template
  117.      *
  118.      * @return string 
  119.      */
  120.     public function getSource()
  121.     {
  122.         return file_get_contents($this->getResourceIdentifier());
  123.     }
  124.  
  125.     /**
  126.      * returns the resource name for this template class
  127.      *
  128.      * @return string 
  129.      */
  130.     public function getResourceName()
  131.     {
  132.         return 'file';
  133.     }
  134.  
  135.     /**
  136.      * returns this template's source filename
  137.      *
  138.      * @return string 
  139.      */
  140.     public function getResourceIdentifier()
  141.     {
  142.         if ($this->resolvedPath !== null) {
  143.             return $this->resolvedPath;
  144.         } elseif ($this->includePath === null) {
  145.             return $this->file;
  146.         } else {
  147.             foreach ($this->includePath as $path) {
  148.                 if (file_exists($path.DIRECTORY_SEPARATOR.$this->file) === true) {
  149.                     $this->resolvedPath = $path . DIRECTORY_SEPARATOR . $this->file;
  150.                     return $this->resolvedPath;
  151.                 }
  152.             }
  153.  
  154.             throw new Dwoo_Exception('Template "'.$this->file.'" could not be found in any of your include path(s)');
  155.         }
  156.     }
  157.  
  158.     /**
  159.      * returns an unique value identifying the current version of this template,
  160.      * in this case it's the unix timestamp of the last modification
  161.      *
  162.      * @return string 
  163.      */
  164.     public function getUid()
  165.     {
  166.         return (string) filemtime($this->getResourceIdentifier());
  167.     }
  168.  
  169.     /**
  170.      * returns a new template object from the given include name, null if no include is
  171.      * possible (resource not found), or false if include is not permitted by this resource type
  172.      *
  173.      * @param Dwoo $dwoo the dwoo instance requiring it
  174.      * @param mixed $resourceId the filename (relative to this template's dir) of the template to include
  175.      * @param int $cacheTime duration of the cache validity for this template,
  176.      *                           if null it defaults to the Dwoo instance that will
  177.      *                           render this template
  178.      * @param string $cacheId the unique cache identifier of this page or anything else that
  179.      *                            makes this template's content unique, if null it defaults
  180.      *                            to the current url
  181.      * @param string $compileId the unique compiled identifier, which is used to distinguish this
  182.      *                              template from others, if null it defaults to the filename+bits of the path
  183.      * @param Dwoo_ITemplate $parentTemplate the template that is requesting a new template object (through
  184.      *                                              an include, extends or any other plugin)
  185.      * @return Dwoo_Template_File|null
  186.      */
  187.     public static function templateFactory(Dwoo $dwoo, $resourceId, $cacheTime = null, $cacheId = null, $compileId = null, Dwoo_ITemplate $parentTemplate = null)
  188.     {
  189.         if (DIRECTORY_SEPARATOR === '\\') {
  190.             $resourceId = str_replace(array("\t", "\n", "\r", "\f", "\v"), array('\\t', '\\n', '\\r', '\\f', '\\v'), $resourceId);
  191.         }
  192.         $resourceId = strtr($resourceId, '\\', '/');
  193.  
  194.         $includePath = null;
  195.  
  196.         if (file_exists($resourceId) === false) {
  197.             if ($parentTemplate === null) {
  198.                 $parentTemplate = $dwoo->getTemplate();
  199.             }
  200.             if ($parentTemplate instanceof Dwoo_Template_File) {
  201.                 if ($includePath = $parentTemplate->getIncludePath()) {
  202.                     if (strstr($resourceId, '../')) {
  203.                         throw new Dwoo_Exception('When using an include path you can not reference a template into a parent directory (using ../)');
  204.                     }
  205.                 } else {
  206.                     $resourceId = dirname($parentTemplate->getResourceIdentifier()).DIRECTORY_SEPARATOR.$resourceId;
  207.                     if (file_exists($resourceId) === false) {
  208.                         return null;
  209.                     }
  210.                 }
  211.             } else {
  212.                 return null;
  213.             }
  214.         }
  215.  
  216.         if ($policy = $dwoo->getSecurityPolicy()) {
  217.             while (true) {
  218.                 if (preg_match('{^([a-z]+?)://}i', $resourceId)) {
  219.                     throw new Dwoo_Security_Exception('The security policy prevents you to read files from external sources : <em>'.$resourceId.'</em>.');
  220.                 }
  221.  
  222.                 if ($includePath) {
  223.                     break;
  224.                 }
  225.  
  226.                 $resourceId = realpath($resourceId);
  227.                 $dirs = $policy->getAllowedDirectories();
  228.                 foreach ($dirs as $dir=>$dummy) {
  229.                     if (strpos($resourceId, $dir) === 0) {
  230.                         break 2;
  231.                     }
  232.                 }
  233.                 throw new Dwoo_Security_Exception('The security policy prevents you to read <em>'.$resourceId.'</em>');
  234.             }
  235.         }
  236.  
  237.         return new Dwoo_Template_File($resourceId, $cacheTime, $cacheId, $compileId, $includePath);
  238.     }
  239.  
  240.     /**
  241.      * returns the full compiled file name and assigns a default value to it if
  242.      * required
  243.      *
  244.      * @param Dwoo $dwoo the dwoo instance that requests the file name
  245.      * @return string the full path to the compiled file
  246.      */
  247.     protected function getCompiledFilename(Dwoo $dwoo)
  248.     {
  249.         // no compile id was provided, set default
  250.         if ($this->compileId===null) {
  251.             $this->compileId = str_replace('../', '__', strtr($this->getResourceIdentifier(), '\\:', '/-'));
  252.         }
  253.         return $dwoo->getCompileDir() . $this->compileId.'.d'.Dwoo::RELEASE_TAG.'.php';
  254.     }
  255. }

Documentation generated on Wed, 24 Dec 2008 02:13:28 +0100 by phpDocumentor 1.4.0