Add QUERY routing; complete exception annotations; render trusted mail component content raw

src/broadcasting/src/BroadcastManager.php

@@ -300,9 +300,10 @@ protected function get(string $name): Broadcaster
     }
 
     /**
-     * Resolve the given broadcaster with Pool Proxy if need.
+     * Resolve the given broadcaster with a pool proxy if needed.
      *
      * @throws InvalidArgumentException
+     * @throws RuntimeException
      */
     protected function resolve(string $name): Broadcaster
     {

src/console/src/Concerns/ConfiguresPrompts.php

@@ -179,6 +179,8 @@ function () use ($prompt): mixed {
      * @param bool|string $required
      * @param null|(Closure(PResult): mixed) $validate
      * @return PResult
+     *
+     * @throws PromptValidationException
      */
     protected function promptUntilValid($prompt, $required, $validate)
     {

src/console/src/Scheduling/ManagesFrequencies.php

@@ -124,6 +124,8 @@ public function everyThirtySeconds(): static
      * Schedule the event to run multiple times per minute.
      *
      * @param int<1, 59> $seconds
+     *
+     * @throws InvalidArgumentException
      */
     protected function repeatEvery(int $seconds): static
     {

src/console/src/Scheduling/Schedule.php

@@ -493,6 +493,8 @@ public static function flushState(): void
 
     /**
      * Dynamically handle calls into the schedule instance.
+     *
+     * @throws BadMethodCallException
      */
     public function __call(string $method, array $parameters): mixed
     {

src/console/src/View/Components/Task.php

@@ -19,6 +19,8 @@ class Task extends Component
      * Render the component using the given arguments.
      *
      * @param null|(callable(): mixed) $task
+     *
+     * @throws Throwable
      */
     public function render(string $description, ?callable $task = null, int $verbosity = OutputInterface::VERBOSITY_NORMAL): void
     {

src/contracts/src/Routing/Registrar.php

@@ -40,6 +40,11 @@ public function patch(string $uri, array|string|callable $action): Route;
      */
     public function options(string $uri, array|string|callable $action): Route;
 
+    /**
+     * Register a new QUERY route with the router.
+     */
+    public function query(string $uri, array|string|callable $action): Route;
+
     /**
      * Register a new route with the given verbs.
      */

src/database/src/Concerns/BuildsQueries.php

@@ -308,6 +308,9 @@ public function lazyByIdDesc(int $chunkSize = 1000, ?string $column = null, ?str
      * Query lazily, by chunking the results of a query by comparing IDs in a given order.
      *
      * @return LazyCollection<int, TValue>
+     *
+     * @throws InvalidArgumentException
+     * @throws RuntimeException if the ID column is missing while iterating the results
      */
     protected function orderedLazyById(int $chunkSize = 1000, ?string $column = null, ?string $alias = null, SortDirection|bool $descending = false): LazyCollection
     {

src/database/src/Concerns/CompilesJsonPaths.php

@@ -30,6 +30,7 @@ protected function wrapJsonPath(string $value, string $delimiter = '->'): string
     {
         $value = preg_replace("/([\\\\]+)?\\'/", "'", $value);
 
+        // Keep this explode() to avoid an extra Stringable allocation per call.
         $jsonPath = (new Collection(explode($delimiter, $value)))
             ->map(fn ($segment) => $this->wrapJsonPathSegment($segment))
             ->join('.');

src/database/src/Console/MonitorCommand.php

@@ -8,6 +8,7 @@
 use Hypervel\Database\ConnectionResolverInterface;
 use Hypervel\Database\Events\DatabaseBusy;
 use Hypervel\Support\Collection;
+use Hypervel\Support\Stringable;
 use Symfony\Component\Console\Attribute\AsCommand;
 
 #[AsCommand(name: 'db:monitor')]
@@ -65,7 +66,7 @@ public function handle(): void
      */
     protected function parseDatabases(?string $databases): Collection
     {
-        return (new Collection(explode(',', $databases ?? '')))->map(function ($database) {
+        return (new Stringable($databases))->explode(',')->map(function ($database) {
             if ($database === '') {
                 $database = $this->hypervel->make('config')->string('database.default');
             }

src/database/src/Eloquent/Casts/AsCollection.php

@@ -22,11 +22,19 @@ class AsCollection implements Castable
     public static function castUsing(array $arguments): CastsAttributes
     {
         return new class($arguments) implements CastsAttributes {
+            /**
+             * Create a new collection cast instance.
+             */
             public function __construct(protected array $arguments)
             {
                 $this->arguments = array_pad(array_values($this->arguments), 2, '');
             }
 
+            /**
+             * Transform the attribute from the underlying model values.
+             *
+             * @throws InvalidArgumentException
+             */
             public function get(Model $model, string $key, mixed $value, array $attributes): ?Collection
             {
                 if (! isset($attributes[$key])) {
@@ -60,6 +68,9 @@ public function get(Model $model, string $key, mixed $value, array $attributes):
                     : $instance->mapInto($this->arguments[1][0]);
             }
 
+            /**
+             * Transform the attribute to its underlying model values.
+             */
             public function set(Model $model, string $key, mixed $value, array $attributes): array
             {
                 $encoded = Json::encode($value);

src/database/src/Eloquent/Casts/AsEncryptedCollection.php

@@ -23,11 +23,19 @@ class AsEncryptedCollection implements Castable
     public static function castUsing(array $arguments): CastsAttributes
     {
         return new class($arguments) implements CastsAttributes {
+            /**
+             * Create a new encrypted collection cast instance.
+             */
             public function __construct(protected array $arguments)
             {
                 $this->arguments = array_pad(array_values($this->arguments), 2, '');
             }
 
+            /**
+             * Transform the attribute from the underlying model values.
+             *
+             * @throws InvalidArgumentException
+             */
             public function get(Model $model, string $key, mixed $value, array $attributes): ?Collection
             {
                 $collectionClass = empty($this->arguments[0]) ? Collection::class : $this->arguments[0];
@@ -61,6 +69,9 @@ public function get(Model $model, string $key, mixed $value, array $attributes):
                     : $instance->mapInto($this->arguments[1][0]);
             }
 
+            /**
+             * Transform the attribute to its underlying model values.
+             */
             public function set(Model $model, string $key, mixed $value, array $attributes): ?array
             {
                 if (! is_null($value)) {

src/database/src/Eloquent/Concerns/HasAttributes.php

@@ -595,6 +595,8 @@ public function isRelation(string $key): bool
 
     /**
      * Handle a lazy loading violation.
+     *
+     * @throws LazyLoadingViolationException
      */
     protected function handleLazyLoadingViolation(string $key): mixed
     {
@@ -773,6 +775,8 @@ protected function flushCastCaches(): void
 
     /**
      * Ensure that the given casts are strings.
+     *
+     * @throws InvalidArgumentException
      */
     protected function ensureCastsAreStringValues(array $casts): array
     {
@@ -1265,6 +1269,8 @@ protected function getEnumCaseFromValue(string $enumClass, string|int $value): m
      * Get the storable value from the given enum.
      *
      * @param UnitEnum $value
+     *
+     * @throws ValueError
      */
     protected function getStorableEnumValue(string $expectedEnum, mixed $value): string|int
     {
@@ -1303,6 +1309,8 @@ protected function getArrayAttributeByKey(string $key): array
 
     /**
      * Cast the given attribute to JSON.
+     *
+     * @throws JsonEncodingException
      */
     protected function castAttributeAsJson(string $key, mixed $value): string
     {
@@ -1390,6 +1398,8 @@ public static function currentEncrypter(): EncrypterContract
 
     /**
      * Cast the given attribute to a hashed string.
+     *
+     * @throws RuntimeException
      */
     protected function castAttributeAsHashedString(string $key, #[SensitiveParameter] mixed $value): ?string
     {
@@ -1429,6 +1439,8 @@ public function fromFloat(mixed $value): float
 
     /**
      * Return a decimal as string.
+     *
+     * @throws MathException
      */
     protected function asDecimal(float|string $value, int $decimals): string
     {

src/database/src/Eloquent/Concerns/QueriesRelationships.php

@@ -692,6 +692,7 @@ protected function getMorphTypeForQuery(string $model): string
      *
      * @param EloquentCollection<int, Model>|Model $related
      *
+     * @throws InvalidArgumentException
      * @throws RelationNotFoundException
      */
     public function whereBelongsTo(mixed $related, ?string $relationshipName = null, string $boolean = 'and'): static
@@ -733,8 +734,6 @@ public function whereBelongsTo(mixed $related, ?string $relationshipName = null,
 
     /**
      * Add a "BelongsTo" relationship with an "or where" clause to the query.
-     *
-     * @throws RuntimeException
      */
     public function orWhereBelongsTo(mixed $related, ?string $relationshipName = null): static
     {
@@ -746,6 +745,7 @@ public function orWhereBelongsTo(mixed $related, ?string $relationshipName = nul
      *
      * @param EloquentCollection<int, Model>|Model $related
      *
+     * @throws InvalidArgumentException
      * @throws RelationNotFoundException
      */
     public function whereAttachedTo(mixed $related, ?string $relationshipName = null, string $boolean = 'and'): static

src/database/src/Eloquent/Concerns/TransformsToResource.php

@@ -31,6 +31,8 @@ public function toResource(?string $resourceClass = null): JsonResource
 
     /**
      * Guess the resource class for the model.
+     *
+     * @throws LogicException
      */
     protected function guessResource(): JsonResource
     {

src/database/src/Eloquent/MassPrunable.php

@@ -47,6 +47,8 @@ public function pruneAll(int $chunkSize = 1000): int
      * Get the prunable model query.
      *
      * @return Builder<static>
+     *
+     * @throws LogicException
      */
     public function prunable(): Builder
     {

src/database/src/Eloquent/Model.php

@@ -367,6 +367,9 @@ public function __construct(array $attributes = [])
 
     /**
      * Check if the model needs to be booted and if so, do it.
+     *
+     * @throws LogicException
+     * @throws RuntimeException
      */
     protected function bootIfNotBooted(): void
     {

src/database/src/Eloquent/PendingHasThroughRelationship.php

@@ -104,6 +104,8 @@ public function has(callable|string $callback): mixed
 
     /**
      * Handle dynamic method calls into the model.
+     *
+     * @throws BadMethodCallException
      */
     public function __call(string $method, array $parameters): mixed
     {

src/database/src/Eloquent/Prunable.php

@@ -8,12 +8,15 @@
 use Hypervel\Contracts\Events\Dispatcher;
 use Hypervel\Database\Events\ModelsPruned;
 use LogicException;
+use Swoole\Coroutine\CanceledException;
 use Throwable;
 
 trait Prunable
 {
     /**
      * Prune all prunable models in the database.
+     *
+     * @throws Throwable
      */
     public function pruneAll(int $chunkSize = 1000): int
     {
@@ -29,14 +32,10 @@ public function pruneAll(int $chunkSize = 1000): int
                         $model->prune();
 
                         ++$total;
+                    } catch (CanceledException $exception) {
+                        throw $exception;
                     } catch (Throwable $e) {
-                        $handler = app(ExceptionHandler::class);
-
-                        if ($handler) {
-                            $handler->report($e);
-                        } else {
-                            throw $e;
-                        }
+                        app(ExceptionHandler::class)->report($e);
                     }
                 });
 
@@ -54,6 +53,8 @@ public function pruneAll(int $chunkSize = 1000): int
      * Get the prunable model query.
      *
      * @return Builder<static>
+     *
+     * @throws LogicException
      */
     public function prunable(): Builder
     {

src/database/src/Grammar.php

@@ -61,6 +61,7 @@ public function wrapTable(Expression|string $table, ?string $prefix = null): str
         if (str_contains($table, '.')) {
             $table = substr_replace($table, '.' . $prefix, strrpos($table, '.'), 1);
 
+            // Keep this explode() to avoid an extra Stringable allocation per call.
             return (new Collection(explode('.', $table)))
                 ->map($this->wrapValue(...))
                 ->implode('.');

src/database/src/Query/Builder.php

@@ -1262,6 +1262,8 @@ public function orWhereNullSafeEquals(ExpressionContract|string $column, mixed $
 
     /**
      * Add a "where in" clause to the query.
+     *
+     * @throws InvalidArgumentException
      */
     public function whereIn(ExpressionContract|string $column, mixed $values, string $boolean = 'and', bool $not = false): static
     {
@@ -3877,6 +3879,8 @@ public function update(array $values): int
 
     /**
      * Update records in a PostgreSQL database using the update from syntax.
+     *
+     * @throws LogicException
      */
     public function updateFrom(array $values): int
     {
@@ -4292,6 +4296,8 @@ public function getConnection(): ConnectionInterface
 
     /**
      * Ensure the database connection supports vector queries.
+     *
+     * @throws RuntimeException
      */
     protected function ensureConnectionSupportsVectors(): void
     {

src/database/src/Query/Grammars/Grammar.php

@@ -314,6 +314,8 @@ protected function whereBitwise(Builder $query, array $where): string
 
     /**
      * Compile a "where like" clause.
+     *
+     * @throws RuntimeException
      */
     protected function whereLike(Builder $query, array $where): string
     {
@@ -695,6 +697,8 @@ public function compileJsonValueCast(string $value): string
 
     /**
      * Compile a "where fulltext" clause.
+     *
+     * @throws RuntimeException
      */
     public function whereFullText(Builder $query, array $where): string
     {

src/database/src/Schema/Builder.php

@@ -325,6 +325,8 @@ public function whenTableDoesntHaveIndex(string $table, array|string $index, Clo
 
     /**
      * Get the data type for the given column name.
+     *
+     * @throws InvalidArgumentException
      */
     public function getColumnType(string $table, string $column, bool $fullDefinition = false): string
     {
@@ -691,6 +693,8 @@ public function ensureVectorExtensionExists(?string $schema = null): void
 
     /**
      * Create a new extension on the schema if it does not exist.
+     *
+     * @throws RuntimeException
      */
     public function ensureExtensionExists(string $name, ?string $schema = null): void
     {