API backend for administration panels based on vue-admin-front package.
Demo.
- PHP 7.1
- Laravel 5
npm i -D vue-admin-front
composer require mr-timofey/laravel-admin-apiFollow installation instructions from dependent packages: mr-timofey/laravel-aio-images for images processing, mr-timofey/laravel-simple-tokens for authorization.
For Laravel <= 5.4 add MrTimofey\LaravelAdminApi\ServiceProvider to your app.providers config.
php artisan vendor:publish --provider="MrTimofey\LaravelAdminApi\ServiceProvider"Look to config/admin_api.php for further package configuration instructions.
Follow vue-admin-front quick start guide.
For development purpose you may also want to execute npm i -D concurrently and add this script to your npm scripts:
{
"scripts": {
"dev": "concurrently --kill-others -n \" api ,admin\" -c \"blue,white\" \"php artisan serve\" \"npm run admin:dev\""
}
}It will run a development PHP server on port 8000 and vue-admin-front dev server on port 8080.
This package uses mr-timofey/laravel-simple-tokens to maintain authentication and authorization logic.
You can change a guard which is used for API by setting a proper auth:{guard name} middleware and guard name
in admin_api.api_middleware and admin_api.api_guard config respectively.
Remove auth middleware if you want to disable authorization.
Also you can completely replace authentication and authorization logic by rebinding auth controller class:
app()->bind(\MrTimofey\LaravelAdminApi\Http\Controllers\Auth::class, YourController::class)
Admin API will try to guess attribute types and generate field names by capitalizing attribute names using model's:
$visibleto get a list of fields to display on entity index page (if not set explicitly)$fillableto get a list of fields for editing (if not set explicitly)$hiddenfields will receive apasswordfield type$datesfields will receive adatetimefield type$castswill just set field types as-is (don't worry,vue-admin-frontsupports any Eloquent compatible types by aliasing them)- belongsTo, hasMany and belongsToMany relations will just work
You can also implement a MrTimofey\LaravelAdminApi\Contracts\ConfiguresAdminHandler interface and define a
configureAdminHandler($handler) method to make things more controllable.
Available field types and their options are described in vue-admin-front field types docs. Same for fields formatting for model index page vue-admin-front display types docs.
Usage example:
<?php
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Http\Request;
use MrTimofey\LaravelAdminApi\Contracts\ConfiguresAdminHandler;
use MrTimofey\LaravelAdminApi\ModelHandler;
class Post extends Model implements ConfiguresAdminHandler
{
protected $casts = [
'published' => 'bool'
];
public function category(): BelongsTo
{
return $this->belongsTo(Category::class);
}
public function tags(): BelongsToMany
{
return $this->belongsToMany(Tag::class);
}
public function scopeOnlyDrafts(Builder $q): Builder
{
return $q->whereRaw('draft IS TRUE');
}
public function configureAdminHandler(ModelHandler $handler): void
{
$handler->setTitle('Posts')
->setCreateTitle('Creating new post')
// placeholders can be used, see more: https://mr-timofey.gitbooks.io/vue-admin/placeholders.html
->setItemTitle('Editing post #{{ id }}')
// allow only these methods (everything is allowed by default)
->allowActions(['index', 'item', 'create', 'update', 'destroy'])
// ...or use policies instead
->usePolicies(true,
// optional policy method prefix (Policy::adminActionIndex, Policy::adminActionCreate, etc.)
'adminAction')
->addPreQueryModifier(function(Builder $q, Request $req): void {
// modify index query just after Model::newQuery() is called
$user = $req->user();
if ($user->role !== 'god') {
$q->where('author_user_id', $user->getKey());
}
})
->addPostQueryModifier(function(Builder $q,Request $req): void {
// modify index query just before execution
// useful if you want to set default sort order
$q->orderByDesc('created_at');
})
// automatically search with LIKE
->setSearchableFields(['title', 'summary'])
// ...or/and set custom search callback
->setSearchCallback(function(
Builder $q,
Request $req,
array $searchableFields): void {
$q->searchLikeAGod($req->get('search'));
})
// index page filters
->setFilterFields([
// auto relation filter
'category',
// see more about available prefix modifiers in ModelHandler::applyFilters phpdoc
'>~created_at' => [
'title' => 'Created after',
'type' => 'datetime'
],
// checkbox, applies scopeOnlyDrafts when checked
'drafts' => [
'scope' => 'onlyDrafts',
'type' => 'switcher'
]
])
// index page table columns
->setIndexFields([
'id',
'title',
// will be automatically formatted as datetime if $this->timestamps === true
// or if $this->dates includes 'created_at' field
'created_at',
// you can provide only title this way
'updated_at' => 'Last update date and time'
])
// item creating/editing form fields
->setItemFields([
'title',
// this just works
'category', // categories should be added to api_admin.models config
// this should just work as well but we want some customizations
'tags' => [
'title' => 'Attach tags',
// 'type' => 'relation', // not necessary if field name is same as a relation method
// 'entity' => 'tags', // tags should be added to api_admin.models config
// placeholders can be used, see more: https://mr-timofey.gitbooks.io/vue-admin/placeholders.html
'display' => '{{ name }}',
// relation widget will allow user to create new tags in-place
'allowCreate' => true,
// this field will be filled with the widget's search box input text
'createField' => 'name',
// fill some other fields with fixed values while creating new tag
'createDefaults' => ['description' => 'New tag'],
// customize suggestions query
'queryParams' => [
'sort' => ['sort' => 'asc']
]
],
'content' => ['type' => 'wysiwyg'],
// $casts => ['published' => 'bool'] will automatically set the right field type for you (checkbox)
'published'
])
// creating/editing validation rules (use $this to refer to the currently editing model instance)
->setValidationRules([
'tags' => ['array', 'between:3,8'],
'category' => ['required'],
'some_unique_field' => [
'required',
'unique,' . $this->getTable() . ',some_unique_field' .
($this->exists ? (',' . $this->getKey() . ',' . $this->getKeyName()) : '')
]
])
// ...or/and defined custom validation callback
->setValidationCallback(
/**
* @throws \Illuminate\Validation\ValidationException
*/
function(
\Illuminate\Http\Request $req,
array $rules,
array $messages,
// gathered from item fields configuration
array $titles
) {
$req->validate([ /* whatever */ ]);
})
// override default error messages
->setValidationMessages([
'category.required' => 'No category - no post'
]);
}
}Every action within an administrative panel can be tracked and processed with the Laravel's event system. Available events:
<?php
namespace MrTimofey\LaravelAdminApi\Events;
// abstract base class for all events (holds user identifier)
ModelEvent::class;
// single model instance action events
SingleModelEvent::class; // abstract base class for single model instance action events (holds item identifier)
ModelCreated::class;
ModelUpdated::class; // holds attributes changes, more info in phpdoc of this class
ModelDestroyed::class;
// bulk destroy (holds destroyed instances' identifiers)
BulkDestroyed::class;By default ModelUpdated will track only instance attributes (using Eloquent's Model::getDirty())
method and relation changes.
You can implement MrTimofey\LaravelAdminApi\Contracts\HasCustomChanges interface and define getCustomChanges()
method to enrich ModelUpdated::$changes field with any additional information you want to track. Default format
is to return array ['field_name' => [$oldValue, $newValue], ...].