feat: add the ability to create API routes with multiple route parameters

src/Concerns/HandlesRelationManyToManyOperations.php

@@ -17,11 +17,13 @@ trait HandlesRelationManyToManyOperations
      * Attach resource to the relation in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed>$args
      * @return JsonResponse
      */
-    public function attach(Request $request, $parentKey)
+    public function attach(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->attachWithTransaction($request, $parentKey);
@@ -237,11 +239,13 @@ protected function afterAttach(Request $request, Model $parentEntity, array &$at
      * Detach resource to the relation in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return JsonResponse
      */
-    public function detach(Request $request, $parentKey)
+    public function detach(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->detachWithTransaction($request, $parentKey);
@@ -360,11 +364,13 @@ protected function afterDetach(Request $request, Model $parentEntity, array &$de
      * Sync relation resources in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return JsonResponse
      */
-    public function sync(Request $request, $parentKey)
+    public function sync(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->syncWithTransaction($request, $parentKey);
@@ -486,11 +492,13 @@ protected function afterSync(Request $request, Model $parentEntity, array &$sync
      * Toggle relation resources in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return JsonResponse
      */
-    public function toggle(Request $request, $parentKey)
+    public function toggle(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->toggleWithTransaction($request, $parentKey);
@@ -603,12 +611,14 @@ protected function afterToggle(Request $request, Model $parentEntity, array &$to
      * Update relation resource pivot in a transaction-safe wqy.
      *
      * @param Request $request
-     * @param int|string $parentKey
-     * @param int|string $relatedKey
+     * @param array<int, mixed> $args
      * @return JsonResponse
      */
-    public function updatePivot(Request $request, $parentKey, $relatedKey)
+    public function updatePivot(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+        $relatedKey = $this->keyResolver->resolveRelationOperationRelatedKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->updatePivotWithTransaction($request, $parentKey, $relatedKey);

src/Concerns/HandlesRelationOneToManyOperations.php

@@ -14,11 +14,13 @@ trait HandlesRelationOneToManyOperations
      * Associates resource with another resource in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return Resource
      */
-    public function associate(Request $request, $parentKey)
+    public function associate(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->associateWithTransaction($request, $parentKey);
@@ -164,12 +166,14 @@ protected function afterAssociate(Request $request, Model $parentEntity, Model $
      * Disassociates resource from another resource in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
-     * @param int|string $relatedKey
+     * @param array<int, mixed> $args
      * @return Resource
      */
-    public function dissociate(Request $request, $parentKey, $relatedKey)
+    public function dissociate(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+        $relatedKey = $this->keyResolver->resolveRelationOperationRelatedKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->dissociateWithTransaction($request, $parentKey, $relatedKey);

src/Concerns/HandlesRelationStandardBatchOperations.php

@@ -17,11 +17,13 @@ trait HandlesRelationStandardBatchOperations
      * Create a batch of new relation resources in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return CollectionResource
      */
-    public function batchStore(Request $request, $parentKey)
+    public function batchStore(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->batchStoreWithTransaction($request, $parentKey);
@@ -161,11 +163,13 @@ protected function afterBatchStore(Request $request, Model $parentEntity, Collec
      * Updates a batch of relation resources in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return CollectionResource
      */
-    public function batchUpdate(Request $request, $parentKey)
+    public function batchUpdate(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->batchUpdateWithTransaction($request, $parentKey);
@@ -355,12 +359,14 @@ protected function afterBatchUpdate(Request $request, Model $parentEntity, Colle
      * Deletes a batch of relation resources in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return CollectionResource
      * @throws Exception
      */
-    public function batchDestroy(Request $request, $parentKey)
+    public function batchDestroy(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->batchDestroyWithTransaction($request, $parentKey);
@@ -527,12 +533,14 @@ protected function afterBatchDestroy(Request $request, Model $parentEntity, Coll
      * Restores a batch of relation resources in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return CollectionResource
      * @throws Exception
      */
-    public function batchRestore(Request $request, $parentKey)
+    public function batchRestore(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->batchRestoreWithTransaction($request, $parentKey);

src/Concerns/HandlesRelationStandardOperations.php

@@ -27,13 +27,15 @@ trait HandlesRelationStandardOperations
      * Fetch the list of relation resources.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return CollectionResource
      */
-    public function index(Request $request, $parentKey)
+    public function index(Request $request, ...$args)
     {
         $requestedRelations = $this->relationsResolver->requestedRelations($request);
 
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         $parentQuery = $this->buildIndexParentFetchQuery($request, $parentKey);
         $parentEntity = $this->runIndexParentFetchQuery($request, $parentQuery, $parentKey);
 
@@ -255,11 +257,13 @@ public function search(Request $request, $parentKey)
      * Create new relation resource.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @return Resource
      */
-    public function store(Request $request, $parentKey)
+    public function store(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->storeWithTransaction($request, $parentKey);
@@ -484,12 +488,14 @@ protected function afterStore(Request $request, Model $parentEntity, Model $enti
      * Fetch a relation resource.
      *
      * @param Request $request
-     * @param int|string $parentKey
-     * @param int|string|null $relatedKey
+     * @param array<int, mixed> $args
      * @return Resource
      */
-    public function show(Request $request, $parentKey, $relatedKey = null)
+    public function show(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+        $relatedKey = $this->keyResolver->resolveRelationOperationRelatedKey($request, $args);
+
         $parentQuery = $this->buildShowParentFetchQuery($request, $parentKey);
         $parentEntity = $this->runShowParentFetchQuery($request, $parentQuery, $parentKey);
 
@@ -672,12 +678,15 @@ protected function afterShow(Request $request, Model $parentEntity, Model $entit
      * Update a relation resource in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @param int|string|null $relatedKey
      * @return Resource
      */
-    public function update(Request $request, $parentKey, $relatedKey = null)
+    public function update(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+        $relatedKey = $this->keyResolver->resolveRelationOperationRelatedKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->updateWithTransaction($request, $parentKey, $relatedKey);
@@ -889,13 +898,16 @@ protected function afterUpdate(Request $request, Model $parentEntity, Model $ent
      * Delete a relation resource.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @param int|string|null $relatedKey
      * @return Resource
      * @throws Exception
      */
-    public function destroy(Request $request, $parentKey, $relatedKey = null)
+    public function destroy(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+        $relatedKey = $this->keyResolver->resolveRelationOperationRelatedKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->destroyWithTransaction($request, $parentKey, $relatedKey);
@@ -1079,12 +1091,15 @@ protected function afterDestroy(Request $request, Model $parentEntity, Model $en
      * Restores a previously deleted relation resource in a transaction-save way.
      *
      * @param Request $request
-     * @param int|string $parentKey
+     * @param array<int, mixed> $args
      * @param int|string|null $relatedKey
      * @return Resource
      */
-    public function restore(Request $request, $parentKey, $relatedKey = null)
+    public function restore(Request $request, ...$args)
     {
+        $parentKey = $this->keyResolver->resolveRelationOperationParentKey($request, $args);
+        $relatedKey = $this->keyResolver->resolveRelationOperationRelatedKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->restoreWithTransaction($request, $parentKey, $relatedKey);

src/Concerns/HandlesStandardOperations.php

@@ -329,17 +329,19 @@ protected function afterStore(Request $request, Model $entity)
      * Fetches resource.
      *
      * @param Request $request
-     * @param int|string $key
+     * @param array<int, mixed> $args
      * @return Resource
      * @throws AuthorizationException
      * @throws BindingResolutionException
      */
-    public function show(Request $request, $key)
+    public function show(Request $request, ...$args)
     {
         $requestedRelations = $this->relationsResolver->requestedRelations($request);
 
         $query = $this->buildShowFetchQuery($request, $requestedRelations);
 
+        $key = $this->keyResolver->resolveStandardOperationKey($request, $args);
+
         $beforeHookResult = $this->beforeShow($request, $key);
         if ($this->hookResponds($beforeHookResult)) {
             return $beforeHookResult;
@@ -438,11 +440,13 @@ protected function afterShow(Request $request, Model $entity)
      * Update a resource in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $key
+     * @param array<int, mixed> $args
      * @return Resource
      */
-    public function update(Request $request, $key)
+    public function update(Request $request, ...$args)
     {
+        $key = $this->keyResolver->resolveStandardOperationKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->updateWithTransaction($request, $key);
@@ -602,12 +606,14 @@ protected function afterUpdate(Request $request, Model $entity)
      * Deletes a resource.
      *
      * @param Request $request
-     * @param int|string $key
+     * @param array<int, mixed> $args
      * @return Resource
      * @throws Exception
      */
-    public function destroy(Request $request, $key)
+    public function destroy(Request $request, ...$args)
     {
+        $key = $this->keyResolver->resolveStandardOperationKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->destroyWithTransaction($request, $key);
@@ -767,12 +773,14 @@ protected function afterDestroy(Request $request, Model $entity)
      * Restore previously deleted resource in a transaction-safe way.
      *
      * @param Request $request
-     * @param int|string $key
+     * @param array<int, mixed> $args
      * @return Resource
      * @throws Exception
      */
-    public function restore(Request $request, $key)
+    public function restore(Request $request, ...$args)
     {
+        $key = $this->keyResolver->resolveStandardOperationKey($request, $args);
+
         try {
             $this->startTransaction();
             $result = $this->restoreWithTransaction($request, $key);

src/Contracts/KeyResolver.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Orion\Contracts;
+
+use Illuminate\Http\Request;
+
+interface KeyResolver
+{
+    public function resolveStandardOperationKey(Request $request, array $args);
+
+    public function resolveRelationOperationParentKey(Request $request, array $args);
+
+    public function resolveRelationOperationRelatedKey(Request $request, array $args);
+}

src/Drivers/Standard/KeyResolver.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Orion\Drivers\Standard;
+
+use Illuminate\Http\Request;
+
+class KeyResolver implements \Orion\Contracts\KeyResolver
+{
+    public function resolveStandardOperationKey(Request $request, array $args)
+    {
+        return $args[0];
+    }
+
+    public function resolveRelationOperationParentKey(Request $request, array $args)
+    {
+        return $args[0];
+    }
+
+    public function resolveRelationOperationRelatedKey(Request $request, array $args)
+    {
+        return $args[1] ?? null;
+    }
+}