[feature/validation-wrapping] Add ValidationExceptionBuilder class wi…

…th tests and documentation

Introduces `ValidationExceptionBuilder` for streamlined validation exception handling in Laravel. The update includes comprehensive documentation and unit tests to ensure robustness and ease of use.

docs/Validation/ValidationExceptionBuilder.md

@@ -0,0 +1,146 @@
+# ValidationExceptionBuilder
+
+`ValidationExceptionBuilder` is a fluent interface for building and throwing validation exceptions in Laravel
+applications. It provides a convenient way to create custom validation exceptions with redirects, error messages, and
+additional parameters.
+
+## Basic Usage
+
+Here's a quick example of how to use the `ValidationExceptionBuilder`:
+
+```php
+use Midnite81\Core\Validation\ValidationExceptionBuilder;
+
+ValidationExceptionBuilder::message('Invalid input')
+    ->redirectTo('/form')
+    ->flash('Please correct the errors and try again.')
+    ->throwException();
+```
+
+This will throw a `ValidationException` with the message "Invalid input", redirect the user to '/form', and flash a
+message to the session.
+
+## API Reference
+
+### Static Methods
+
+#### `message(string $message): self`
+
+Create a new ValidationExceptionBuilder instance with the specified error message.
+
+### Instance Methods
+
+#### `redirectTo(string $url): self`
+
+Set the URL to redirect to after validation failure.
+
+#### `redirectBack(): self`
+
+Set the redirect to go back to the previous URL.
+
+#### `redirectRoute(string $name, array $parameters = []): self`
+
+Set a named route to redirect to after validation failure.
+
+#### `fragment(string $fragment): self`
+
+Set the URL fragment (hash) to append to the redirect URL.
+
+#### `withQueryParameters(array $params): self`
+
+Set query parameters to append to the redirect URL.
+
+#### `errorBag(string $errorBag): self`
+
+Set the error bag name for the validation exception.
+
+#### `flash(?string $message = null, string $key = 'error'): self`
+
+Enable session flashing with an optional custom message and key.
+
+#### `withException(string $exceptionClass): self`
+
+Set the exception class to be thrown.
+
+#### `withExceptionCallback(callable $callback): self`
+
+Set a callback for creating the exception.
+
+#### `throwException(): void`
+
+Throw the configured exception.
+
+#### `throwExceptionIf($condition): void`
+
+Throw the configured exception if the given condition is true.
+
+#### `throwExceptionUnless($condition): void`
+
+Throw the configured exception unless the given condition is true.
+
+## Examples
+
+### Basic Validation Exception
+
+```php
+ValidationExceptionBuilder::message('The email is invalid')
+    ->redirectBack()
+    ->throwException();
+```
+
+### Custom Redirect with Query Parameters
+
+```php
+ValidationExceptionBuilder::message('Invalid input')
+    ->redirectTo('/users')
+    ->withQueryParameters(['sort' => 'name', 'order' => 'asc'])
+    ->throwException();
+```
+
+### Using Named Routes
+
+```php
+ValidationExceptionBuilder::message('Access denied')
+    ->redirectRoute('dashboard', ['user' => $userId])
+    ->throwException();
+```
+
+### Flashing Messages
+
+```php
+ValidationExceptionBuilder::message('Form submission failed')
+    ->redirectBack()
+    ->flash('Please correct the errors and try again.', 'warning')
+    ->throwException();
+```
+
+### Conditional Exception Throwing
+
+```php
+$someCondition = true;
+
+ValidationExceptionBuilder::message('Conditional error')
+    ->redirectBack()
+    ->throwExceptionIf($someCondition);
+```
+
+### Custom Exception Class
+
+```php
+class MyCustomException extends Exception {}
+
+ValidationExceptionBuilder::message('Something went wrong')
+    ->withException(MyCustomException::class)
+    ->throwException();
+```
+
+### Using Exception Callback
+
+```php
+ValidationExceptionBuilder::message('Custom handling required')
+    ->withExceptionCallback(function ($message, $url, $errorBag) {
+        // Custom logic here
+        return new MyCustomException($message);
+    })
+    ->throwException();
+```