README

A Responder Implementation for Laravel Projects.

Disclaimer

The packages under the BrightComponents namespace are basically a way for me to avoid copy/pasting simple functionality that I like in all of my projects. There's nothing groundbreaking here, just a little extra functionality for form requests, controllers, custom rules, services, etc.

Responders are a great way to make your controllers slim and keep the code related to responses in one place. The general idea is based on the "R" in ADR - Action Domain Responder, by Paul M. Jones.

For example, in your controller:

namespace App\Http\Controllers;

use App\MyDatasource;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
use App\Http\Responders\Post\IndexResponder;

class PostIndex implements Controller
{
    /**
     * The Responder.
     *
     * @var \App\Http\Responders\Post\IndexResponder
     */
    private $responder;

    /**
     * Construct a new PostIndex Controller.
     *
     * @param \App\Http\Responders\Post\IndexResponder $responder
     */
    public function __construct(Responder $responder)
    {
        $this->responder = $responder;
    }

    public function index(Request $request)
    {
        $data = MyDatasource::getSomeData($request);

        return $this->responder->respond($request, $data);
    }
}

Then in your responder:

namespace App\Http\Responders\Post;

use Illuminate\Http\Request;
use BrightComponents\Responder\Responder;

class IndexResponder extends Responder
{
    /**
     * Send a response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Illuminate\Database\Eloquent\Model|\Illuminate\Database\Eloquent\Collection|array|null  $data
     *
     * @return mixed
     */
    public function respond(Request $request, $data = null)
    {
        if ($request->isApi()) {
            // return json
        }

        return $this->view('posts.index', ['posts' => $data]);
    }
}

The benefit over the traditional "handle the response inside your controller actions", is the clarity it brings, the narrow class responsibility, fewer dependencies in your controller and overall organization. When used together with single action controllers, you can really clean up your controllers and bring a lot of clarity to your codebase.

Installation

You can install the package via composer:

composer require bright-components/responders

Note: Until version 1.0 is released, major features and bug fixes may be added between minor versions. To maintain stability, I recommend a restraint in the form of "^0.1.0". This would take the form of:

composer require "bright-components/responders:^0.1.0"

Laravel versions > 5.6.0 will automatically identify and register the service provider.

If you are using an older version of Laravel, add the package service provider to your config/app.php file, in the 'providers' array:

'providers' => [
    //...
    BrightComponents\Services\ResponderServiceProvider::class,
    //...
];

Then, run:

php artisan vendor:publish

and choose the BrightComponents/Responders option.

This will copy the package configuration (responders.php) to your 'config' folder. Here, you can set the root namespace for your Responder classes:

return [

    /*
    |--------------------------------------------------------------------------
    | Namespace
    |--------------------------------------------------------------------------
    |
    | Set the namespace for the Responders.
    |
 */

    'namespace' => 'Http\\Responders'
];

Usage

To begin using BrightComponents/Responders, simply follow the instructions above, then generate your Responder classes as needed. To generate an IndexResponder for Posts, as in the example above, enter the following command into your terminal:

php artisan adr:responder Post\\IndexResponder

Then add the responder as a dependency to your controller and call the respond method. This method expects an instance of Illuminate\Http\Request and an optional $data object:

public function index(Request $request)
{
    $data = MyDatasource::getSomeData();

    return $this->responder->respond($request, $data)
}

The abstract responder, that your responders extend, has a few 'helper' methods for working with responses:

    protected function view($view, $data = [], $mergeData = []);

    protected function redirect(string $path = null, $status = 302, array $headers = [], $secure = null);

    protected function flash($message, array $options = []); //uses DevMarketer/LaraFlash

    protected function json($content = '', $status = 500, array $headers = []);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email clay@phpstage.com instead of using the issue tracker.

Roadmap

We plan to work on flexibility/configuration soon, as well as release a framework agnostic version of the package.

Credits

License

The MIT License (MIT). Please see License File for more information.

bright-components / responders

Maintainers

Details