Added docs to MediaType class.

VERSION

@@ -1 +1 @@
-0.2408.12356
+0.2408.20020

src/MediaType.php

@@ -1,17 +1,24 @@
 <?php
 // MediaType.php
 // Created: 2022-02-10
-// Updated: 2024-08-01
+// Updated: 2024-08-02
 
 namespace Index;
 
 use InvalidArgumentException;
+use RuntimeException;
 use Stringable;
 
 /**
  * Implements a structure for representing and comparing media/mime types.
  */
 class MediaType implements Stringable, IComparable, IEquatable {
+    /**
+     * @param string $category Media type category.
+     * @param string $kind Media type kind.
+     * @param string $suffix Media type suffix.
+     * @param array<string, mixed> $params Media type parameters.
+     */
     public function __construct(
         private string $category,
         private string $kind,
@@ -19,74 +26,155 @@ class MediaType implements Stringable, IComparable, IEquatable {
         private array $params
     ) {}
 
+    /**
+     * Returns the media type category.
+     *
+     * Expected return values for this are 'application', 'audio', 'image', 'message', 'multipart', 'text', 'video', 'font', 'example', 'model', 'haptics' or '*' for wildcard.
+     *
+     * @return string Media type category.
+     */
     public function getCategory(): string {
         return $this->category;
     }
 
+    /**
+     * Returns the media type kind.
+     *
+     * @return string Media type kind.
+     */
     public function getKind(): string {
         return $this->kind;
     }
 
+    /**
+     * Returns the media type suffix.
+     *
+     * @return string Media type suffix.
+     */
     public function getSuffix(): string {
         return $this->suffix;
     }
 
+    /**
+     * Returns all media type parameters.
+     *
+     * @return array<string, mixed> Media type parameters
+     */
     public function getParams(): array {
         return $this->params;
     }
 
+    /**
+     * Checks if a media type parameter is present.
+     *
+     * @param string $name Media type parameter name.
+     * @return bool true if the parameter is present.
+     */
     public function hasParam(string $name): bool {
         return isset($this->params[$name]);
     }
 
-    public function getParam(string $name, int $filter = FILTER_DEFAULT, $options = null) {
+    /**
+     * Retrieves a media type parameter, or null if it is not present.
+     *
+     * @param string $name Media type parameter name.
+     * @param int $filter A PHP filter extension filter constant.
+     * @param array|int $options Options for the PHP filter.
+     * @return mixed Value of the parameter, null if not present.
+     */
+    public function getParam(string $name, int $filter = FILTER_DEFAULT, $options = null): mixed {
         if(!isset($this->params[$name]))
             return null;
         return filter_var($this->params[$name], $filter, $options);
     }
 
+    /**
+     * Retrieves the charset parameter from the media type parameters.
+     *
+     * @return string Character specified in media type.
+     */
     public function getCharset(): string {
         return $this->getParam('charset', FILTER_DEFAULT, FILTER_FLAG_STRIP_LOW | FILTER_FLAG_STRIP_HIGH) ?? 'utf-8';
     }
 
+    /**
+     * Retrieves the q parameter from the media type parameters.
+     *
+     * @return float Quality specified for the media type.
+     */
     public function getQuality(): float {
         return max(min(round($this->getParam('q', FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION) ?? 1, 2), 1), 0);
     }
 
+    /**
+     * Compares the category string with another one. Can be used for sorting.
+     *
+     * @param string $category Category string to compare with.
+     * @return int 0 if they are a match, something else if not.
+     */
     public function compareCategory(string $category): int {
         return ($this->category === '*' || $category === '*')
             ? 0 : strcmp($this->category, $category);
     }
 
+    /**
+     * Matches the category string with another one.
+     *
+     * @param string $category Category string to match with.
+     * @return bool true if they are a match.
+     */
     public function matchCategory(string $category): bool {
         return $this->category === '*' || $category === '*' || $this->category === $category;
     }
 
+    /**
+     * Compares the kind string with another one. Can be used for sorting.
+     *
+     * @param string $kind Kind string to compare with.
+     * @return int 0 if they are a match, something else if not.
+     */
     public function compareKind(string $kind): int {
         return ($this->kind === '*' || $kind === '*')
             ? 0 : strcmp($this->kind, $kind);
     }
 
+    /**
+     * Matches the kind string with another one.
+     *
+     * @param string $kind Kind string to match with.
+     * @return bool true if they are a match.
+     */
     public function matchKind(string $kind): bool {
         return $this->kind === '*' || $kind === '*' || $this->kind === $kind;
     }
 
+    /**
+     * Compares the suffix string with another one. Can be used for sorting.
+     *
+     * @param string $suffix Suffix string to compare with.
+     * @return int 0 if they are a match, something else if not.
+     */
     public function compareSuffix(string $suffix): int {
         return strcmp($this->suffix, $suffix);
     }
 
+    /**
+     * Matches the suffix string with another one.
+     *
+     * @param string $suffix Suffix string to match with.
+     * @return bool true if they are a match.
+     */
     public function matchSuffix(string $suffix): bool {
         return $this->suffix === $suffix;
     }
 
     public function compare(mixed $other): int {
-        if(!($other instanceof MediaType)) {
+        if(!($other instanceof MediaType))
             try {
                 $other = self::parse((string)$other);
             } catch(InvalidArgumentException $ex) {
                 return -1;
             }
-        }
 
         if(($match = self::compareCategory($other->category)) !== 0)
             return $match;
@@ -97,13 +185,12 @@ class MediaType implements Stringable, IComparable, IEquatable {
     }
 
     public function equals(mixed $other): bool {
-        if(!($other instanceof MediaType)) {
+        if(!($other instanceof MediaType))
             try {
                 $other = self::parse((string)$other);
             } catch(InvalidArgumentException $ex) {
                 return false;
             }
-        }
 
         if(!$this->matchCategory($other->category))
             return false;
@@ -130,14 +217,20 @@ class MediaType implements Stringable, IComparable, IEquatable {
         return $string;
     }
 
-    public static function parse(string $mediaTypeStr): MediaType {
+    /**
-        $parts = explode(';', $mediaTypeStr);
+     * Parses a media type string into a MediaType object.
-        $mediaTypeStr = array_shift($parts);
+     *
-        $mediaTypeParts = explode('/', $mediaTypeStr, 2);
+     * @param string $string Media type string.
+     * @return MediaType Object representing the given string.
+     */
+    public static function parse(string $string): MediaType {
+        $parts = explode(';', $string);
+        $string = array_shift($parts);
+        $stringParts = explode('/', $string, 2);
 
-        $category = $mediaTypeParts[0];
+        $category = $stringParts[0];
 
-        $kindSplit = explode('+', $mediaTypeParts[1] ?? '', 2);
+        $kindSplit = explode('+', $stringParts[1] ?? '', 2);
         $kind = $kindSplit[0];
         $suffix = $kindSplit[1] ?? '';
 
@@ -151,7 +244,20 @@ class MediaType implements Stringable, IComparable, IEquatable {
         return new MediaType($category, $kind, $suffix, $params);
     }
 
+    /**
+     * Reads the media type of a given file path.
+     *
+     * Uses mime_content_type().
+     *
+     * @param string $path File path.
+     * @throws RuntimeException If $path does not exist.
+     * @return MediaType Media type of file.
+     */
     public static function fromPath(string $path): MediaType {
-        return self::parse(mime_content_type($path));
+        $string = mime_content_type($path);
+        if($string === false)
+            throw new RuntimeException('File specified in $path does not exist.');
+
+        return self::parse($string);
     }
 }