Laravel Magic provides Abstract Controller, Model, generic Request, Traits, Exceptions and various middlewares in order to generate very easily and quickly API resources from scratch.
Laravel Magic is a free open source project. If you use the project, please star us on Github... it costs nothing but a click! 😉
You can install the package via composer:
composer require dominiquevienne/laravel-magicThis package does not provide
- any migration
- any configuration file
- any view
# Duration of the cache handled by the package
LARAVEL_MAGIC_CACHE_DEFAULT_DURATION=3600
# Used to ensure that queries handled by the AbstractController will use a Filters/ModelFilter.php class
LARAVEL_MAGIC_FILTER_MODE=paranoid
# Public key used to validate JWT tokens
OAUTH_KEY_PUB=myPublicKey
# Acceptable delay in seconds between two servers (used for tokens validation)
JWT_LEEWAY=300Extending your models from AbstractModel will give you the opportunity to get the autocompletion that comes with PHPDoc in your IDE and will make it possible to check if a relationship exist for the given model.
It will also make it possible for AbstractController to make the magic happen. (see Controllers).
<?php
namespace App\Models;
use Dominiquevienne\LaravelMagic\Models\AbstractModel;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;
/**
* @property-read int $id
* Your PHPDoc goes here
*/
class YourModel extends AbstractModel
{
use HasFactory;
protected $fillable = [
// ...
];
}Extending your controllers from AbstractController will give you the opportunity to get a fully automated way to generate index, show, destroy, update, store methods without writing a single controller line. This will fill 90% of the API Resource needs.
Since default methods are already available in AbstractController, you can directly configure your routes to target the usual methods and magic will happen.
<?php
namespace App\Http\Controllers;
use Dominiquevienne\LaravelMagic\Http\Controllers\AbstractController;
class YourController extends AbstractController
{
}When calling an index or show endpoint, you can add the with GET parameter in order to retrieve direct relationships of a given model.
The API will not throw an error / warning if relationship is not available.
If the property is not provided or if value is empty after sanitization, the query will result in a normal query without any relationship retrieval.
When calling an index or show endpoint, you can add the fields GET parameter in order to only retrieve the listed fields.
The API will not throw an error / warning if field is not available.
If the property is not provided or if value is empty after sanitization, the query will throw every available fields.
When calling an index endpoint, you can add the filter GET parameter in order to filter the list so you only retrieve the row you targeted.
The API will not throw an error / warning if the fields you use for filtering are not available.
If the property is not provided or if value is empty after sanitization, the query will result in a normal query retrieving all the rows.
When calling an index endpoint, you can add the filter GET parameter in order to order the provided result is ordered the way you need.
The API will throw an error if you provide a non-compliant string.
If the property is not provided, the query will result in a normal query retrieving all the rows without any specific sorting.
The standard Laravel pagination is integrated. Please refer to the official paginate documentation.
By default Laravel Magic will cache queries used for Index and Show methods. It will use their fingerprint to ensure that the cache value is the one corresponding to a unique query. This caching method takes in consideration the in-app filtering, user-filtering, fields, ordering, relationships and pagination.
The default behaviour is to store the query result in cache for 8 hours but the value can be overridden in your .env file through the LARAVEL_MAGIC_CACHE_DEFAULT_DURATION variable. The value of this variable is TTL for cache in seconds. Use LARAVEL_MAGIC_CACHE_DEFAULT_DURATION=0 if you want to avoid totally query caching.
Laravel Magic provides a BootstrapRequest file which will be call on any AbstractConctroller.create and AbstractConctroller.update methods. If a request which name is ModelnameRequest is available in your Requests folder, it will be used to generate the validation rules.
In your development, if you create a src/Http/Filters/ModelNameFilter.php class extending the GenericFilter class, Laravel Magic will automatically filter the way it retrieves data in your CRUD methods.
If this class has not been created, by default, no filtering is done. However, if you set LARAVEL_MAGIC_FILTERING_MODE=paranoid in your .env file, LaravelMagic will make it impossible to get any data.
Laravel Magic provides ForceJson and VerifyJwtToken middlewares. Those can be set up in Laravel Kernel.
We also provide the HasPublicationStatus, TimeStampsBy and SoftDeletesBy traits.
This trait will add a publication status to any of your model and store it in database.
To use the trait, add it to your models and migrate your schema so it has the publication_status_id field. Value of this field is handled by $publicationStatusAvailable property.
This trait will add creatorand an updater relationships and will automatically store the user id in the created_by and updated_by table properties. Those properties have to be added through migration.
This trait will add deleter relationship and will automatically store the user id in the deleted_by table property. Those properties have to be added through migration.
Laravel Magic provides those Exceptions:
- ControllerAutomationException
- EnvException
- PublicationStatusException
- StatusUnknownException
These are used internally but you can of course use them as you want.
composer testPlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.