GitHub Repository

apiato

Definition & Principles

Read from the Porto SAP Documentation (#Controllers).

Rules

Folder Structure

 - app
    - Containers
        - {container-name}
            - UI
                - API
                    - Controllers
                        - Controller.php
                - WEB
                    - Controllers
                        - Controller.php

Code Sample

User Web Welcome Controller:

<?php

class Controller extends PortWebController
{

    public function sayWelcome()
    {
        return view('welcome');
    }
}

User API Login Controller:

<?php

class Controller extends ApiController
{

    /**
     * @param \App\Containers\User\UI\API\Requests\RegisterUserRequest $request
     *
     * @return  mixed
     */
    public function registerUser(RegisterUserRequest $request)
    {
        $user = Apiato::call(RegisterUserAction::class, [$request]);

        return $this->transform($user, UserTransformer::class);
    }

    /**
     * @param \App\Containers\User\UI\API\Requests\DeleteUserRequest $request
     *
     * @return  \Illuminate\Http\JsonResponse
     */
    public function deleteUser(DeleteUserRequest $request)
    {
        $user = Apiato::call(DeleteUserAction::class, [$request]);

        return $this->deleted($user);
    }

    // ...
}

Notice we call the Action using Apiato::call() which triggers the run function in the Action as well inform the action which UI called it, ($this->getUI()) in case you wanna handle the same Action differently based on the UI type.

The second parameter of the call function is an array of the Action parameters in order. When you need to pass data to the Action, it’s recommended to pass the Request Object as it should be the place that holds the state of your current request.

Refer to the Magical Call page for more info and examples on how to use the call function.

Example: Usage from Routes Endpoint:

<?php

$router->post('login', [
    'uses' => 'Controller@loginUser',
]);

$router->post('logout', [
    'uses'       => 'Controller@logoutUser',
    'middleware' => [
        'api.auth',
    ],
]);

Controller response builder helper functions

Many helper function are there to help you build your response faster, those helpers exist in the vendor/apiato/core/Traits/ResponseTrait.php.

Some functions

transform This is the most useful function which you will be using in most cases.

// $user is a User Object
return $this->transform($user, UserTransformer::class);

// $orders is a Collection of Order Objects
return $this->transform($orders, OrderTransformer::class, ['products', 'recipients', 'store', 'invoice']);

withMeta This function allows including meta data in the response.

$metaData = ['total_credits', 10000];

return $this->withMeta($metaData)->transform($receipt, ReceiptTransformer::class);

json This function allows passing array data to be represented as json.

return $this->json([
    'foo': 'bar'
]);

Other functions