Add support for routes with nested model binding

[nicodevs]

This PR introduces support for defining routes with nested model bindings by specifying a meta.parent attribute in the controller's configuration. The parent attribute identifies the name of the related model.

Example

Given the following draft:

controllers:
  Comment:
    resource: api
    meta:
      parent: post

Blueprint will generate a nested resource route instead of a standard resource route:

-Route::apiResource('comments', App\Http\Controllers\CommentController::class);
+Route::apiResource('posts/{post}/comments', App\Http\Controllers\CommentController::class);

The meta.parent works not only for web or API resources, but for individual routes as well:

Route::get('posts/{post}/comments/foobar', [App\Http\Controllers\CommentController::class, 'foobar']);

The controller methods will automatically inject the parent model as a parameter:

-public function index(Request $request): CommentCollection
+public function index(Request $request, Post $post): CommentCollection

And queries within the controller will utilize the parent model to scope operations. The relationship is inferred using the controller's name, following Laravel conventions:

-Comment::all();
+$post->comments()->get();

-Comment::create($request->validated());
+$post->comments()->create($request->validated());

Click here to see a full controller example

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use App\Models\Comment;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use App\Http\Resources\CommentResource;
use App\Http\Resources\CommentCollection;
use App\Http\Requests\CommentStoreRequest;
use App\Http\Requests\CommentUpdateRequest;

class CommentController extends Controller
{
    public function index(Request $request, Post $post): CommentCollection
    {
        $comments = $post->comments()->get();

        return new CommentCollection($comments);
    }

    public function store(CommentStoreRequest $request, Post $post): CommentResource
    {
        $comment = $post->comments()->create($request->validated());

        return new CommentResource($comment);
    }

    public function show(Request $request, Post $post, Comment $comment): CommentResource
    {
        return new CommentResource($comment);
    }

    public function update(CommentUpdateRequest $request, Post $post, Comment $comment): CommentResource
    {
        $comment->update($request->validated());

        return new CommentResource($comment);
    }

    public function destroy(Request $request, Post $post, Comment $comment): Response
    {
        $comment->delete();

        return response()->noContent();
    }
}

This PR also makes the necessary adjustments to the generated tests, both for Pest and PHPUnit, to fit the changes. You can check examples of these generated tests in tests/fixtures/tests/pest/api-resource-nested.php and tests/fixtures/tests/phpunit/api-resource-nested.php.

Testing

I have added tests to assert the correct generation of the route, controller, and tests when the meta.parent is present. I also added a test in ControllerLexerTest to assert that the parent is being set as expected.

The previous tests are passing, ensuring that the introduction of this feature does not alter the existing functionality.

Let me know if this approach is valid and if you would like to see any changes. It would be great to have this feature in Blueprint. Thank you!

[jasonmccreary]

Is this ready? There was like 1000 WIPs.

[nicodevs]

Yes @jasonmccreary ~ is ready for review.

Yes, I’ve made small commits while the PR was in draft, and squashed them before marking it ready. Sorry if that was unclear!

[jasonmccreary]

Cool. Thanks.

Just as a bit of inside info, a maintainer may receive notifications for all commits made to a PR (open or draft). So it's best not to open the PR until you feel it's ready to ready.

[nicodevs]

Oh, @jasonmccreary, sorry for the unintentional spam! I'll make sure to open PRs only when they're 100% ready for review.

Thank you so much for the merge!