Merge branch 'master' of github.com:ramsey/mimeparse

* 'master' of github.com:ramsey/mimeparse:
  More accurately differentiate between media-ranges and mime-types.
  Minor comment improvements.
  Wrap comments at 80 characters wherever possible.
  Make difference between parseMediaRange and parseMimeType more clear.
  Clarify exception message.
  Improve and correct some documentation.
  Use order of $supported array instead of $tieBreaker to break ties.
  Fix return value documentation for qualityAndFitnessParsed.
  Simplify process of rejecting unacceptable types.
  Rename fitnessAndQualityParsed to represent order of returned array.
  Use the term "generic subtype" instead of "format".
  Make some comments more PHP-centric.

Author: Ben Ramsey

src/Bitworking/Mimeparse.php

@@ -1,10 +1,11 @@
 <?php
 /**
- * Mimeparse class. This class provides basic functions for handling mime-types. It can
- * handle matching mime-types against a list of media-ranges. See section
- * 14.1 of the HTTP specification [RFC 2616] for a complete explanation.
+ * Mimeparse class. Provides basic functions for handling mime-types. It can
+ * match mime-types against a list of media-ranges. See section 14.1 of the
+ * HTTP specification [RFC 2616] for a complete explanation.
  *
- * It's just a port to php from original Python code (http://code.google.com/p/mimeparse/).
+ * It's a PHP port of the original Python code
+ * (http://code.google.com/p/mimeparse/).
  *
  * Ported from version 0.1.2. Comments are mostly excerpted from the original.
  *
@@ -17,27 +18,30 @@
 class Mimeparse
 {
     /**
-     * Parses a mime-type and returns an array with its components.
+     * Parses a media-range and returns an array with its components.
      *
-     * The array returned contains:
+     * The returned array contains:
      *
      * 1. type: The type categorization.
      * 2. subtype: The subtype categorization.
-     * 3. params: A hash of all the parameters for the media range.
-     * 4. format: The content format.
+     * 3. params: An associative array of all the parameters for the
+     *    media-range.
+     * 4. generic subtype: A more generic subtype, if one is present. See
+     *    http://tools.ietf.org/html/rfc3023#appendix-A.12
      *
-     * For example, the media range "application/xhtml+xml;q=0.5" would
-     * get parsed into:
+     * For example, the media-range "application/xhtml+xml;q=0.5" would get
+     * parsed into:
      *
-     * array("application", "xhtml", array( "q" => "0.5" ), "xml")
+     * array("application", "xhtml+xml", array( "q" => "0.5" ), "xml")
      *
-     * @param string $mimeType
-     * @return array ($type, $subtype, $params)
-     * @throws UnexpectedValueException when $mimeType does not include a valid subtype
+     * @param string $mediaRange
+     * @return array ($type, $subtype, $params, $genericSubtype)
+     * @throws UnexpectedValueException when $mediaRange does not include a
+     * valid subtype
      */
-    public static function parseMimeType($mimeType)
+    public static function parseMediaRange($mediaRange)
     {
-        $parts = explode(';', $mimeType);
+        $parts = explode(';', $mediaRange);
 
         $params = array();
         foreach ($parts as $i => $param) {
@@ -49,78 +53,72 @@ public static function parseMimeType($mimeType)
 
         $fullType = trim($parts[0]);
 
-        // Java URLConnection class sends an Accept header that includes a single "*"
-        // Turn it into a legal wildcard.
+        // Java URLConnection class sends an Accept header that includes a
+        // single "*". Turn it into a legal wildcard.
         if ($fullType == '*') {
             $fullType = '*/*';
         }
 
         list($type, $subtype) = explode('/', $fullType);
 
         if (!$subtype) {
-            throw new \UnexpectedValueException('malformed mime type');
+            throw new \UnexpectedValueException('Malformed media-range: '.$mediaRange);
         }
 
-        if (false !== strpos($subtype, '+')) {
-            // don't rewrite subtype to prevent compatibility issues
-            list(/*$subtype*/, $format) = explode('+', $subtype, 2);
+        $plusPos = strpos($subtype, '+');
+        if (false !== $plusPos) {
+            $genericSubtype = substr($subtype, $plusPos + 1);
         } else {
-            $format = $subtype;
+            $genericSubtype = $subtype;
         }
 
-        return array(trim($type), trim($subtype), $params, $format);
+        return array(trim($type), trim($subtype), $params, $genericSubtype);
     }
 
 
     /**
-     * Carves up a media range and returns an Array of the
-     * [type, subtype, params] where "params" is a Hash of all
-     * the parameters for the media range.
-     *
-     * For example, the media range "application/*;q=0.5" would
-     * get parsed into:
-     *
-     * array("application", "*", ( "q", "0.5" ))
+     * Parses a media-range via Mimeparse::parseMediaRange() and guarantees that
+     * there is a value for the "q" param, filling it in with a proper default
+     * if necessary.
      *
-     * In addition this function also guarantees that there
-     * is a value for "q" in the params dictionary, filling it
-     * in with a proper default if necessary.
-     *
-     * @param string $range
-     * @return array ($type, $subtype, $params)
+     * @param string $mediaRange
+     * @return array ($type, $subtype, $params, $genericSubtype)
      */
-    protected static function parseMediaRange($range)
+    protected static function parseAndNormalizeMediaRange($mediaRange)
     {
-        list($type, $subtype, $params) = self::parseMimeType($range);
+        $parsedMediaRange = self::parseMediaRange($mediaRange);
+        $params = $parsedMediaRange[2];
 
         if (!isset($params['q'])
             || !is_numeric($params['q'])
             || floatval($params['q']) > 1
             || floatval($params['q']) < 0
         ) {
-            $params['q'] = '1';
+            $parsedMediaRange[2]['q'] = '1';
         }
 
-        return array($type, $subtype, $params);
+        return $parsedMediaRange;
     }
 
     /**
      * Find the best match for a given mime-type against a list of
-     * media-ranges that have already been parsed by Mimeparse::parseMediaRange()
+     * media-ranges that have already been parsed by
+     * Mimeparse::parseAndNormalizeMediaRange()
      *
-     * Returns the fitness and the "q" quality parameter of the best match, or an
-     * array [-1, 0] if no match was found. Just as for Mimeparse::quality(),
-     * $parsedRanges must be an Enumerable of parsed media-ranges.
+     * Returns the fitness and the "q" quality parameter of the best match, or
+     * an array [-1, 0] if no match was found. Just as for
+     * Mimeparse::quality(), $parsedRanges must be an array of parsed
+     * media-ranges.
      *
      * @param string $mimeType
      * @param array  $parsedRanges
-     * @return array ($bestFitness, $bestFitQuality)
+     * @return array ($bestFitQuality, $bestFitness)
      */
-    protected static function fitnessAndQualityParsed($mimeType, $parsedRanges)
+    protected static function qualityAndFitnessParsed($mimeType, $parsedRanges)
     {
         $bestFitness = -1;
         $bestFitQuality = 0;
-        list($targetType, $targetSubtype, $targetParams) = self::parseMediaRange($mimeType);
+        list($targetType, $targetSubtype, $targetParams) = self::parseAndNormalizeMediaRange($mimeType);
 
         foreach ($parsedRanges as $item) {
             list($type, $subtype, $params) = $item;
@@ -151,25 +149,26 @@ protected static function fitnessAndQualityParsed($mimeType, $parsedRanges)
 
     /**
      * Find the best match for a given mime-type against a list of
-     * media-ranges that have already been parsed by Mimeparse::parseMediaRange()
+     * media-ranges that have already been parsed by
+     * Mimeparse::parseAndNormalizeMediaRange()
      *
-     * Returns the "q" quality parameter of the best match, 0 if no match
-     * was found. This function behaves the same as Mimeparse::quality() except that
-     * $parsedRanges must be an Enumerable of parsed media-ranges.
+     * Returns the "q" quality parameter of the best match, 0 if no match was
+     * found. This function behaves the same as Mimeparse::quality() except
+     * that $parsedRanges must be an array of parsed media-ranges.
      *
      * @param string $mimeType
      * @param array  $parsedRanges
      * @return float $q
      */
     protected static function qualityParsed($mimeType, $parsedRanges)
     {
-        list($q, $fitness) = self::fitnessAndQualityParsed($mimeType, $parsedRanges);
+        list($q, $fitness) = self::qualityAndFitnessParsed($mimeType, $parsedRanges);
         return $q;
     }
 
     /**
-     * Returns the quality "q" of a mime-type when compared against
-     * the media-ranges in ranges. For example:
+     * Returns the quality "q" of a mime-type when compared against the
+     * media-ranges in ranges. For example:
      *
      * Mimeparse::quality("text/html", "text/*;q=0.3, text/html;q=0.7,
      * text/html;level=1, text/html;level=2;q=0.4, *\/*;q=0.5")
@@ -184,71 +183,57 @@ public static function quality($mimeType, $ranges)
         $parsedRanges = explode(',', $ranges);
 
         foreach ($parsedRanges as $i => $r) {
-            $parsedRanges[$i] = self::parseMediaRange($r);
+            $parsedRanges[$i] = self::parseAndNormalizeMediaRange($r);
         }
 
         return self::qualityParsed($mimeType, $parsedRanges);
     }
 
     /**
-     * Takes a list of supported mime-types and finds the best match
-     * for all the media-ranges listed in header. The value of header
-     * must be a string that conforms to the format of the HTTP Accept:
-     * header. The value of supported is an Enumerable of mime-types
+     * Takes a list of supported mime-types and finds the best match for all
+     * the media-ranges listed in header. The value of $header must be a
+     * string that conforms to the format of the HTTP Accept: header. The
+     * value of $supported is an array of mime-types.
+     *
+     * In case of ties the mime-type with the lowest index in $supported will
+     * be used.
      *
      * Mimeparse::bestMatch(array("application/xbel+xml", "text/xml"), "text/*;q=0.5,*\/*; q=0.1")
      * => "text/xml"
      *
      * @param  array  $supported
      * @param  string $header
-     * @param  string $tieBreaker In case of a tie, this mime-type is preferred
      * @return mixed  $mimeType or NULL
      */
-    public static function bestMatch($supported, $header, $tieBreaker = null)
+    public static function bestMatch($supported, $header)
     {
         $parsedHeader = explode(',', $header);
 
         foreach ($parsedHeader as $i => $r) {
-            $parsedHeader[$i] = self::parseMediaRange($r);
+            $parsedHeader[$i] = self::parseAndNormalizeMediaRange($r);
         }
 
         $weightedMatches = array();
-        foreach ($supported as $mimeType) {
-            $weightedMatches[] = array(
-                self::fitnessAndQualityParsed($mimeType, $parsedHeader),
-                $mimeType
-            );
-        }
-
-        // If the best fit quality is 0 for anything, then it is
-        // not acceptable for the client; remove it from the list
-        // of weighted matches.
-        $unacceptableTypes = array();
-        foreach ($weightedMatches as $k => $v) {
-            if (empty($v[0][0])) {
-                $unacceptableTypes[] = $k;
+        foreach ($supported as $index => $mimeType) {
+            list($quality, $fitness) = self::qualityAndFitnessParsed($mimeType, $parsedHeader);
+            if (!empty($quality)) {
+                // Mime-types closer to the beginning of the array are 
+                // preferred. This preference score is used to break ties.
+                $preference = 0 - $index;
+                $weightedMatches[] = array(
+                    array($quality, $fitness, $preference),
+                    $mimeType
+                );
             }
         }
-        foreach ($unacceptableTypes as $weightedMatchKey) {
-            unset($weightedMatches[$weightedMatchKey]);
-        }
 
+        // Note that since fitness and preference are present in 
+        // $weightedMatches they will also be used when sorting (after quality 
+        // level).
         array_multisort($weightedMatches);
-        $a = array_pop($weightedMatches);
-
-        // If there's a tie breaker specified, see if we have any ties
-        // and then break them with the $tieBreaker
-        if ($tieBreaker) {
-            array_push($weightedMatches, $a);
-            $ties = array_filter($weightedMatches, function ($val) use ($a) {
-                return ($val[0] == $a[0]);
-            });
-            if (count($ties) > 1 && in_array(array($a[0], $tieBreaker), $ties)) {
-                return $tieBreaker;
-            }
-        }
+        $firstChoice = array_pop($weightedMatches);
 
-        return (empty($a[0][0]) ? null : $a[1]);
+        return (empty($firstChoice[0][0]) ? null : $firstChoice[1]);
     }
 
     /**