flash/index
flash/index
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Added docs to MediaType class.

Browse source
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
Show stats Download patch file Download diff file Expand all files Collapse all files

2
VERSION
View file

@ -1 +1 @@
0.2408.12356
0.2408.20020

132
src/MediaType.php
View file

@ -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);
$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);
}
}