diff --git a/VERSION b/VERSION index 2d4ead4..aea044f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.2408.12356 +0.2408.20020 diff --git a/src/MediaType.php b/src/MediaType.php index e9c752f..b04a708 100644 --- a/src/MediaType.php +++ b/src/MediaType.php @@ -1,17 +1,24 @@ $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 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); - $mediaTypeStr = array_shift($parts); - $mediaTypeParts = explode('/', $mediaTypeStr, 2); + /** + * Parses a media type string into a MediaType object. + * + * @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); } }