Better exceptions

src/Context.php

@@ -2,7 +2,8 @@
 
 namespace Sparors\Ussd;
 
-use InvalidArgumentException;
+use Sparors\Ussd\Exceptions\GlobaldentifierEmptyException;
+use Sparors\Ussd\Exceptions\UniqueIdentifierEmptyException;
 
 class Context
 {
@@ -14,11 +15,11 @@ public function __construct(
         private string $input
     ) {
         if (0 === strlen($uid)) {
-            throw new InvalidArgumentException("Unique Identifier (uid) can not be empty");
+            throw new UniqueIdentifierEmptyException();
         }
 
         if (0 === strlen($gid)) {
-            throw new InvalidArgumentException("Global Identifier (gid) can not be empty");
+            throw new GlobaldentifierEmptyException();
         }
 
         $this->bag = [];

src/Exceptions/ActiveStateNotFoundException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+class ActiveStateNotFoundException extends UssdException
+{
+    public function __construct()
+    {
+        parent::__construct('Active state not found. This may indicate session has ended');
+    }
+}

src/Exceptions/GlobaldentifierEmptyException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+class GlobaldentifierEmptyException extends UssdException
+{
+    public function __construct()
+    {
+        parent::__construct("Global identifier (gid) can not be empty");
+    }
+}

src/Exceptions/InvalidConfiguratorException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+use Sparors\Ussd\Contracts\Configurator;
+
+class InvalidConfiguratorException extends UssdException
+{
+    public function __construct(string $configurator)
+    {
+        parent::__construct("Invalid configurator, {$configurator} should implement ". Configurator::class);
+    }
+}

src/Exceptions/InvalidContinueStateException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+use Sparors\Ussd\Contracts\ContinueState;
+
+class InvalidContinueStateException extends UssdException
+{
+    public function __construct(?string $state)
+    {
+        $message = $state
+            ? "Invalid continue state, {$state} should implement ". ContinueState::class
+            : "Invalid continue state, should not be null and must implement ". ContinueState::class;
+
+        parent::__construct($message);
+    }
+}

src/Exceptions/InvalidContinuingModeException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+use Sparors\Ussd\ContinuingMode;
+
+class InvalidContinuingModeException extends UssdException
+{
+    public function __construct(int $continuingMode)
+    {
+        $start = ContinuingMode::START;
+        $continue = ContinuingMode::CONTINUE;
+        $confirm = ContinuingMode::CONFIRM;
+
+        parent::__construct("Invalid continuingMode, {$continuingMode} should be one of {$start}, {$continue} or {$confirm}. use constants from ".ContinuingMode::class);
+    }
+}

src/Exceptions/InvalidExceptionHandlerException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+use Sparors\Ussd\Contracts\ExceptionHandler;
+
+class InvalidExceptionHandlerException extends UssdException
+{
+    public function __construct(string $exceptionHandler)
+    {
+        parent::__construct("Invalid exception handler, {$exceptionHandler} should implement ".ExceptionHandler::class." or be a closure");
+    }
+}

src/Exceptions/InvalidInitialStateException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+use Sparors\Ussd\Contracts\InitialAction;
+use Sparors\Ussd\Contracts\InitialState;
+
+class InvalidInitialStateException extends UssdException
+{
+    public function __construct(string $state)
+    {
+        parent::__construct("Invalid initial state, {$state} should implement ".InitialState::class." or ".InitialAction::class);
+    }
+}

src/Exceptions/InvalidResponseException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+use Sparors\Ussd\Contracts\Response;
+
+class InvalidResponseException extends UssdException
+{
+    public function __construct(string $response)
+    {
+        parent::__construct("Invalid response, {$response} should implement ".Response::class." or be a closure");
+    }
+}

src/Exceptions/InvalidStateException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+use Sparors\Ussd\Contracts\State;
+
+class InvalidStateException extends UssdException
+{
+    public function __construct(string $state)
+    {
+        parent::__construct("Invalid state, {$state} should implement ".State::class);
+    }
+}

src/Exceptions/NextStateNotFoundException.php

@@ -2,15 +2,10 @@
 
 namespace Sparors\Ussd\Exceptions;
 
-use Exception;
-use Sparors\Ussd\Contracts\State;
-
-class NextStateNotFoundException extends Exception
+class NextStateNotFoundException extends UssdException
 {
-    public function __construct(State $state)
+    public function __construct(string $state)
     {
-        $class = $state::class;
-
-        parent::__construct("No state found after {$class} with the given input");
+        parent::__construct("Next state not found after {$state}. This may indicate unhandled transition");
     }
 }

src/Exceptions/NoInitialStateProvided.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+class NoInitialStateProvided extends UssdException
+{
+    public function __construct()
+    {
+        parent::__construct('No initial state provided');
+    }
+}

src/Exceptions/UniqueIdentifierEmptyException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Sparors\Ussd\Exceptions;
+
+class UniqueIdentifierEmptyException extends UssdException
+{
+    public function __construct()
+    {
+        parent::__construct("Unique identifier (uid) can not be empty");
+    }
+}

src/Ussd.php

@@ -8,7 +8,6 @@
 use Exception;
 use Illuminate\Support\Facades\App;
 use Illuminate\Support\Str;
-use InvalidArgumentException;
 use ReflectionClass;
 use Sparors\Ussd\Attributes\Paginate;
 use Sparors\Ussd\Attributes\Terminate;
@@ -22,7 +21,16 @@
 use Sparors\Ussd\Contracts\InitialState;
 use Sparors\Ussd\Contracts\Response;
 use Sparors\Ussd\Contracts\State;
+use Sparors\Ussd\Exceptions\ActiveStateNotFoundException;
+use Sparors\Ussd\Exceptions\InvalidConfiguratorException;
+use Sparors\Ussd\Exceptions\InvalidContinueStateException;
+use Sparors\Ussd\Exceptions\InvalidContinuingModeException;
+use Sparors\Ussd\Exceptions\InvalidExceptionHandlerException;
+use Sparors\Ussd\Exceptions\InvalidInitialStateException;
+use Sparors\Ussd\Exceptions\InvalidResponseException;
+use Sparors\Ussd\Exceptions\InvalidStateException;
 use Sparors\Ussd\Exceptions\NextStateNotFoundException;
+use Sparors\Ussd\Exceptions\NoInitialStateProvided;
 use Sparors\Ussd\Tests\PendingTest;
 use Sparors\Ussd\Traits\Conditionable;
 use Sparors\Ussd\Traits\WithPagination;
@@ -94,8 +102,8 @@ public function useConfigurator(Configurator|string $configurator): static
 
         throw_unless(
             $configurator instanceof Configurator,
-            InvalidArgumentException::class,
-            "Configurator should implement ".Configurator::class
+            InvalidConfiguratorException::class,
+            $configurator::class
         );
 
         $configurator->configure($this);
@@ -111,8 +119,8 @@ public function useInitialState(InitialAction|InitialState|string $initialState)
 
         throw_unless(
             $initialState instanceof InitialState || $initialState instanceof InitialAction,
-            InvalidArgumentException::class,
-            "Initial state should implement ".InitialState::class." or ".InitialAction::class
+            InvalidInitialStateException::class,
+            $initialState::class
         );
 
         $this->initialState = $initialState;
@@ -131,8 +139,8 @@ public function useContinuingState(
 
         throw_unless(
             in_array($continuingMode, [ContinuingMode::START, ContinuingMode::CONTINUE, ContinuingMode::CONFIRM], true),
-            InvalidArgumentException::class,
-            "Invalid continuingMode"
+            InvalidContinuingModeException::class,
+            $continuingMode
         );
 
         $this->continuingMode = $continuingMode;
@@ -141,8 +149,8 @@ public function useContinuingState(
         if (ContinuingMode::CONFIRM === $continuingMode) {
             throw_unless(
                 $continuingState instanceof ContinueState,
-                InvalidArgumentException::class,
-                "Continuing state should implement ".ContinueState::class
+                InvalidContinueStateException::class,
+                isset($continuingState) ? $continuingState::class : null
             );
         }
 
@@ -159,8 +167,8 @@ public function useResponse(Closure|Response|string $response): static
 
         throw_unless(
             $response instanceof Response || $response instanceof Closure,
-            InvalidArgumentException::class,
-            "Response should implement ".Response::class." or be a closure"
+            InvalidResponseException::class,
+            $response::class
         );
 
         $this->response = $response;
@@ -176,8 +184,8 @@ public function useExceptionHandler(Closure|ExceptionHandler|string $exceptionHa
 
         throw_unless(
             $exceptionHandler instanceof ExceptionHandler || $exceptionHandler instanceof Closure,
-            InvalidArgumentException::class,
-            "Exception handler should implement ".ExceptionHandler::class." or be a closure"
+            InvalidExceptionHandlerException::class,
+            $exceptionHandler::class
         );
 
         $this->exceptionHandler = $exceptionHandler;
@@ -226,7 +234,8 @@ private function operate(): array
         } elseif (ContinuingMode::CONFIRM === $this->continuingMode && $record->has(static::HALT) && $spur = $record->get(static::SPUR, public: true)) {
             throw_unless(
                 $this->continuingState instanceof ContinueState,
-                $this->continuingState::class.' does not implement '.ContinueState::class
+                InvalidContinueStateException::class,
+                isset($this->continuingState) ? $this->continuingState::class : null
             );
 
             $record->forget(static::HALT);
@@ -248,7 +257,7 @@ private function operate(): array
 
             throw_unless(
                 $nextState,
-                'No active state found. This may indicate session has ended'
+                ActiveStateNotFoundException::class
             );
 
             $nextState = App::make($nextState);
@@ -265,7 +274,7 @@ private function operate(): array
         } else {
             throw_unless(
                 isset($this->initialState),
-                'Initial state should be provided'
+                NoInitialStateProvided::class
             );
 
             $nextState = $this->initialState::class;
@@ -417,7 +426,7 @@ private function next(State $state): string
             }
         }
 
-        throw new NextStateNotFoundException($state);
+        throw new NextStateNotFoundException($state::class);
     }
 
     private function actionable(string $class): string
@@ -432,7 +441,8 @@ private function actionable(string $class): string
 
         throw_unless(
             $instance instanceof State,
-            $instance::class.' does not implement '.State::class
+            InvalidStateException::class,
+            $instance::class
         );
 
         return $instance::class;