Proposal: update stubs and use type declaration instead of phpdoc @param and @return

[madman-81]

In my opinion, type declaration allows for cleaner code than the phpdoc @param and @return notations. These were used back in the days when PHP didn't have type declaration. So I think now might be a good time to refactor the stubs used by the artisan commands and switch to php native type declarations.

For example controller.stub (src\Illuminate\Routing\Console\stubs) would go from this:

<?php

namespace {{ namespace }};

use {{ rootNamespace }}Http\Controllers\Controller;
use Illuminate\Http\Request;

class {{ class }} extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        //
    }

    /**
     * Show the form for creating a new resource.
     *
     * @return \Illuminate\Http\Response
     */
    public function create()
    {
        //
    }

    /**
     * Store a newly created resource in storage.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\Response
     */
    public function store(Request $request)
    {
        //
    }

    /**
     * Display the specified resource.
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
    public function show($id)
    {
        //
    }

    /**
     * Show the form for editing the specified resource.
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
    public function edit($id)
    {
        //
    }

    /**
     * Update the specified resource in storage.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
    public function update(Request $request, $id)
    {
        //
    }

    /**
     * Remove the specified resource from storage.
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
    public function destroy($id)
    {
        //
    }
}

To this:

<?php

namespace {{ namespace }};

use {{ rootNamespace }}Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class {{ class }} extends Controller
{
    /**
     * Display a listing of the resource.
     */
    public function index(): Response
    {
        //
    }

    /**
     * Show the form for creating a new resource.
     */
    public function create(): Response
    {
        //
    }

    /**
     * Store a newly created resource in storage.
     */
    public function store(Request $request): Response
    {
        //
    }

    /**
     * Display the specified resource.
     */
    public function show(int $id): Response
    {
        //
    }

    /**
     * Show the form for editing the specified resource.
     */
    public function edit(int $id): Response
    {
        //
    }

    /**
     * Update the specified resource in storage.
     */
    public function update(Request $request, int $id): Response
    {
        //
    }

    /**
     * Remove the specified resource from storage.
     */
    public function destroy(int $id): Response
    {
        //
    }
}

What are you thoughts? If this is something that's desirable, I can create a PR for this.

[Bowero]

I agree with you that this would be an improvement, but why can't we have both?

As phpdoc is still used everywhere else in the framework, I wouldn't just remove it. A lot of developers rely on tools that us phpdoc as their primary source of information and I see no harm in having it in place, especially in stubs.

[madman-81]

Thanks Bowero for sharing your thoughts here. This is exactly the reason why I posted it here, as a proposal: let's first find out what the best approach is before making a PR with a whole bunch of changes people don't want.

My personal opinion is that I don't need the @param or @return tags in the doc blocks, especially if I don't want to add a description to the parameters. Using both type hinting and leaving them in the dockblocks feels a bit like duplicate code. But then again, I don't run tools on my code that rely on the docblocks.

[crynobone]

Hey there,

We're closing this issue because it's inactive, already solved, old, or not relevant anymore. Feel free to open up a new issue if you're still experiencing this problem.

[shaedrich]

This was added to Laravel 10 via #44545