Helpers and events

Global helpers

admin()

Returns the logged administrator or null.

if ( admin()?->hasAccess(Order::class, 'update') ) {
    // ...
}

Permission checks are described in Permissions.

autoAjax()

Returns a JSON response builder for messages, errors and store data.

return autoAjax()->success(_('Saved.'))->store(['cart' => $cart]);

autoAjax()->error(_('The order can not be changed.'))->throw();

See the bootstrap request for a larger example.

Frontend editor

uploadable(), linkable() and encryptText(): available with the crudadmin/website package (composer require crudadmin/website).

With the frontend editor enabled, administrators can replace images and links rendered by these helpers directly on the website. Without the editor, the default values are returned. See Frontend editor for everything the editor can change.

{{-- image with a key, default asset and optional resize --}}
<img src="{{ uploadable('hero', 'images/hero.jpg', [1200, 600]) }}" alt="">

{{-- link with a key and default URL --}}
<a href="{{ linkable('footer.contact', '/contact') }}">Contact</a>

Other helpers

trim_end('path///', '/');  // 'path'

Translation helpers (_(), localeUrl(), switchLocale(), localizedRoutes()) are described in Localization.

Text obfuscation

encryptText($text) obfuscates e-mails or phone numbers as base64 for frontend decoding. It is not encryption and should not be used to protect secrets. Decoding on the website is described in Obfuscated e-mails.

Admin facade

Request type

Admin::isAdmin() is true for URLs starting with /admin. Admin::isFrontend() is true for other HTTP requests, never in console.

public function scopeVisible($query)
{
    if ( Admin::isFrontend() ) {
        $query->where('visible', true);
    }
}

Models

$orders = Admin::getModel('Order');         // new App\Models\Order, the basename is case insensitive
$class = Admin::getModel('Order', true);    // 'App\Models\Order'
$model = Admin::getModelByTable('orders');  // new instance or null
Admin::hasAdminModel('Order');              // true

Request cache

A cache living for one request, shared by the whole administration.

$vatRates = Admin::cache('vat_rates', fn () => VatRate::pluck('rate', 'id'));

Log

Admin::log()->info('Stock imported'); // storage/logs/crudadmin.log

Configuration switches are available as Admin::isEnabledLocalization(), Admin::isEnabledAdminLocalization(), Admin::isHistoryEnabled() and Admin::isRolesEnabled(), see Configuration.

Admin events

Admin::event('my.event', function (&$value) {
    $value = strtoupper($value);
});

$args = [&$value];
Admin::fire('my.event', $args);

Admin::forgetEvent('my.event');

// class with a register() method
Admin::registerEvents(\Vendor\Package\Admin\Events::class);

Migration events

use Illuminate\Database\Schema\Blueprint;

Admin::event('migrations.orders.fire_after_all', function (Blueprint $table) {
    $table->index(['client_id', 'created_at']);
});

fire_after_migration runs after the table was migrated, fire_after_all after all tables. The _noScheme suffix runs the callback without the schema builder. Callbacks run once. For hooks inside the model see migration hooks.

Generator events

admin:model fires admin.command.model.create.stub_path, stub, namespaces, parameters, fields and options. admin:module fires admin.command.module.create.stub_path, stub and options. Arguments are passed by reference.

Admin::event('admin.command.model.create.fields', function (&$fields, $command) {
    $fields['sku'] = 'name:SKU|max:20';
});

Extending from packages

Registering models

public function boot()
{
    Admin::registerAdminModels(__DIR__.'/Models/*', 'Vendor\Package\Models');

    Admin::registerModel(\Vendor\Package\Models\Setting::class);
}

A model whose class basename is already registered is skipped.

Package service provider

A package has one service provider extending Admin\Providers\AdminPackageServiceProvider. It declares what the package brings, the base provider registers it and keeps it working with php artisan optimize: config files are merged only when the config is not cached, route files are loaded only when the routes are not cached.

src/Providers/AppServiceProvider.php

use Admin\Providers\AdminPackageServiceProvider;

class AppServiceProvider extends AdminPackageServiceProvider
{
    // config key => file. Values of the project win, missing keys are added, a list of the project replaces the list of the package
    protected $config = [
        'vendor_package' => __DIR__.'/../Config/config.php',
    ];

    // groups the project defines as a whole, the package does not add its items into them
    protected $replacedConfig = ['vendor_package.types'];

    // merged into config('admin'), lists are appended: scripts, styles, components, gettext paths, groups
    protected $adminConfig = __DIR__.'/../Config/admin.php';

    // route file => route group attributes
    protected $routes = [
        __DIR__.'/../Routes/routes.php' => ['middleware' => 'web', 'namespace' => 'Vendor\Package\Controllers'],
    ];

    // a directory of models (glob => namespace) or a model class; override models() when they depend on the config
    protected $models = [
        __DIR__.'/../Models/**' => 'Vendor\Package\Models',
        \Vendor\Package\Setting::class,
    ];

    // blade views, namespace => directory; a directory missing in the release is skipped
    protected $views = [
        'vendorpackage' => __DIR__.'/../Views',
    ];

    // files for php artisan vendor:publish, tag => [source => target in the project]
    protected $publishable = [
        'vendor_package.config' => [__DIR__.'/../Config/config.php' => 'config/vendor_package.php'],
    ];

    // built assets, source => directory in public/; admin:update publishes them and adds the directory into .gitignore
    protected $assets = [
        __DIR__.'/../../dist' => 'vendor/package',
    ];

    protected $assetsTag = 'vendor_package.assets';

    protected $listen = [
        OrderCreated::class => [SendOrderMail::class],
    ];

    protected $commands = [SyncCommand::class];

    // field mutations; a RuntimeMutation is applied in the administration only, after fields are compiled
    protected $mutations = [DefaultVat::class];

    // alias => facade, or alias => ['facade' => ..., 'class' => [abstract, concrete]]; the concrete class is
    // resolved again for every request, add 'shared' => true for a registry filled by the providers
    protected $facades = ['Package' => PackageFacade::class];

    // static state of one request, reset before every request and queue job of long running processes:
    // classes with a static flushState() method, or callables
    protected $flush = [PackageCart::class];

    protected $routeMiddleware = ['package' => PackageMiddleware::class];

    // changes of the config which a config file can not express, run only when the config is not cached
    protected function configure()
    {
        if (! config()->has('logging.channels.package')) {
            config()->set('logging.channels.package', ['driver' => 'single', 'path' => storage_path('logs/package.log')]);
        }
    }
}

Models of optional features are returned by models():

protected function models()
{
    return config('vendor_package.invoices') ? [__DIR__.'/../Models/Invoices/**' => 'Vendor\Package\Models\Invoices'] : [];
}

configure() and models() run once for the whole process under Laravel Octane (or once in config:cache), they read the config only, never the request, the session or the database. Settings set in boot() on a facade of a service bound per request are lost from the first Octane request on, keep them in static properties or in the config. Keep register() and boot() for other work (publishes, views, macros) and call parent::register() / parent::boot() first. Do not add separate config, route or event providers, and do not extend Laravel’s RouteServiceProvider or EventServiceProvider: with the application skeleton of Laravel 11 they load all routes of the application again and add the email verification listener once more. The config of $adminConfig looks like this, the groups of a package are [Class::class, 'method'] callables resolved late for translations:

src/Config/admin.php

return [
    'groups' => [[PackageGroups::class, 'groups']],
    'modules' => ['Vendor\Package\Admin\Modules' => __DIR__.'/../Admin/Modules'],
    'components' => [__DIR__.'/../Admin/Components'],
    'gettext' => ['source_paths' => [__DIR__.'/../Views']],
];

Rules for php artisan optimize: no closures in config files, env() only in config files, config()->set() only in configure(), routes only with controller actions and unique names prefixed by the package.

Getting started

Upgrade guide

Admin interface

Validation

Frontend

Website

Helpers and events

Global helpers

admin()

autoAjax()

Frontend editor

Other helpers

Text obfuscation

Admin facade

Request type

Models

Request cache

Log

Admin events

Migration events

Generator events

Extending from packages

Registering models

Package service provider

​Global helpers

​admin()

​autoAjax()

​Frontend editor

​Other helpers

​Text obfuscation

​Admin facade

​Request type

​Models

​Request cache

​Log

​Admin events

​Migration events

​Generator events

​Extending from packages

​Registering models

​Package service provider

Global helpers

admin()

autoAjax()

Frontend editor

Other helpers

Text obfuscation

Admin facade

Request type

Models

Request cache

Log

Admin events

Migration events

Generator events

Extending from packages

Registering models

Package service provider