feat: accept null values in MediaTypeParser methods

CHANGELOG.md

@@ -2,10 +2,18 @@
 
 ## 3.1.0 (YYYY-MM-DD)
 
-## Bug fixes
+### Features
+
+- `MediaTypeParser::parseOrNull()`, `MediaTypeParse::parse()` now also accepts passing `null` values as an argument. The new argument type for both methods is now `string|null`.
+
+### Bug fixes
 
 - Fixes minor bug in `MediaType::isFont()` method; it will now correctly return `true` for media types that have an essence of `application/vnd.ms-opentype`.
 
+### Deprecated
+
+- `MediaTypeParser::parse()` is deprecated and renamed to `MediaTypeParser::parseOrThrow()`, to be more explicit that it can throw exceptions. Call `MediaTypeParser::parseOrThrow()` instead.
+
 ## 3.0.0 (2024-04-03)
 
 ### Breaking changes

src/MediaTypeParser.php

@@ -9,18 +9,30 @@
  * @see https://mimesniff.spec.whatwg.org/#parsing-a-mime-type
  */
 final class MediaTypeParser {
-	public function parseOrNull( string $s ): MediaType|null {
+	public function parseOrNull( string|null $s ): MediaType|null {
 		try {
-			return $this->parse( $s );
+			return $this->parseOrThrow( $s );
 		} catch ( MediaTypeParserException | AssertionException ) {
 			return null;
 		}
 	}
 
 	/**
+	 * @deprecated Deprecated in `v3.1.0`. Call `parseOrThrow()` instead.
 	 * @throws MediaTypeParserException|InvariantException
 	 */
-	public function parse( string $s ): MediaType {
+	public function parse( string|null $s ): MediaType {
+		return $this->parseOrThrow( $s );
+	}
+
+	/**
+	 * @throws MediaTypeParserException|InvariantException
+	 */
+	public function parseOrThrow( string|null $s ): MediaType {
+		if ( $s === null ) {
+			throw new MediaTypeParserException();
+		}
+
 		$normalized = Utf8Utils::trimHttpWhitespace( $s );
 		if ( $normalized === '' ) {
 			throw new MediaTypeParserException();

tests/MediaTypeParserTest.php

@@ -24,7 +24,7 @@ public function testValidMediaTypes(
 		string $expectedSubType,
 		array $expectedParameters
 	): void {
-		$parsedValue = $this->parser->parse( $validMediaType );
+		$parsedValue = $this->parser->parseOrThrow( $validMediaType );
 
 		$this->assertInstanceOf( MediaType::class, $parsedValue );
 		$this->assertEquals( $expectedType, $parsedValue->type );
@@ -35,7 +35,7 @@ public function testValidMediaTypes(
 	#[DataProvider( "provideInvalidMediaTypes" )]
 	public function testInvalidMediaTypes( $invalidMediaType ): void {
 		$this->expectException( MediaTypeParserException::class );
-		$this->parser->parse( $invalidMediaType );
+		$this->parser->parseOrThrow( $invalidMediaType );
 	}
 
 	public static function provideValidMediaTypes(): array {
@@ -101,6 +101,7 @@ public static function provideValidMediaTypes(): array {
 
 	public static function provideInvalidMediaTypes(): array {
 		return [
+			[ null ],
 			[ '' ],
 			[ '    ' ],
 			[ '\n\n\n\n\r\r\r' ],