Adds custom exceptions for invalid direction and filter operators and…

… never returns null anymore

README.md

@@ -147,8 +147,10 @@ FilterClause {
   - If the `$count` query string value is not a boolean
   - If the formatting of `$orderby` is not valid (should be a property, space and the direction)
   - If the direction of the `$orderby` query string value is neither `asc` or `desc` (case-insensitive)
+    - This will throw an InvalidDirectionException, inheriting InvalidArgumentException.
   - If the formatting of `$filter` is not valid (should be a property, space, operator, space and value)
   - If the operator of the `$filter` query string value is not `eq`, `ne`, `gt`, `ge`, `lt`, `le` or `in` (case-insensitive)
+    - This will throw an InvalidFilterOperatorException, inheriting InvalidArgumentException.
 - `LogicException`
   - If an unforeseen edge case is triggered by an input value. For example when a regex operation fails. Should never be thrown under normal operation.
     - If an edge case is found, please report them as an issue. Currently, I cannot write test cases for them as I don't know how to trigger them.

src/Exceptions/InvalidDirectionException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace GlobyApp\OdataQueryParser\Exceptions;
+
+class InvalidDirectionException extends \InvalidArgumentException
+{
+    public function __construct(string $message)
+    {
+        parent::__construct($message);
+    }
+}

src/Exceptions/InvalidFilterOperatorException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace GlobyApp\OdataQueryParser\Exceptions;
+
+class InvalidFilterOperatorException extends \InvalidArgumentException
+{
+    public function __construct(string $message)
+    {
+        parent::__construct($message);
+    }
+}

src/OdataQueryParser.php

@@ -8,6 +8,8 @@
 use GlobyApp\OdataQueryParser\Datatype\OrderByClause;
 use GlobyApp\OdataQueryParser\Enum\FilterOperator;
 use GlobyApp\OdataQueryParser\Enum\OrderDirection;
+use GlobyApp\OdataQueryParser\Exceptions\InvalidDirectionException;
+use GlobyApp\OdataQueryParser\Exceptions\InvalidFilterOperatorException;
 use InvalidArgumentException;
 use LogicException;
 
@@ -37,10 +39,10 @@ class OdataQueryParser
      * @param string $url The URL to parse the query strings from. It should be a "complete" or "full" URL
      * @param bool $withDollar When set to false, parses the odata keys without requiring the $ in front of odata keys
      *
-     * @return OdataQuery|null OdataQuery object, parsed version of the input url, or null, if there is no query string
+     * @return OdataQuery OdataQuery object, parsed version of the input url
      * @throws InvalidArgumentException The URL, or parts of it are malformed and could not be processed
      */
-    public static function parse(string $url, bool $withDollar = true): ?OdataQuery
+    public static function parse(string $url, bool $withDollar = true): OdataQuery
     {
         // Verify the URL is valid
         if (filter_var($url, FILTER_VALIDATE_URL) === false) {
@@ -51,7 +53,7 @@ public static function parse(string $url, bool $withDollar = true): ?OdataQuery
         $queryString = self::extractQueryString($url);
         if ($queryString === null) {
             // There is no query string, so there cannot be a result
-            return null;
+            return new OdataQuery();
         }
 
         $parsedQueryString = self::parseQueryString($queryString);
@@ -285,7 +287,7 @@ private static function getSkip(array $queryString): ?int
      * @param array<string, string> $queryString The query string to get the order by clauses from
      *
      * @return OrderByClause[] The parsed order by clauses
-     * @throws InvalidArgumentException If the direction is not asc or desc, or the clause split found a clause that was incorrectly formed
+     * @throws InvalidFilterOperatorException If the direction is not asc or desc, or the clause split found a clause that was incorrectly formed
      */
     private static function getOrderBy(array $queryString): array
     {
@@ -322,14 +324,14 @@ private static function getOrderBy(array $queryString): array
      * @param string $direction The string representation of the order direction
      *
      * @return OrderDirection The parsed order direction
-     * @throws InvalidArgumentException If the direction is not asc or desc
+     * @throws InvalidDirectionException If the direction is not asc or desc
      */
     private static function parseDirection(string $direction): OrderDirection
     {
         return match (strtolower($direction)) {
             "asc" => OrderDirection::ASC,
             "desc" => OrderDirection::DESC,
-            default => throw new InvalidArgumentException("Direction should be either asc or desc"),
+            default => throw new InvalidDirectionException("Direction should be either asc or desc"),
         };
     }
 
@@ -339,7 +341,7 @@ private static function parseDirection(string $direction): OrderDirection
      * @param array<string, string> $queryString The query string to find the filter key in
      *
      * @return FilterClause[] The parsed list of filter clauses
-     * @throws InvalidArgumentException If an invalid operator is found, or the clause split found a clause that was incorrectly formed
+     * @throws InvalidFilterOperatorException If an invalid operator is found, or the clause split found a clause that was incorrectly formed
      */
     private static function getFilter(array $queryString): array
     {
@@ -377,7 +379,7 @@ private static function getFilter(array $queryString): array
      * @param string $operator The string representation of the filter operator
      *
      * @return FilterOperator The parsed filter operator
-     * @throws InvalidArgumentException If the filter operator is not valid
+     * @throws InvalidFilterOperatorException If the filter operator is not valid
      */
     private static function parseFilterOperator(string $operator): FilterOperator
     {
@@ -389,7 +391,7 @@ private static function parseFilterOperator(string $operator): FilterOperator
             "lt" => FilterOperator::LESS_THAN,
             "le" => FilterOperator::LESS_THAN_EQUALS,
             "in" => FilterOperator::IN,
-            default => throw new InvalidArgumentException("Filter operator should be eq, ne, gt, ge, lt, le or in."),
+            default => throw new InvalidFilterOperatorException("Filter operator should be eq, ne, gt, ge, lt, le or in."),
         };
     }
 

tests/ParseTest.php

@@ -21,7 +21,7 @@ public function testShouldReturnExceptionIfUrlIsNotValid(): void {
 	}
 
 	public function testShouldReturnAnEmptyArrayIfNoQueryParameters(): void {
-		$expected = null;
+		$expected = new OdataQueryParser\OdataQuery();
 		$actual = OdataQueryParser\OdataQueryParser::parse("https://example.com");
 
 		$this->assertEquals($expected, $actual);