Added docs to MediaType class.

This commit is contained in:
flash 2024-08-02 00:21:00 +00:00
parent 7ef130629b
commit 5be38a7090
2 changed files with 120 additions and 14 deletions

View file

@ -1 +1 @@
0.2408.12356 0.2408.20020

View file

@ -1,17 +1,24 @@
<?php <?php
// MediaType.php // MediaType.php
// Created: 2022-02-10 // Created: 2022-02-10
// Updated: 2024-08-01 // Updated: 2024-08-02
namespace Index; namespace Index;
use InvalidArgumentException; use InvalidArgumentException;
use RuntimeException;
use Stringable; use Stringable;
/** /**
* Implements a structure for representing and comparing media/mime types. * Implements a structure for representing and comparing media/mime types.
*/ */
class MediaType implements Stringable, IComparable, IEquatable { 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( public function __construct(
private string $category, private string $category,
private string $kind, private string $kind,
@ -19,74 +26,155 @@ class MediaType implements Stringable, IComparable, IEquatable {
private array $params 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 { public function getCategory(): string {
return $this->category; return $this->category;
} }
/**
* Returns the media type kind.
*
* @return string Media type kind.
*/
public function getKind(): string { public function getKind(): string {
return $this->kind; return $this->kind;
} }
/**
* Returns the media type suffix.
*
* @return string Media type suffix.
*/
public function getSuffix(): string { public function getSuffix(): string {
return $this->suffix; return $this->suffix;
} }
/**
* Returns all media type parameters.
*
* @return array<string, mixed> Media type parameters
*/
public function getParams(): array { public function getParams(): array {
return $this->params; 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 { public function hasParam(string $name): bool {
return isset($this->params[$name]); 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])) if(!isset($this->params[$name]))
return null; return null;
return filter_var($this->params[$name], $filter, $options); 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 { public function getCharset(): string {
return $this->getParam('charset', FILTER_DEFAULT, FILTER_FLAG_STRIP_LOW | FILTER_FLAG_STRIP_HIGH) ?? 'utf-8'; 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 { public function getQuality(): float {
return max(min(round($this->getParam('q', FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION) ?? 1, 2), 1), 0); 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 { public function compareCategory(string $category): int {
return ($this->category === '*' || $category === '*') return ($this->category === '*' || $category === '*')
? 0 : strcmp($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 { public function matchCategory(string $category): bool {
return $this->category === '*' || $category === '*' || $this->category === $category; 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 { public function compareKind(string $kind): int {
return ($this->kind === '*' || $kind === '*') return ($this->kind === '*' || $kind === '*')
? 0 : strcmp($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 { public function matchKind(string $kind): bool {
return $this->kind === '*' || $kind === '*' || $this->kind === $kind; 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 { public function compareSuffix(string $suffix): int {
return strcmp($this->suffix, $suffix); 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 { public function matchSuffix(string $suffix): bool {
return $this->suffix === $suffix; return $this->suffix === $suffix;
} }
public function compare(mixed $other): int { public function compare(mixed $other): int {
if(!($other instanceof MediaType)) { if(!($other instanceof MediaType))
try { try {
$other = self::parse((string)$other); $other = self::parse((string)$other);
} catch(InvalidArgumentException $ex) { } catch(InvalidArgumentException $ex) {
return -1; return -1;
} }
}
if(($match = self::compareCategory($other->category)) !== 0) if(($match = self::compareCategory($other->category)) !== 0)
return $match; return $match;
@ -97,13 +185,12 @@ class MediaType implements Stringable, IComparable, IEquatable {
} }
public function equals(mixed $other): bool { public function equals(mixed $other): bool {
if(!($other instanceof MediaType)) { if(!($other instanceof MediaType))
try { try {
$other = self::parse((string)$other); $other = self::parse((string)$other);
} catch(InvalidArgumentException $ex) { } catch(InvalidArgumentException $ex) {
return false; return false;
} }
}
if(!$this->matchCategory($other->category)) if(!$this->matchCategory($other->category))
return false; return false;
@ -130,14 +217,20 @@ class MediaType implements Stringable, IComparable, IEquatable {
return $string; 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]; $kind = $kindSplit[0];
$suffix = $kindSplit[1] ?? ''; $suffix = $kindSplit[1] ?? '';
@ -151,7 +244,20 @@ class MediaType implements Stringable, IComparable, IEquatable {
return new MediaType($category, $kind, $suffix, $params); 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 { 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);
} }
} }