The admin panel

The admin panel is the back office of your project: users, roles, logs and the optional modules, each as a CRUD generated from a short PHP class. This guide covers what the panel ships with and how to register a resource of your own with Laravel Front, the package that renders it.

How to reach it

The panel lives at /admin. Its routes are in routes/admin.php, and bootstrap/app.php wraps that whole file in the middleware web, auth, security and role:admin, under the admin. route-name prefix. Signed-in users with the admin role see a Go To Admin Panel entry in the user menu at the top right of the application.

Three things follow from that middleware stack:

• You need a session. A visitor is sent to the login page.
• security applies the same checks as the rest of the account area: a blocked account is logged out, and an account flagged for a password change is sent to the password screen before anything else.
• You need the role named admin. The middleware carries that name literally, so the admin_role key in config/app.php must stay admin for the panel to open.

Super-administrators are not a role. config/app.php → sudo is a list of emails, and php artisan db:seed (through AdminSeeder) creates an account for each one and assigns it the admin role. That role is what opens the door; being on the sudo list on top of it unlocks the Dev Zone, the Design screen and the activity log. See /help/sudo-and-super-administrators.

Once inside, every screen checks its own policy, and the policy checks a permission of the shape {action} {resource}. The seeded admin role holds every permission, so a fresh install shows everything. A role you create shows only what you grant it, and a resource its role cannot read disappears from the menu. See /help/roles-and-permissions.

The layout

Sidebar. resources/views/layouts/sidebars/admin.blade.php renders the <x-design::sidebar-menu> component (App\Classes\SidebarMenu) with two kinds of entries: the manual links it declares, in this order — Dashboard at /admin, Space at /admin/space, Media at /admin/media, shown to accounts that can browse other accounts' media, Support inbox at /support, shown when the support tickets module is on and the account may answer tickets, and at the bottom Design at /admin/design and Dev Zone at /admin/dev, both shown only to sudo accounts — and every registered resource that returns true from showOnMenu() and whose model the current user passes the viewAny policy check for. Resources are grouped by their $menu_group; a resource with no group sits in the ungrouped block at the top. The sidebar declares the order of its groups (Logs, Plans, Users); a group it does not name goes after those, alphabetically. Each group remembers whether you left it open in localStorage.

Search. When the resource's model uses the Searchable trait, the top bar shows a search box that filters the index by the model's $searchable columns. Users, roles and announcements are searchable out of the box.

Dashboard. /admin is a Livewire component (App\Livewire\Admin\Dashboard) with a date range (default: the last 30 days) and a metric selector. The metrics always available are New Registered Users, Total Accumulated Users, Activity Log Events, Daily Logged Users and Users by Country. Tracking Events appears when FEATURE_TRACKING_ENABLED is on, Referral Subscriptions when FEATURE_REFERRALS_ENABLED is on, and the billing package adds its own when it is installed. The chosen metric is kept in the URL, so a dashboard view can be bookmarked. Each metric is described in /help/dashboard-metrics-and-visitor-tracking.

What ships with the panel

Every class in app/Front/Resources/ is a resource. All of them extend the local App\Front\Resources\Resource, which sets the defaults $section = 'admin', $showOnMenu = true and the circle-stack icon.

Six screens are plain Livewire components registered in the same file:

Register a resource of your own

The example below adds a Plan resource. Replace the name with yours.

1. Generate the class

php artisan front:resource Plan -a
composer dump-autoload

-a also creates App\Models\Plan, its migration and App\Policies\PlanPolicy. Use -m for the model and migration only, -p for the policy only, or no flag when the model already exists. The command writes app/Front/Resources/Plan.php from a stub with $base_url = '/admin/plans'; the URL is the plural snake case of the class name under default_base_url (/admin) from the package configuration.

composer dump-autoload matters: the permission seeder discovers resources from Composer's class map, and the project's optimize-autoloader setting only refreshes that map when you dump it.

2. Describe the screen

<?php

namespace App\Front\Resources;

use App\Front\Filters;
use App\Models\Plan as Model;
use WeblaborMx\Front\Inputs;

class Plan extends Resource
{
    public $base_url = '/admin/plans';
    public $model = Model::class;
    public $title = 'name';
    public $icon = 'credit-card';
    public $menu_group = 'Plans';
    public $menu_order = 1;

    public function indexQuery($query)
    {
        return $query->latest();
    }

    public function fields()
    {
        return [
            Inputs\ID::make(),
            Inputs\Text::make('Name')->rules(['required', 'string', 'max:255']),
            Inputs\Money::make('Price')->rules(['required', 'numeric', 'min:0']),
            Inputs\Boolean::make('Active')->default(true),
            Inputs\Textarea::make('Description')->hideFromIndex(),
            Inputs\DateTime::make('Created At')->onlyOnDetail(),
        ];
    }

    public function filters()
    {
        return [
            (new Filters\BooleanFilter)->setTitle('Active'),
            (new Filters\TextFilter)->setTitle('Name'),
        ];
    }
}

The properties the resource understands:

Fields. fields() returns inputs from WeblaborMx\Front\Inputs. The first argument is the label; the column is its snake case unless you pass a second argument (Inputs\Text::make('Sent At', 'created_at')). Available inputs: Autocomplete, BelongsTo, BelongsToMany, Boolean, Check, Checkboxes, Code, Date, DateTime, Disabled, File, HasMany, HasOneThrough, Hidden, ID, Image, ImageCropper, ImagePointer, Images, InputGroup, Money, MorphMany, MorphTo, MorphToMany, Number, Password, Percentage, Select, Text, Textarea, Time, ToastEditor (Markdown), Trix. The project adds its own under App\Front\Inputs: Password with a generator button, Pin, PermissionSelector and Categories.

Chain these on any input:

Filters. filters() returns instances of the classes in app/Front/Filters/: TextFilter, SelectFilter (->options([...]), ->multiple()), BooleanFilter (->setTrueValue(...)) and DateFilter. setTitle($title, $field, $slug) names the filter and, optionally, the column and the query-string key; setOperator('>=') changes the comparison and setScope('byPlan') delegates to a model scope instead. A search filter is added for you when the model is searchable.

Actions. actions() returns classes extending App\Front\Actions\Action, one button per record. Set $title and $icon, put $show_on_index = true to offer the button on the list as well as on the detail page, return a boolean from hasPermissions($object) and do the work in handle($object). Return a redirect or nothing. When fields() returns inputs, the action first shows a form and receives its data in $this->data. An action with no fields — or only hidden ones — runs from its button, which sends a POST with the form token; opening its address with GET only shows the action screen and changes nothing, so a link or a prefetch never runs it. index_actions() does the same with classes extending App\Front\Actions\IndexAction, which act on the list rather than on one record. ActingAs, BlockUser, ResetPin and CloneRole in app/Front/Actions/ are working examples. GoToCategories is a ready-made action whose handle() takes no record: it redirects to the categories screen for the type you give it with (new Actions\GoToCategories)->setTitle('Tags')->setType('tag').

Cards. cards() returns cards rendered above the index table; the package ships WeblaborMx\Front\Cards\NumericCard, which you extend with a value() method and which caches its number for five minutes.

Pages. A screen that is not a CRUD — a report, a settings form — extends App\Front\Pages\Page, declares fields() for what it shows and post() for what it saves, and is registered with Route::page('Settings', 'settings'), which mounts App\Front\Pages\Settings at /admin/settings for GET, POST, PUT and DELETE.

Hooks. Override these to run code around the CRUD: indexQuery($query) to change the listing query, indexResult($result) to change the collection, processDataBeforeSaving($data) to edit the input before it is written, beforeUpdate($object, $request), store($object, $request) and update($object, $request) after a save, processAfterSave($object, $request) after either, destroy($object) before deleting (return false to stop it), and beforeRequest() to hijack any request after authorization.

The package's layout hooks are configured in config/front.php. The kit sets scripts_stack to scripts, the Blade stack the application layout already prints, so an input that needs JavaScript pushes it there.

3. Add the route

// routes/admin.php
Route::front('Plan');

Route::front registers the whole CRUD in one line. Inside routes/admin.php the routes take the admin.front.plans name family and the /admin/plans prefix:

A resource that is registered but not linked from anywhere is still reachable by URL and still protected by its policy.

4. Write the policy

<?php

namespace App\Policies;

class PlanPolicy extends BasePolicy
{
    protected string $name = 'plan';
    protected $requiredConfig = 'features.plans_enabled';
}

$name is the singular of the model's table, and it is the second word of every permission the resource needs. $requiredConfig is optional: when the config key it names is false, every check fails, the screen hides from the menu and its routes return 403. Laravel finds App\Policies\PlanPolicy for App\Models\Plan on its own; only a model outside App\Models needs Gate::policy() in AppServiceProvider::boot(), which is how ActivityPolicy is attached.

5. Create the permissions

php artisan db:seed --class=PermissionSeeder
php artisan db:seed --class=RoleSeeder

The first command creates create plan, retrieve plan, update plan and delete plan; the second grants them to the admin role. Until you run both, even the admin sees a 403 on the new screen. The full rules are in /help/roles-and-permissions.

6. Put it in the menu

Nothing to do: the sidebar reads $menu_group, $menu_order and $icon from the class, and hides the entry from anyone whose role lacks retrieve plan. To give a new group a fixed position, add it to the :groups list of resources/views/layouts/sidebars/admin.blade.php; to add a link that is not a resource, add it to :items with a name, url, icon, optional menu_group, order and a show boolean.