<?php
/**
* HTTP_Accept class for dealing with the HTTP 'Accept' header
*
* PHP versions 4 and 5
*
* LICENSE: This source file is subject to the MIT License.
* The full text of this license is available at the following URL:
* http://www.opensource.org/licenses/mit-license.php
*
* @category HTTP
* @package HTTP_Accept
* @author Kevin Locke <kwl7@cornell.edu>
* @copyright 2007 Kevin Locke
* @license http://www.opensource.org/licenses/mit-license.php MIT License
* @version SVN: $Id: HTTP_Accept.php 22 2007-10-06 18:46:45Z kevin $
* @link http://pear.php.net/package/HTTP_Accept
*/
/**
* HTTP_Accept class for dealing with the HTTP 'Accept' header
*
* This class is intended to be used to parse the HTTP Accept header into
* usable information and provide a simple API for dealing with that
* information.
*
* The parsing of this class is designed to follow RFC 2616 to the letter,
* any deviations from that standard are bugs and should be reported to the
* maintainer.
*
* Often the class will be used very simply as
* <code>
* <?php
* $accept = new HTTP_Accept($_SERVER['HTTP_ACCEPT']);
* if ($accept->getQuality("image/png") > $accept->getQuality("image/jpeg"))
* // Send PNG image
* else
* // Send JPEG image
* ?>
* </code>
*
* However, for browsers which do not accurately describe their preferences,
* it may be necessary to check if a MIME Type is explicitly listed in their
* Accept header, in addition to being preferred to another type
*
* <code>
* <?php
* if ($accept->isMatchExact("application/xhtml+xml"))
* // Client specifically asked for this type at some quality level
* ?>
* </code>
*
*
* @category HTTP
* @package HTTP_Accept
* @access public
* @link http://pear.php.net/package/HTTP_Accept
*/
class HTTP_Accept
{
/**
* Array of types and their associated parameters, extensions, and quality
* factors, as represented in the Accept: header.
* Indexed by [type][subtype][index],
* and contains 'PARAMS', 'QUALITY', and 'EXTENSIONS' keys for the
* parameter set, quality factor, and extensions set respectively.
* Note: Since type, subtype, and parameters are case-insensitive
* (RFC 2045 5.1) they are stored as lower-case.
*
* @var array
* @access private
*/
var $acceptedtypes = array();
/**
* Regular expression to match a token, as defined in RFC 2045
*
* @var string
* @access private
*/
var $_matchtoken = '(?:[^[:cntrl:]()<>@,;:\\\\"\/\[\]?={} \t]+)';
/**
* Regular expression to match a quoted string, as defined in RFC 2045
*
* @var string
* @access private
*/
var $_matchqstring = '(?:"[^\\\\"]*(?:\\\\.[^\\\\"]*)*")';
/**
* Constructs a new HTTP_Accept object
*
* Initializes the HTTP_Accept class with a given accept string
* or creates a new (empty) HTTP_Accept object if no string is given
*
* Note: The behavior is a little strange here to accomodate
* missing headers (to be interpreted as accept all) as well as
* new empty objects which should accept nothing. This means that
* HTTP_Accept("") will be different than HTTP_Accept()
*
* @access public
* @return object HTTP_Accept
* @param string $acceptstring The value of an Accept: header
* Will often be $_SERVER['HTTP_ACCEPT']
* Note: If get_magic_quotes_gpc is on,
* run stripslashes() on the string first
*/
function HTTP_Accept()
{
if (func_num_args() == 0) {
// User wishes to create empty HTTP_Accept object
$this->acceptedtypes = array(
'*' => array(
'*' => array (
0 => array(
'PARAMS' => array(),
'QUALITY' => 0,
'EXTENSIONS' => array()
)
)
)
);
return;
}
$acceptstring = trim(func_get_arg(0));
if (empty($acceptstring)) {
// Accept header empty or not sent, interpret as "*/*"
$this->acceptedtypes = array(
'*' => array(
'*' => array (
0 => array(
'PARAMS' => array(),
'QUALITY' => 1,
'EXTENSIONS' => array()
)
)
)
);
return;
}
$matches = preg_match_all(
'/\s*('.$this->_matchtoken.')\/' . // typegroup/
'('.$this->_matchtoken.')' . // subtype
'((?:\s*;\s*'.$this->_matchtoken.'\s*' . // parameter
'(?:=\s*' . // optional =value
'(?:'.$this->_matchqstring.'|'.$this->_matchtoken.'))?)*)/', // value
$acceptstring, $acceptedtypes,
PREG_SET_ORDER);
if ($matches == 0) {
// Malformed Accept header
$this->acceptedtypes = array(
'*' => array(
'*' => array (
0 => array(
'PARAMS' => array(),
'QUALITY' => 1,
'EXTENSIONS' => array()
)
)
)
);
return;
}
foreach ($acceptedtypes as $accepted) {
$typefamily = strtolower($accepted[1]);
$subtype = strtolower($accepted[2]);
// */subtype is invalid according to grammar in section 14.1
// so we ignore it
if ($typefamily == '*' && $subtype != '*')
continue;
// Parse all arguments of the form "key=value"
$matches = preg_match_all('/;\s*('.$this->_matchtoken.')\s*' .
'(?:=\s*' .
'('.$this->_matchqstring.'|'.
$this->_matchtoken.'))?/',
$accepted[3], $args,
PREG_SET_ORDER);
$params = array();
$quality = -1;
$extensions = array();
foreach ($args as $arg) {
array_shift($arg);
if (!empty($arg[1])) {
// Strip quotes (Note: Can't use trim() in case "text\"")
$len = strlen($arg[1]);
if ($arg[1][0] == '"' && $arg[1][$len-1] == '"'
&& $len > 1) {
$arg[1] = substr($arg[1], 1, $len-2);
$arg[1] = stripslashes($arg[1]);
}
} else if (!isset($arg[1])) {
$arg[1] = null;
}
// Everything before q=# is a parameter, after is an extension
if ($quality >= 0) {
$extensions[$arg[0]] = $arg[1];
} else if ($arg[0] == 'q') {
$quality = (float)$arg[1];
if ($quality < 0)
$quality = 0;
else if ($quality > 1)
$quality = 1;
} else {
$arg[0] = strtolower($arg[0]);
// Values required for parameters,
// assume empty-string for missing values
if (isset($arg[1]))
$params[$arg[0]] = $arg[1];
else
$params[$arg[0]] = "";
}
}
if ($quality < 0)
$quality = 1;
else if ($quality == 0)
continue;
if (!isset($this->acceptedtypes[$typefamily]))
$this->acceptedtypes[$typefamily] = array();
if (!isset($this->acceptedtypes[$typefamily][$subtype]))
$this->acceptedtypes[$typefamily][$subtype] = array();
$this->acceptedtypes[$typefamily][$subtype][] =
array('PARAMS' => $params,
'QUALITY' => $quality,
'EXTENSIONS' => $extensions);
}
if (!isset($this->acceptedtypes['*']))
$this->acceptedtypes['*'] = array();
if (!isset($this->acceptedtypes['*']['*']))
$this->acceptedtypes['*']['*'] = array(
0 => array(
'PARAMS' => array(),
'QUALITY' => 0,
'EXTENSIONS' => array()
)
);
}
/**
* Gets the accepted quality factor for a given MIME Type
*
* Note: If there are multiple best matches
* (e.g. "text/html;level=4;charset=utf-8" matching both "text/html;level=4"
* and "text/html;charset=utf-8"), it returns the lowest quality factor as
* a conservative estimate. Further, if the ambiguity is between parameters
* and extensions (e.g. "text/html;level=4;q=1;ext=foo" matching both
* "text/html;level=4" and "text/html;q=1;ext=foo") the parameters take
* precidence.
*
* Usage Note: If the quality factor for all supported media types is 0,
* RFC 2616 specifies that applications SHOULD send an HTTP 406 (not
* acceptable) response.
*
* @access public
* @return double the quality value for the given MIME Type
* Quality values are in the range [0,1] where 0 means
* "not accepted" and 1 is "perfect quality".
* @param string $mimetype The MIME Type to query ("text/html")
* @param array $params Parameters of Type to query ([level => 4])
* @param array $extensions Extension parameters to query
*/
function getQuality($mimetype, $params = array(), $extensions = array())
{
$type = explode("/", $mimetype);
$supertype = strtolower($type[0]);
$subtype = strtolower($type[1]);
if ($params == null)
$params = array();
if ($extensions == null)
$extensions = array();
if (empty($this->acceptedtypes[$supertype])) {
if ($supertype == '*')
return 0;
else
return $this->getQuality("*/*", $params, $extensions);
}
if (empty($this->acceptedtypes[$supertype][$subtype])) {
if ($subtype == '*')
return $this->getQuality("*/*", $params, $extensions);
else
return $this->getQuality("$supertype/*", $params, $extensions);
}
$params = array_change_key_case($params, CASE_LOWER);
$matches = $this->_findBestMatchIndices($supertype, $subtype,
$params, $extensions);
if (count($matches) == 0) {
if ($subtype != '*')
return $this->getQuality("$supertype/*", $params, $extensions);
else if ($supertype != '*')
return $this->getQuality("*/*", $params, $extensions);
else
return 0;
}
$minquality = 1;
foreach ($matches as $match)
if ($this->acceptedtypes[$supertype][$subtype][$match]['QUALITY'] < $minquality)
$minquality = $this->acceptedtypes[$supertype][$subtype][$match]['QUALITY'];
return $minquality;
}
/**
* Determines if there is an exact match for the specified MIME Type
*
* @access public
* @return boolean true if there is an exact match to the given
* values, false otherwise.
* @param string $mimetype The MIME Type to query (e.g. "text/html")
* @param array $params Parameters of Type to query (e.g. [level => 4])
* @param array $extensions Extension parameters to query
*/
function isMatchExact($mimetype, $params = array(), $extensions = array())
{
$type = explode("/", $mimetype);
$supertype = strtolower($type[0]);
$subtype = strtolower($type[1]);
if ($params == null)
$params = array();
if ($extensions == null)
$extensions = array();
return $this->_findExactMatchIndex($supertype, $subtype,
$params, $extensions) >= 0;
}
/**
* Gets a list of all MIME Types explicitly accepted, sorted by quality
*
* @access public
* @return array list of MIME Types explicitly accepted, sorted
* in decreasing order of quality factor
*/
function getTypes()
{
$qvalues = array();
$types = array();
foreach ($this->acceptedtypes as $typefamily => $subtypes) {
if ($typefamily == '*')
continue;
foreach ($subtypes as $subtype => $variants) {
if ($subtype == '*')
continue;
$maxquality = 0;
foreach ($variants as $variant)
if ($variant['QUALITY'] > $maxquality)
$maxquality = $variant['QUALITY'];
if ($maxquality > 0) {
$qvalues[] = $maxquality;
$types[] = $typefamily.'/'.$subtype;
}
}
}
array_multisort($qvalues, SORT_DESC, SORT_NUMERIC,
$types, SORT_DESC, SORT_STRING);
return $types;
}
/**
* Gets the parameter sets for a given mime type, sorted by quality.
* Only parameter sets where the extensions set is empty will be returned.
*
* @access public
* @return array list of sets of name=>value parameter pairs
* in decreasing order of quality factor
* @param string $mimetype The MIME Type to query ("text/html")
*/
function getParameterSets($mimetype)
{
$type = explode("/", $mimetype);
$supertype = strtolower($type[0]);
$subtype = strtolower($type[1]);
if (!isset($this->acceptedtypes[$supertype])
|| !isset($this->acceptedtypes[$supertype][$subtype]))
return array();
$qvalues = array();
$paramsets = array();
foreach ($this->acceptedtypes[$supertype][$subtype] as $acceptedtype) {
if (count($acceptedtype['EXTENSIONS']) == 0) {
$qvalues[] = $acceptedtype['QUALITY'];
$paramsets[] = $acceptedtype['PARAMS'];
}
}
array_multisort($qvalues, SORT_DESC, SORT_NUMERIC,
$paramsets, SORT_DESC, SORT_STRING);
return $paramsets;
}
/**
* Gets the extension sets for a given mime type, sorted by quality.
* Only extension sets where the parameter set is empty will be returned.
*
* @access public
* @return array list of sets of name=>value extension pairs
* in decreasing order of quality factor
* @param string $mimetype The MIME Type to query ("text/html")
*/
function getExtensionSets($mimetype)
{
$type = explode("/", $mimetype);
$supertype = strtolower($type[0]);
$subtype = strtolower($type[1]);
if (!isset($this->acceptedtypes[$supertype])
|| !isset($this->acceptedtypes[$supertype][$subtype]))
return array();
$qvalues = array();
$extensionsets = array();
foreach ($this->acceptedtypes[$supertype][$subtype] as $acceptedtype) {
if (count($acceptedtype['PARAMS']) == 0) {
$qvalues[] = $acceptedtype['QUALITY'];
$extensionsets[] = $acceptedtype['EXTENSIONS'];
}
}
array_multisort($qvalues, SORT_DESC, SORT_NUMERIC,
$extensionsets, SORT_DESC, SORT_STRING);
return $extensionsets;
}
/**
* Adds a type to the set of accepted types
*
* @access public
* @param string $mimetype The MIME Type to add (e.g. "text/html")
* @param double $quality The quality value for the given MIME Type
* Quality values are in the range [0,1] where
* 0 means "not accepted" and 1 is
* "perfect quality".
* @param array $params Parameters of the type to add (e.g. [level => 4])
* @param array $extensions Extension parameters of the type to add
*/
function addType($mimetype, $quality = 1,
$params = array(), $extensions = array())
{
$type = explode("/", $mimetype);
$supertype = strtolower($type[0]);
$subtype = strtolower($type[1]);
if ($params == null)
$params = array();
if ($extensions == null)
$extensions = array();
$index = $this->_findExactMatchIndex($supertype, $subtype, $params, $extensions);
if ($index >= 0) {
$this->acceptedtypes[$supertype][$subtype][$index]['QUALITY'] = $quality;
} else {
if (!isset($this->acceptedtypes[$supertype]))
$this->acceptedtypes[$supertype] = array();
if (!isset($this->acceptedtypes[$supertype][$subtype]))
$this->acceptedtypes[$supertype][$subtype] = array();
$this->acceptedtypes[$supertype][$subtype][] =
array('PARAMS' => $params,
'QUALITY' => $quality,
'EXTENSIONS' => $extensions);
}
}
/**
* Removes a type from the set of accepted types
*
* @access public
* @param string $mimetype The MIME Type to remove (e.g. "text/html")
* @param array $params Parameters of the type to remove (e.g. [level => 4])
* @param array $extensions Extension parameters of the type to remove
*/
function removeType($mimetype, $params = array(), $extensions = array())
{
$type = explode("/", $mimetype);
$supertype = strtolower($type[0]);
$subtype = strtolower($type[1]);
if ($params == null)
$params = array();
if ($extensions == null)
$extensions = array();
$index = $this->_findExactMatchIndex($supertype, $subtype, $params, $extensions);
if ($index >= 0) {
$this->acceptedtypes[$supertype][$subtype] =
array_merge(array_slice($this->acceptedtypes[$supertype][$subtype],
0, $index),
array_slice($this->acceptedtypes[$supertype][$subtype],
$index+1));
}
}
/**
* Gets a string representation suitable for use in an HTTP Accept header
*
* @access public
* @return string a string representation of this object
*/
function __toString()
{
$accepted = array();
$qvalues = array();
foreach ($this->acceptedtypes as $supertype => $subtypes) {
foreach ($subtypes as $subtype => $entries) {
foreach ($entries as $entry) {
$accepted[] = array('TYPE' => "$supertype/$subtype",
'QUALITY' => $entry['QUALITY'],
'PARAMS' => $entry['PARAMS'],
'EXTENSIONS' => $entry['EXTENSIONS']);
$qvalues[] = $entry['QUALITY'];
}
}
}
array_multisort($qvalues, SORT_DESC, SORT_NUMERIC,
$accepted);
$str = "";
foreach ($accepted as $accept) {
// Skip the catchall value if it is 0, since this is implied
if ($accept['TYPE'] == '*/*' &&
$accept['QUALITY'] == 0 &&
count($accept['PARAMS']) == 0 &&
count($accept['EXTENSIONS'] == 0))
continue;
$str = $str.$accept['TYPE'].';';
foreach ($accept['PARAMS'] as $param => $value) {
if (preg_match('/^'.$this->_matchtoken.'$/', $value))
$str = $str.$param.'='.$value.';';
else
$str = $str.$param.'="'.addcslashes($value,'"\\').'";';
}
if ($accept['QUALITY'] < 1 || !empty($accept['EXTENSIONS']))
$str = $str.'q='.$accept['QUALITY'].';';
foreach ($accept['EXTENSIONS'] as $extension => $value) {
if (preg_match('/^'.$this->_matchtoken.'$/', $value))
$str = $str.$extension.'='.$value.';';
else
$str = $str.$extension.'="'.addcslashes($value,'"\\').'";';
}
$str[strlen($str)-1] = ',';
}
return rtrim($str, ',');
}
/**
* Finds the index of an exact match for the specified MIME Type
*
* @access private
* @return int the index of an exact match if found,
* -1 otherwise
* @param string $supertype The general MIME Type to find (e.g. "text")
* @param string $subtype The MIME subtype to find (e.g. "html")
* @param array $params Parameters of Type to find ([level => 4])
* @param array $extensions Extension parameters to find
*/
function _findExactMatchIndex($supertype, $subtype, $params, $extensions)
{
if (empty($this->acceptedtypes[$supertype])
|| empty($this->acceptedtypes[$supertype][$subtype]))
return -1;
$params = array_change_key_case($params, CASE_LOWER);
$parammatches = array();
foreach ($this->acceptedtypes[$supertype][$subtype] as $index => $typematch)
if ($typematch['PARAMS'] == $params
&& $typematch['EXTENSIONS'] == $extensions)
return $index;
return -1;
}
/**
* Finds the indices of the best matches for the specified MIME Type
*
* A "match" in this context is an exact type match and no extraneous
* matches for parameters or extensions (so the best match for
* "text/html;level=4" may be "text/html" but not the other way around).
*
* "Best" is interpreted as the entries that match the most
* parameters and extensions (the sum of the number of matches)
*
* @access private
* @return array an array of the indices of the best matches
* (empty if no matches)
* @param string $supertype The general MIME Type to find (e.g. "text")
* @param string $subtype The MIME subtype to find (e.g. "html")
* @param array $params Parameters of Type to find ([level => 4])
* @param array $extensions Extension parameters to find
*/
function _findBestMatchIndices($supertype, $subtype, $params, $extensions)
{
$bestmatches = array();
$bestlength = 0;
if (empty($this->acceptedtypes[$supertype])
|| empty($this->acceptedtypes[$supertype][$subtype]))
return $bestmatches;
foreach ($this->acceptedtypes[$supertype][$subtype] as $index => $typematch) {
if (count(array_diff_assoc($typematch['PARAMS'], $params)) == 0
&& count(array_diff_assoc($typematch['EXTENSIONS'],
$extensions)) == 0) {
$length = count($typematch['PARAMS'])
+ count($typematch['EXTENSIONS']);
if ($length > $bestlength) {
$bestmatches = array($index);
$bestlength = $length;
} else if ($length == $bestlength) {
$bestmatches[] = $index;
}
}
}
return $bestmatches;
}
}
// vim: set ts=4 sts=4 sw=4 et:
?>