README

This package contains a wide array of standard options for your API resources. Additionally, it generates a complete API resource based on your model. The package follows the default laravel folder/file structures.

Installation

composer require singlequote/laravel-api-resource

API Resource Generation

php artisan make:api-resource {model}

With the command above, you can generate a complete set for your API resources including the API controller, actions, requests, and an API resource.

For example, if we would want to generate an API resource for our User model.

php artisan make:api-resource User

The following files will be created:

App/Http/Controllers
    - ApiUserController

App/Actions/Users
    - DeleteUserAction
    - IndexUsersAction
    - ShowUserAction
    - StoreUserAction
    - UpdateUserAction

App/Http/Requests/Users
    - IndexUserRequest
    - ShowUserRequest
    - StoreUserRequest
    - UpdateUserRequest

App/Http/Resources
    - UserResource

After the generation is completed you can add your api resource route to your api.php route file.

/*
  |--------------------------------------------------------------------------
  | User routes
  |--------------------------------------------------------------------------
 */
Route::apiResource('users', UserController::class)->only('index', 'store', 'show', 'update', 'destroy');

Resource methods

The package comes with default methods that can be used to quickly setup your api. For instance the policy service can be used to add policies to your resource response.

   use SingleQuote\LaravelApiResource\Service\ApiPolicyService;

    public function toArray(Request $request): array
    {
        return [
            // ...
            'policies' => ApiPolicyService::defaults($this->resource),
        ];
    }

In addition you can pass additional policy methods as a second parameter.

'policies' => ApiPolicyService::defaults($this->resource, ['sendInvite', 'acceptInvite']),

Api methods

The package comes with default api options. To use the provided helpers, add the HasApi trait to your models.

helper	value
limit	number
search	array
where	array
whereIn	array
whereNotIn	array
whereHas	array
whereRelation	array
with	array
select	array
orderBy	string
orderByDesc	string

limit The default limit provided by the package is set to 1000 results per page. You can change the default in the laravel-api-resource config file. To change the limit for a single request you can use the limit helper.

axios.get(route('api.users.index', {
	limit : 100
}))

search A search helper is available if you want to create a search input. The search field accepts an array with 2 required fields. The field and query. The fields are the columns the api should search in. The query is the query used to search in the columns.

axios.get(route('api.users.index', {
	search: {
        fields: "name,email",
        query: "john"
    }
}))

where You may use the query builder's where method to add "where" clauses to the query. The most basic call to the where method requires 2 arguments. The first argument is the name of the column. The second argument is the value to compare against the column's value.

axios.get(route('api.users.index', {
	where: {
        first_name: "john"
    }
}))

whereIn The whereIn method verifies that a given column's value is contained within the given array:

axios.get(route('api.users.index', {
	whereIn: {
        role: ['admin', 'employee']
    }
}))

whereNotIn The whereNotIn method verifies that the given column's value is not contained in the given array

axios.get(route('api.users.index', {
	whereNotIn: {
        role: ['quests', 'visitors']
    }
}))

has When retrieving model records, you may wish to limit your results based on the existence of a relationship. For example, imagine you want to retrieve all users that have at least one role.

axios.get(route('api.users.index', {
	has:  ['roles']
}))

whereRelation If you would like to query for a relationship's existence with a single, simple where condition attached to the relationship query.

axios.get(route('api.users.index', {
	whereRelation:  {
		roles: {
            name: 'admin'
        }
	}
}))

with Sometimes you may need to eager load several different relationships. To do so, just pass an array of relationships to the with method

axios.get(route('api.users.index', {
	with: ['roles']
}))

select Sometimes you may only need a few columns from the resource and keep your api responses small.

axios.get(route('api.users.index', {
	select: ['id', 'name']
}))

orderBy/orderByDesc Sometimes you may want to change the ordering form your api response. You can use the orderBy or orderByDesc helper

axios.get(route('api.users.index', {
	orderBy: 'name'
}))

Contributing

Please see CONTRIBUTING for details.

Postcardware

You're free to use this package, but if it makes it to your production environment, we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Quotec, Traktieweg 8c 8304 BA, Emmeloord, Netherlands.

Credits

License

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

singlequote / laravel-api-resource

Maintainers

Details