Source for file Response.php

Documentation is available at Response.php

  1. <?php
  2. // vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4 fdm=marker encoding=utf8 :
  3. /**
  4.  * Pxxo - build self-supported and interoperable Web graphical components
  5.  * 
  6.  * Copyright (c) 2008, Nicolas Thouvenin
  7.  *
  8.  * All rights reserved.
  9.  *
  10.  * Redistribution and use in source and binary forms, with or without
  11.  * modification, are permitted provided that the following conditions are met:
  12.  *
  13.  *     * Redistributions of source code must retain the above copyright
  14.  *       notice, this list of conditions and the following disclaimer.
  15.  *     * Redistributions in binary form must reproduce the above copyright
  16.  *       notice, this list of conditions and the following disclaimer in the
  17.  *       documentation and/or other materials provided with the distribution.
  18.  *     * Neither the name of the author nor the names of its contributors may be
  19.  *       used to endorse or promote products derived from this software without
  20.  *       specific prior written permission.
  21.  *
  22.  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  23.  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  24.  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  25.  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  26.  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  27.  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  28.  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  29.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  31.  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32.  
  33.  * @package    Pxxo
  34.  * @copyright  Copyright (c) 2008 Nicolas Thouvenin
  35.  * @license    http://opensource.org/licenses/bsd-license.php
  36.  * @version    $Id$
  37.  */
  38.  
  39.  
  40. /**
  41.  * Classe de Gestion de l'entete HTTP
  42.  *
  43.  * Cette classe reprend la classe de Hugo Haas (http://larve.net/2006/08/php-http-caching/)
  44.  * et lui ajoute quelques bricoles
  45.  *
  46.  * @package    Pxxo
  47.  * @copyright  Copyright (c) 2008 Nicolas Thouvenin
  48.  * @license    http://opensource.org/licenses/bsd-license.php
  49.  */
  50. class Pxxo_Response
  51. {
  52.     /**
  53.      * Array containing the list of Cache-Control directives, except max-age and s-maxage
  54.      * @var array 
  55.      */
  56.     private $_CacheDirectives = array();
  57.  
  58.     /**
  59.      * allowed Cache Control Directives
  60.      * @var array 
  61.      */
  62.     private $CacheDirectives = array(
  63.         'public',
  64.         'private',
  65.         'no-cache',
  66.         'no-store',
  67.         'must-revalidate',
  68.         'proxy-revalidate',
  69.     );
  70.  
  71.     /**
  72.      * Array containing the list of Cache-Control directives, except max-age and s-maxage
  73.      * @var array 
  74.      */
  75.     private $_ContentDirectives = array();
  76.  
  77.     /**
  78.      * allowed Content Directives
  79.      * @var array 
  80.      */
  81.     private $ContentDirectives = array(
  82.         'type',
  83.         'language',
  84.         'disposition',
  85.         'transfer-encoding',
  86.         'length',
  87.     );
  88.  
  89.  
  90.     /**
  91.      * var array Ages: max-age and s-maxage
  92.      */
  93.     private $ages = array(
  94.         'max-age' => -1, 
  95.         's-maxage' => -1
  96.     );
  97.  
  98.     /**
  99.      * @var string Last-Modified and ETags
  100.      */
  101.     private $lastModified;
  102.  
  103.     /**
  104.      * @var string 
  105.      */
  106.     private $eTag;
  107.  
  108.     /**
  109.      * @var array URL et Status Code
  110.      */
  111.     private $redirection  =array();
  112.  
  113.     /**
  114.      * @var array cookies will be send
  115.      */
  116.     private $cookies = array();
  117.  
  118.     /**
  119.      * Send HTTP caching headers (Expires, Cache-Control, ETags and
  120.      * Last-Modified), and returns a 304 if the client has a cached version.
  121.      *
  122.      * This function returns a 304 if the client already has the latest version
  123.      * of the resource's representation. The PHP
  124.      * script will subsequently quit if $die is set to true.
  125.      *
  126.      * @param $die if set to true, the program terminates if a 304 is being sent, and if set to false, the call will return and the execution will continue
  127.      */
  128.     function sendStatusAndHeaders($die) 
  129.     {
  130.         if ($this->isRedirect()) {
  131.             header('HTTP/1.1 ' . $this->redirection[1]);
  132.             $this->sendHeaders();
  133.             if ($die == true) exit();
  134.         }
  135.  
  136.         $isFresh = $_SERVER['REQUEST_METHOD'] == "GET" ? $this->isFresh() : false;
  137.         // Send back a 304?
  138.         if ($isFresh == true) {
  139.             header('HTTP/1.1 304 Not Modified');
  140.         }
  141.         $this->sendHeaders();
  142.         // Die if 304?
  143.         if ($isFresh == true && $die == true) exit();
  144.     }
  145.  
  146.     /**
  147.      * Send HTTP caching headers (Expires, Cache-Control, ETags and  Last-Modified)
  148.      *
  149.      * Expires and Cache-Control are sent as set.
  150.      *
  151.      * ETag is sent if set. Last-Modified is sent if set or if ETag isn't set,
  152.      * defaulting to the current time.
  153.      * Indeed, at least you of the two needs to be present for the response
  154.      * to be cacheable.
  155.      */
  156.     function sendHeaders() 
  157.     {
  158.         // Signature Pxxo
  159.         header('X-Powered-By: Pxxo/5.x', false);
  160.  
  161.  
  162.         if ($this->isRedirect()) {
  163.             header('Location: ' . $this->redirection[0], true);
  164.             header('HTTP/1.1 ' . $this->redirection[1]);
  165.             return;
  166.         }
  167.  
  168.         // Cookies
  169.         foreach($this->cookies as $key => $value) {
  170.             header('Set-Cookie: '.$value, false);
  171.         }
  172.  
  173.         // Expires corresponds to max-age
  174.         if ($this->ages['max-age'] >= 0) {
  175.             header('Expires: ' . self::formatDate(time() + $this->ages['max-age']), 1);
  176.         }
  177.         // Cache-Control
  178.         if (!is_array($this->_CacheDirectives)) {
  179.             $this->_CacheDirectives = array();
  180.         }
  181.         foreach($this->ages as $dir => $value) {
  182.             if ($value >= 0) {
  183.                 array_push($this->_CacheDirectives, "$dir=$value");
  184.             }
  185.         }
  186.         if (count($this->_CacheDirectives) > 0) {
  187.             header('Cache-Control: ' .
  188.                 implode(', ', $this->_CacheDirectives), true);
  189.         }
  190.         // At least one of ETags of Last-Modified will be sent for cacheability
  191.         if ($this->eTag) {
  192.             header('ETag: ' . $this->eTag);
  193.         }
  194.         if ($this->lastModified) {
  195.             $lm = $this->lastModified;
  196.         } else if (!$this->eTag) {
  197.             $lm = time();
  198.         }
  199.         if (isset($lm)) {
  200.             header('Last-Modified: ' . self::formatDate($lm));
  201.         }
  202.  
  203.         // Content-*
  204.         foreach($this->_ContentDirectives as $key => $value) {
  205.             header('Content-'.ucfirst($key).': ' . $value, true);
  206.         }
  207.     }
  208.  
  209.     /**
  210.      * Determines whether the client has a fresh representation of the resource.
  211.      *
  212.      * This function compares the If-Modified-Since and If-None-Match headers
  213.      * provided by the client to the values specified for this resource, and
  214.      * returns true if the resource has been modified or false if the client's
  215.      * version is current.
  216.      *
  217.      * @return true if the version the client has is fresh, false if this is not the case and a new version needs to be returned
  218.      */
  219.     function isFresh() 
  220.     {
  221.         if (!isset($_SERVER['HTTP_IF_MODIFIED_SINCE']) &&
  222.             !isset($_SERVER['HTTP_IF_NONE_MATCH'])) {
  223.                 // No information provided by the client
  224.                 return false;
  225.             }
  226.  
  227.         if (isset($_SERVER['HTTP_IF_MODIFIED_SINCE']) && ! $this->eTag) {
  228.             if (!$this->lastModified) {
  229.                 $this->addCookie('T2', true);
  230.                 return false;
  231.             }
  232.             // Split the If-Modified-Since (Netscape < v6 gets this wrong)
  233.             $ifModifiedSince = explode(';', $_SERVER['HTTP_IF_MODIFIED_SINCE']);
  234.             // Turn the client request If-Modified-Since into a timestamp
  235.             $ifModifiedSince = strtotime($ifModifiedSince[0]);
  236.             // Compare timestamps (FIXME: make this test '!='?)
  237.             if ($this->lastModified > $ifModifiedSince) {
  238.                 return false;
  239.             }
  240.         }
  241.  
  242.         if (isset($_SERVER['HTTP_IF_NONE_MATCH']) && $this->eTag) {
  243.             if ($_SERVER['HTTP_IF_NONE_MATCH'] == '*') {
  244.                 return true;
  245.             }
  246.             $etags = preg_split('/,\s*/', $_SERVER['HTTP_IF_NONE_MATCH']);
  247.             foreach($etags as $e) {
  248.                 if ($this->etagMatch($e)) {
  249.                     return true;
  250.                 }
  251.             }
  252.             return false;
  253.         }
  254.  
  255.         return true;
  256.     }
  257.  
  258.     /**
  259.      * Compares an etag with the resource's entity tag.
  260.      *
  261.      * @param $etag Entity tag to compare
  262.      * @return true if they match, false if they don't
  263.      */
  264.     private function etagMatch($etag) 
  265.     {
  266.         if (!$this->eTag) {
  267.             return false;
  268.         }
  269.         if ((self::isEtagWeak($this->eTag) || self::isEtagWeak($etag))
  270.             &&
  271.                 ($_SERVER['REQUEST_METHOD'] != "GET" || isset($_SERVER['HTTP_RANGE'])))
  272.         {
  273.             // Weak validation only works for non-subrange GET requests
  274.             return false;
  275.         }
  276.         if (self::etagValidator($this->eTag) == self::etagValidator($etag)) {
  277.             return true;
  278.         } else {
  279.             return false;
  280.         }
  281.     }
  282.  
  283.     /**
  284.      * Determines if an entity tag is weak
  285.      *
  286.      * @param $etag Entity tag
  287.      * @return true if the entity tag is weak, false otherwise
  288.      */
  289.     static function isEtagWeak($etag) 
  290.     {
  291.         return (substr_compare($etag, 'W/', 0, 2) == 0);
  292.     }
  293.  
  294.     /**
  295.      * Returns the validator value of an entity tag
  296.      *
  297.      * @param $etag Entity tag
  298.      * @return The validator value ($etag if the entity tag is strong, or what's after 'W/' otherwise)
  299.      */
  300.     static function etagValidator($etag)
  301.     {
  302.         if (self::isEtagWeak($etag)) {
  303.             return substr($etag, 2);
  304.         } else {
  305.             return $etag;
  306.         }
  307.     }
  308.  
  309.     /**
  310.      * Sets Location header and response code. Forces replacement of any prior redirects.
  311.      *
  312.      * @param string $url 
  313.      * @param int $code 
  314.      */
  315.     public function setRedirect($url, $code = 302)
  316.     {
  317.         $this->redirection = array($url, $code);
  318.     }
  319.  
  320.     /**
  321.      * Is there a redirection
  322.      *
  323.      * @return boolean 
  324.      */
  325.     public function isRedirect()
  326.     {
  327.         return (count($this->redirection) === 2);
  328.     }
  329.  
  330.  
  331.     /**
  332.      * Get the max-age or s-maxage cache control directive value
  333.      *
  334.      * @param $type "max-age" or "s-maxage"
  335.      * @return The value in seconds; if -1 is returned, no max-age directive will be sent
  336.      */
  337.     function getDuration($type) 
  338.     {
  339.         if ($type != "max-age" && $type != "s-maxage") {
  340.             return trigger_error('Invalid type in getDuration : `'.$type.' is unknown', E_USER_NOTICE);
  341.         }
  342.         return $this->ages[$type];
  343.     }
  344.  
  345.     /**
  346.      * Set max-age or s-maxage cache control directive value
  347.      *
  348.      * @param $type "max-age" or "s-maxage"
  349.      * @param $time Duration as a positive number of seconds, a string
  350.      *         for strtotime(), or a negative number to disable this directive
  351.      * @return Updated value
  352.      */
  353.     function setDuration($type, $time) 
  354.     {
  355.         if ($type != "max-age" && $type != "s-maxage") {
  356.             return trigger_error('Invalid type in setDuration : `'.$type.' is unknown', E_USER_NOTICE);
  357.         }
  358.         if (is_numeric($time)) {
  359.             $time = intval($time);
  360.             if ($time < 0) {
  361.                 $time = -1;
  362.             }
  363.         } else {
  364.             if ($time == 'now') {
  365.                 $time = 0;
  366.             } else {
  367.                 $time = strtotime($time) - time();
  368.             }
  369.             if ($time < 0) {
  370.                 return trigger_error('Invalid time in setDuration : Bad interval specified to strtotime()', E_USER_NOTICE);
  371.             }
  372.         }
  373.         return $this->ages[$type] = $time;
  374.     }
  375.  
  376.     /**
  377.      * Set max-age and the Expires header value
  378.      *
  379.      * @param $time Duration as a positive number of seconds, a string
  380.      *         for strtotime(), or a negative number to disable this directive
  381.      * @return Updated value
  382.      */
  383.     function freshFor($time) 
  384.     {
  385.         return $this->setDuration('max-age', $time);
  386.     }
  387.  
  388.     /**
  389.      * Set/unset Cache-Control directive
  390.      *
  391.      * @param string $type Cache-Control directive (e.g. "public")
  392.      * @param boolean $set true or false to set or unset the parameter
  393.      */
  394.     function setCacheDirective($type, $set) 
  395.     {
  396.         $type = strtolower($type);
  397.         if (!in_array($type, $this->CacheDirectives)) {
  398.             return trigger_error('Invalid type in setCacheDirective : `'.$type.' is unknown', E_USER_NOTICE);
  399.         }
  400.         if ($set == true) {
  401.             if (!in_array($type, $this->_CacheDirectives)) {
  402.                 array_push($this->_CacheDirectives, $type);
  403.             }
  404.         } else {
  405.             $this->_CacheDirectives = array_diff($this->_CacheDirectives, array($type));
  406.         }
  407.     }
  408.  
  409.     /**
  410.      * Set/unset Content directive
  411.      *
  412.      * @param string $type Content directive (e.g. "type")
  413.      * @param mixed $set 
  414.      */
  415.     function setContentDirective($type, $set) 
  416.     {
  417.         $type = strtolower($type);
  418.         if (!in_array($type, $this->ContentDirectives)) {
  419.             return trigger_error('Invalid type in setContentDirective : `'.$type.' is unknown', E_USER_NOTICE);
  420.         }
  421.         $this->_ContentDirectives[$type] = $set;
  422.     }
  423.  
  424.  
  425.  
  426.     /**
  427.      * Set value of the ETag header
  428.      * The string will be quoted automatically.
  429.      *
  430.      * @param string $value Value (string)
  431.      */
  432.     function setEtag($value) 
  433.     {
  434.         $this->eTag = '"' . $value . '"';
  435.     }
  436.  
  437.     /**
  438.      * Set value of the ETag header to a weak value
  439.      * The string will be quoted automatically.
  440.      *
  441.      * @param string $value Value (string)
  442.      */
  443.     function setWeakEtag($value) 
  444.     {
  445.         $this->setEtag($value);
  446.         $this->eTag = "W/" . $this->eTag;
  447.     }
  448.  
  449.     /**
  450.      * Set value of the Last-Modified header
  451.      *
  452.      * @param string $value Unix timestamp
  453.      */
  454.     function setLastModified($value) 
  455.     {
  456.         $this->lastModified = $value;
  457.     }
  458.  
  459.     /**
  460.      * Set value of the Last-Modified header using the last modification date of a file
  461.      *
  462.      * @param string $file File whose modification time will be used
  463.      */
  464.     function setLastModifiedFromFile($file) 
  465.     {
  466.         $finfo = stat($file);
  467.         if (!$finfo) {
  468.             return;
  469.         }
  470.         $this->setLastModified($finfo['mtime']);
  471.     }
  472.  
  473.     /**
  474.      * Format a date in RFC 1123 date format
  475.      *
  476.      * @param string $time Time since epoch in seconds
  477.      * @return string Formatted date (e.g. "Sun, 27 Aug 2006 08:32:28 GMT")
  478.      */
  479.     static function formatDate($time) 
  480.     {
  481.         return gmdate("D, d M Y H:i:s", $time) . ' GMT';
  482.     }
  483.  
  484.  
  485.     /**
  486.      * setCookie (RFC 2109 compatible)
  487.      *
  488.      * @param string Name of the cookie
  489.      * @param string Value of the cookie
  490.      * @param int Lifetime of the cookie
  491.      * @param string Path where the cookie can be used
  492.      * @param string Domain which can read the cookie
  493.      * @param bool Secure mode?
  494.      * @param bool Only allow HTTP usage?
  495.      * @return bool True or false whether the method has successfully run
  496.      */
  497.     function addCookie($name, $value='', $maxage=0, $path='', $domain='', $secure=false, $HTTPOnly=false)
  498.     {
  499.         $ob = ini_get('output_buffering');
  500.  
  501.         // Abort the method if headers have already been sent, except when output buffering has been enabled
  502.         if ( headers_sent() && (bool) $ob === false || strtolower($ob) == 'off' )
  503.             return false;
  504.  
  505.         if ( !empty($domain) )
  506.         {
  507.             // Fix the domain to accept domains with and without 'www.'.
  508.             if ( strtolower( substr($domain, 0, 4) ) == 'www.' ) $domain = substr($domain, 4);
  509.             // Add the dot prefix to ensure compatibility with subdomains
  510.             if ( substr($domain, 0, 1) != '.' ) $domain = '.'.$domain;
  511.  
  512.             // Remove port information.
  513.             $port = strpos($domain, ':');
  514.  
  515.             if ( $port !== false ) $domain = substr($domain, 0, $port);
  516.         }
  517.  
  518.         $this->cookies[$name] = rawurlencode($name).'='.rawurlencode($value)
  519.         .(empty($domain) ? '' : '; Domain='.$domain)
  520.         .(empty($maxage) ? '' : '; Max-Age='.$maxage)
  521.         .(empty($path) ? '' : '; Path='.$path)
  522.         .(!$secure ? '' : '; Secure')
  523.         .(!$HTTPOnly ? '' : '; HttpOnly');
  524.  
  525.         return true;
  526.     }
  527.  
  528. }

Documentation generated on Thu, 13 Mar 2008 22:03:22 +0100 by phpDocumentor 1.4.1