- Definition & Principles
- Folder Structure
- Code Samples
- Request Properties
- How the authorize function work
- Allow a Role to access every endpoint
- Request Helper Functions
- Storing Data on the Request
- Unit Testing for Actions (Request)
- All Requests MUST extend from
- A Request MUST have a
rules()function, returning an array and
authorize()function to check for authorization (can return true when no authorization required).
If you are wondering what are those properties doing on the request! keep reading
By just injecting the request class you already applied the validation and authorization rules.
When you need to pass data to the Action, you should pass the request Object as it is to the Action parameter.
Apiato adds some new properties to the Request Class. Each of these properties are very useful for some situations, and let you achieve your goals faster and cleaner. Below we'll see a description for each property:
The $decode property is used for decoding Hashed ID's from any Request on the fly.
If you have enabled the HashID feature, most probably you are passing or allowing your users to pass Hashed (encoded) ID's into your application. These IDs need to be Decoded somewhere and Apiato has a property on its Requests Components where you can specify those Hashed ID's in order to decode them before applying the validation rules.
Note: validations rules that relies on your ID like (
exists:users,id) will not work unless you decode your ID before passing it to the validation.
The $urlParameters property is used for applying validation rules on the URL parameters:
Laravel by default does not allow validating the URL parameters (
/stores/999/items). In order to be able to apply validation rules on URL parameters you can simply define your URL parameters in the
$urlParameters property. This will also allow you to access those parameters form the Controller in the same way you access the Request data.
The $access property allows the user to define a set of Roles and Permissions that can access this endpoint.
$access property is used by the
hasAccess function defined below in the
authorize function, to check if the user has the necessary Roles & Permissions to call this endpoint (basically access the controller function where this request object is injected).
If you do not like the
laravelish style with
| in order to separate the different
permissions (e.g., see the example above),
you can also use the
array notation. The example from above would look like this (only part that changes):
authorize function is calling a
check function which accepts an array of function names. Each of those functions returns boolean.
In the example above we are calling three functions
| between the functions indicates an
OR operation, so if any of the functions
isOwner returns true the user will gain access and only when both return false the user will be prevented from accessing this endpoint.
On the other side if
isKing (a custom function could be written by you anywhere) returned false no matter what all other functions returns, the user will be prevented from accessing this endpoint, because the default operation between all functions in the array is
Checkout the hasAccess below.
The best way to add a custom authorize function is through a Trait, which can be added to your
Request classes. In the example below we create a Trait named
IsAuthorPermissionTrait with a single method called
isAuthor() method, in turn, calls a Task to verify that the current user is an author (e.g., if the user has the proper
Now, add the newly created Trait to the Request to use the
isAuthor function in the authorization check.
Now, the Request uses the newly created
isAuthor method to check the proper access rights.
You can allow some Roles to access every endpoint in the system without having to define that role in each Request object.
This is useful when you want to let users with
Admin role access everything.
To do this, define those roles in
app/Ship/Configs/apiato.php as follows:
This will append the
admin role to all roles access in every request object. Example: this
'roles' => 'manger' becomes
'roles' => 'manger|admin' (if the user is manager or admin "has any of the roles", will be allowed to access the endpoint function).
Apiato also provides some helpful functions by default, so you can use them whenever you need them.
hasAccess function, decides if user has Access or not based on the
If the user has any roles or permissions he will be given access.
If you need more or less roles/permissions just add
|between each permission.
If you do not need to set a roles/permissions just set
'permission' => ''or
'permission' => null.
Get the data from within the
$request by entering the name of the field. This function behaves like
however, it works on the decoded values instead of the original data.
Consider the following Request data in case you are passing
application/json data instead of
$request->input('id') would return
$request->getInputByKey('id') would return the
decoded value (e.g.,
Furthermore, one can define a
default value to be returned, if the key is not present (or not set), like so:
PATCH requests, if you like to submit only the fields, to be changed to the API in order to:
a) minimize the traffic
b) partially update the respective resource
Checking for the presence (or absence) of specific keys in the request typically results in huge
if blocks, like so:
So to avoid those
if blocks, you might use
array_filter($data) in order to remove
empty fields from the request.
However, in PHP
'' (empty string) are also considered
empty (which is not what you want clearly).
You can read more about this problem here.
In order to simplify sanitizing
Request Data when using
application/json instead of
apiato offers a convenient
sanitizeInput(array $fields) method.
Consider the following Request data:
This method lets you specify a list of
$fields to be accessed and extracted from the
$request. This is done using the
DOT notation. Finally, call the
sanitizeInput() method on the
$data looks like this:
data.blabla is not within the
$data array, as it was not present within the
$request. Furthermore, all
other fields from the
$request are omitted as they are not specified. So basically, the method creates some kind of
filter on the
$request, only passing the defined values. Furthermore, the DOT Notation allows you to easily specify
the fields to would like to pass through. This makes partially updating a resource quite easy!
You can also set default values while sanitizing data from the request
Sometimes you might want to map input from the request to other fields in order to automatically pass it to a
Task. Of course, you can manually map those fields, but you can also rely on the
mapInput(array $fields) helper
This helper, in turn, allows to "redefine" keys in the request for subsequent processing. Consider the following example request:
Your Task to process this data, however, requests the field
data.username. You can call the helper
The resulting structure would look like this:
During the Request life-cycle you may want to store some data on the request object and pass it to other SubActions (or Tasks).
To store some data on the request use:
To retrieve the data back at any time during the request life-cycle use:
Since we're passing Request objects to Actions. When writing unit tests we need to create fake Request just to pass it to the Action with some fake data.
Example Two (With Authenticated User):