Add pivot chaperones and update query iteration, exception helpers and queue workers

src/database/src/Concerns/BuildsQueries.php

@@ -45,10 +45,12 @@ public function chunk(int $count, callable $callback): bool
             throw new InvalidArgumentException('The chunk size should be at least 1');
         }
 
-        $this->enforceOrderBy();
+        $clone = clone $this;
 
-        $skip = $this->getOffset();
-        $remaining = $this->getLimit();
+        $clone->enforceOrderBy();
+
+        $skip = $clone->getOffset();
+        $remaining = $clone->getLimit();
 
         $page = 1;
 
@@ -61,7 +63,7 @@ public function chunk(int $count, callable $callback): bool
                 break;
             }
 
-            $results = $this->offset($offset)->limit($limit)->get();
+            $results = $clone->offset($offset)->limit($limit)->get();
 
             $countResults = $results->count();
 
@@ -246,12 +248,14 @@ public function lazy(int $chunkSize = 1000): LazyCollection
             throw new InvalidArgumentException('The chunk size should be at least 1');
         }
 
-        $this->enforceOrderBy();
-
         $skip = $this->getOffset();
         $remaining = $this->getLimit();
 
         return new LazyCollection(function () use ($chunkSize, $skip, $remaining): Generator {
+            $clone = clone $this;
+
+            $clone->enforceOrderBy();
+
             $page = 1;
 
             while (true) {
@@ -263,7 +267,7 @@ public function lazy(int $chunkSize = 1000): LazyCollection
                     return;
                 }
 
-                $results = $this->offset($offset)->limit($limit)->get();
+                $results = $clone->offset($offset)->limit($limit)->get();
 
                 foreach ($results as $result) {
                     yield $result;

src/database/src/Eloquent/Relations/BelongsToMany.php

@@ -16,6 +16,7 @@
 use Hypervel\Database\Eloquent\Relations\Concerns\AsPivot;
 use Hypervel\Database\Eloquent\Relations\Concerns\InteractsWithDictionary;
 use Hypervel\Database\Eloquent\Relations\Concerns\InteractsWithPivotTable;
+use Hypervel\Database\Eloquent\Relations\Concerns\SupportsPivotInverseRelations;
 use Hypervel\Database\MultipleRecordsFoundException;
 use Hypervel\Database\Query\Builder as QueryBuilder;
 use Hypervel\Database\Query\Grammars\MySqlGrammar;
@@ -44,6 +45,7 @@ class BelongsToMany extends Relation
 {
     use InteractsWithDictionary;
     use InteractsWithPivotTable;
+    use SupportsPivotInverseRelations;
 
     /**
      * The intermediate table for the relation.
@@ -256,9 +258,21 @@ public function match(array $models, EloquentCollection $results, string $relati
             $key = $this->getDictionaryKey($model->{$this->parentKey});
 
             if ($key !== null && isset($dictionary[$key])) {
+                $items = $dictionary[$key];
+
+                // Correct $this->parent to the actual parent for each group of results...
+                if ($this->declaringInverseRelationship) {
+                    foreach ($items as $item) {
+                        $item->{$this->accessor}?->setRelation(
+                            $this->declaringInverseRelationship,
+                            $model
+                        );
+                    }
+                }
+
                 $model->setRelation(
                     $relation,
-                    $this->related->newCollection($dictionary[$key])
+                    $this->related->newCollection($items)
                 );
             }
         }
@@ -1202,9 +1216,11 @@ protected function hydratePivotRelation(array $models): void
         // and create a new Pivot model, which is basically a dynamic model that we
         // will set the attributes, table, and connections on it so it will work.
         foreach ($models as $model) {
-            $model->setRelation($this->accessor, $this->newExistingPivot(
-                $this->migratePivotAttributes($model)
-            ));
+            $pivot = $this->newExistingPivot($this->migratePivotAttributes($model));
+
+            $this->applyChaperonesToPivot($pivot, $this->parent, $model);
+
+            $model->setRelation($this->accessor, $pivot);
         }
     }
 

src/database/src/Eloquent/Relations/Concerns/SupportsPivotInverseRelations.php

@@ -0,0 +1,140 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Database\Eloquent\Relations\Concerns;
+
+use Hypervel\Database\Eloquent\Model;
+use Hypervel\Database\Eloquent\RelationNotFoundException;
+use Hypervel\Support\Arr;
+use Hypervel\Support\Str;
+
+trait SupportsPivotInverseRelations
+{
+    /**
+     * The name of the declaring model's relationship on the pivot.
+     */
+    protected ?string $declaringInverseRelationship = null;
+
+    /**
+     * The name of the related model's relationship on the pivot.
+     */
+    protected ?string $relatedInverseRelationship = null;
+
+    /**
+     * Instruct Eloquent to link the declaring and related models back to the pivot after the relationship query has run.
+     *
+     * @return $this
+     */
+    public function chaperone(?string $declaring = null, ?string $related = null): static
+    {
+        if (! $this->using) {
+            return $this;
+        }
+
+        $pivotModel = new $this->using;
+
+        $this->declaringInverseRelationship = $this->resolvePivotInverseRelation(
+            $pivotModel,
+            $declaring,
+            $this->foreignPivotKey,
+            $this->parent
+        );
+
+        $this->relatedInverseRelationship = $this->resolvePivotInverseRelation(
+            $pivotModel,
+            $related,
+            $this->relatedPivotKey,
+            $this->related
+        );
+
+        // Both sides can guess the same model name, so keep it only on a side named
+        // explicitly or identified by its pivot key.
+        if ($this->declaringInverseRelationship !== null
+            && $this->declaringInverseRelationship === $this->relatedInverseRelationship) {
+            $relation = $this->declaringInverseRelationship;
+
+            if ($declaring === null && ($related !== null || $this->relationNameFromPivotKey($this->foreignPivotKey, $this->parent) !== $relation)) {
+                $this->declaringInverseRelationship = null;
+            }
+
+            if ($related === null && ($declaring !== null || $this->relationNameFromPivotKey($this->relatedPivotKey, $this->related) !== $relation)) {
+                $this->relatedInverseRelationship = null;
+            }
+        }
+
+        return $this;
+    }
+
+    /**
+     * Remove the chaperone relationships for this query.
+     *
+     * @return $this
+     */
+    public function withoutChaperone(): static
+    {
+        $this->declaringInverseRelationship = null;
+        $this->relatedInverseRelationship = null;
+
+        return $this;
+    }
+
+    /**
+     * Resolve the inverse relation name on the pivot for a given model.
+     *
+     * If an explicit name is provided and invalid, an exception is thrown.
+     * If guessing fails, null is returned.
+     *
+     * @throws RelationNotFoundException
+     */
+    protected function resolvePivotInverseRelation(Model $pivotModel, ?string $relation, string $foreignKey, Model $model): ?string
+    {
+        if ($relation !== null) {
+            if (! $pivotModel->isRelation($relation)) {
+                throw RelationNotFoundException::make($pivotModel, $relation);
+            }
+
+            return $relation;
+        }
+
+        return $this->guessPivotInverseRelation($pivotModel, $foreignKey, $model);
+    }
+
+    /**
+     * Attempt to guess the inverse relation name on the pivot for a given model.
+     */
+    protected function guessPivotInverseRelation(Model $pivotModel, string $foreignKey, Model $model): ?string
+    {
+        $candidates = array_filter(array_unique([
+            $this->relationNameFromPivotKey($foreignKey, $model),
+            Str::camel(class_basename($model)),
+        ]));
+
+        return Arr::first(
+            $candidates,
+            fn (string $relation): bool => $pivotModel->isRelation($relation)
+        );
+    }
+
+    /**
+     * Derive the inverse relationship name from a pivot key.
+     */
+    protected function relationNameFromPivotKey(string $pivotKey, Model $model): string
+    {
+        return Str::camel(Str::beforeLast($pivotKey, $model->getKeyName()));
+    }
+
+    /**
+     * Apply chaperone relationships to a pivot model instance.
+     */
+    protected function applyChaperonesToPivot(Model $pivot, Model $declaring, Model $related): void
+    {
+        if ($this->declaringInverseRelationship) {
+            $pivot->setRelation($this->declaringInverseRelationship, $declaring);
+        }
+
+        if ($this->relatedInverseRelationship) {
+            $pivot->setRelation($this->relatedInverseRelationship, $related);
+        }
+    }
+}

src/docs/eloquent-relationships.md

@@ -14,6 +14,7 @@
     - [Filtering Queries via Intermediate Table Columns](#filtering-queries-via-intermediate-table-columns)
     - [Ordering Queries via Intermediate Table Columns](#ordering-queries-via-intermediate-table-columns)
     - [Defining Custom Intermediate Table Models](#defining-custom-intermediate-table-models)
+        - [Automatically Hydrating Pivot Relationships](#automatically-hydrating-pivot-relationships)
 - [Polymorphic Relationships](#polymorphic-relationships)
     - [One to One](#one-to-one-polymorphic-relations)
     - [One to Many](#one-to-many-polymorphic-relations)
@@ -1035,6 +1036,49 @@ class RoleUser extends Pivot
 }
 ```
 
+<a name="automatically-hydrating-pivot-relationships"></a>
+#### Automatically Hydrating Pivot Relationships
+
+When a custom pivot model defines `belongsTo` relationships for the declaring and related models, you may invoke `chaperone` after `using` to automatically hydrate those relationships on each pivot model. This avoids additional queries when accessing the models through the pivot:
+
+```php
+use Hypervel\Database\Eloquent\Model;
+use Hypervel\Database\Eloquent\Relations\BelongsTo;
+use Hypervel\Database\Eloquent\Relations\BelongsToMany;
+use Hypervel\Database\Eloquent\Relations\Pivot;
+
+class RoleUser extends Pivot
+{
+    public function role(): BelongsTo
+    {
+        return $this->belongsTo(Role::class);
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+}
+
+class Role extends Model
+{
+    public function users(): BelongsToMany
+    {
+        return $this->belongsToMany(User::class)
+            ->using(RoleUser::class)
+            ->chaperone();
+    }
+}
+```
+
+Eloquent infers the relationship names from the pivot keys and model names. You may also pass the declaring and related relationship names to `chaperone` explicitly:
+
+```php
+return $this->belongsToMany(User::class)
+    ->using(RoleUser::class)
+    ->chaperone(declaring: 'role', related: 'user');
+```
+
 <a name="polymorphic-relationships"></a>
 ## Polymorphic Relationships
 

src/docs/errors.md

@@ -109,6 +109,8 @@ class InvalidOrderException extends Exception
 }
 ```
 
+You may use `Exceptions::contextForException($exception)` to get an exception's complete log context without reporting it. The returned array includes global context, the exception's context, and the exception itself.
+
 <a name="the-report-helper"></a>
 #### The `report` Helper
 

src/docs/queues.md

@@ -3047,7 +3047,7 @@ The `pause`, `pauseFor`, and `resume` methods also accept enums for queue and co
 
 Queue workers report paused and resumed queues in their console output.
 
-Pausing or resuming a queue dispatches the `Hypervel\Queue\Events\QueuePaused` or `Hypervel\Queue\Events\QueueResumed` event in the process that made the change. Their `connection` and `queue` properties identify the queue, and the `QueuePaused` event's `ttl` property is `null` unless the queue was paused for a limited time. Pausing or resuming every queue with the `--all` option dispatches the `QueuesPaused` or `QueuesResumed` event instead. Running workers dispatch the `WorkerQueuePaused` and `WorkerQueueResumed` events, with `connectionName` and `queue` properties, when they detect that one of their queues has been paused or resumed.
+Pausing or resuming a queue dispatches the `Hypervel\Queue\Events\QueuePaused` or `Hypervel\Queue\Events\QueueResumed` event in the process that made the change. Their `connectionName` and `queue` properties identify the queue, and the `QueuePaused` event's `ttl` property is `null` unless the queue was paused for a limited time. Pausing or resuming every queue with the `--all` option dispatches the `QueuesPaused` or `QueuesResumed` event instead. Running workers dispatch the `WorkerQueuePaused` and `WorkerQueueResumed` events, with `connectionName` and `queue` properties, when they detect that one of their queues has been paused or resumed.
 
 A worker process may also be paused as a whole by sending it the `SIGUSR2` signal and resumed with `SIGCONT`. The worker dispatches the `WorkerPausing` and `WorkerResuming` events when it receives these signals. Both events provide the worker's `connectionName`, `queue`, and `workerOptions`.
 
@@ -4038,3 +4038,5 @@ Event::listen(function (WorkerIdle $event) {
 When an interrupting signal is delivered to running jobs, Hypervel dispatches a `Hypervel\Queue\Events\JobInterrupted` event once for each job that was notified. Its `connectionName`, `job`, and `signal` properties identify the interrupted work.
 
 Queue workers also dispatch a `WorkerStopping` event before they stop. You may register a listener using `Queue::stopping` in the `boot` method of a service provider. Its `connectionName` and `queue` properties identify the worker, while `terminatesImmediately` is `true` when the process will be terminated as soon as the listeners return. In that case, listeners should not start cleanup that must finish after the listener returns.
+
+When a job times out, the worker normally ends its own process with `SIGKILL`, so a process supervisor sees the signal rather than an exit status. If you need to control how the worker terminates, you may register a callback using `Hypervel\Queue\Worker::killUsing` in a service provider's `boot` method. The callback receives the worker's exit status after the `WorkerStopping` event is dispatched. If the callback returns, the worker is terminated as usual.

src/foundation/src/Exceptions/Handler.php

@@ -713,6 +713,14 @@ public function stopIgnoring(array|string $exceptions): static
         return $this;
     }
 
+    /**
+     * Create the context array for logging the given exception.
+     */
+    public function contextForException(Throwable $e): array
+    {
+        return $this->buildExceptionContext($e);
+    }
+
     /**
      * Create the context array for logging the given exception.
      *

src/foundation/src/Exceptions/Renderer/Mappers/BladeMapper.php

@@ -84,7 +84,7 @@ public function map(FlattenException $exception): FlattenException
     /**
      * Find the compiled view file for the given compiled path.
      */
-    protected function findCompiledView(string $compiledPath): ?string
+    public function findCompiledView(string $compiledPath): ?string
     {
         return once(fn () => $this->getKnownPaths())[$compiledPath] ?? null;
     }
@@ -135,7 +135,7 @@ protected function filterViewData(array $data): array
     /**
      * Detect the line number in the original blade file.
      */
-    protected function detectLineNumber(string $filename, int $compiledLineNumber): int
+    public function detectLineNumber(string $filename, int $compiledLineNumber): int
     {
         $source = @file_get_contents($filename);
 

src/queue/src/Events/QueuePaused.php

@@ -13,7 +13,7 @@ class QueuePaused
      * Create a new event instance.
      */
     public function __construct(
-        public string $connection,
+        public string $connectionName,
         public string $queue,
         public DateInterval|DateTimeInterface|int|null $ttl = null,
     ) {

src/queue/src/Events/QueueResumed.php

@@ -10,7 +10,7 @@ class QueueResumed
      * Create a new event instance.
      */
     public function __construct(
-        public string $connection,
+        public string $connectionName,
         public string $queue,
     ) {
     }

src/queue/src/Events/WorkerStopping.php

@@ -13,17 +13,17 @@ class WorkerStopping
      * Create a new event instance.
      *
      * @param null|float|int $memoryUsage the memory usage of the worker in megabytes
-     * @param bool $terminatesImmediately whether the process terminates as soon as listeners return; listeners must not start cleanup that must finish before returning when this is true
+     * @param bool $terminatesImmediately whether the process terminates as soon as listeners return; when true, listeners must not start cleanup that must finish after they return
      */
     public function __construct(
+        public ?string $connectionName = null,
+        public ?string $queue = null,
         public int $status = 0,
         public ?WorkerOptions $workerOptions = null,
         public ?WorkerStopReason $reason = null,
         public ?int $jobsProcessed = null,
         public float|int|null $lastJobProcessedAt = null,
         public float|int|null $memoryUsage = null,
-        public ?string $connectionName = null,
-        public ?string $queue = null,
         public bool $terminatesImmediately = false,
     ) {
     }