El panel de administración

El panel de administración es la trastienda de tu proyecto: usuarios, roles, registros y los módulos opcionales, cada uno como un CRUD generado a partir de una clase PHP corta. Esta guía cubre lo que trae el panel y cómo registrar un recurso propio con Laravel Front, el paquete que lo dibuja.

Cómo llegar

El panel vive en /admin. Sus rutas están en routes/admin.php, y bootstrap/app.php envuelve ese archivo completo en los middleware web, auth, security y role:admin, bajo el prefijo de nombre de ruta admin.. Quien tiene sesión y el rol de administrador ve la entrada Go To Admin Panel en el menú de usuario, arriba a la derecha de la aplicación.

De esa pila de middleware se siguen tres cosas:

• Necesitas sesión. A un visitante se le manda a la página de inicio de sesión.
• security aplica las mismas revisiones que el resto del área de cuenta: una cuenta bloqueada pierde la sesión, y una cuenta marcada para cambiar contraseña va a la pantalla de contraseña antes que a ninguna otra.
• Necesitas el rol llamado admin. El middleware lleva ese nombre literal, así que la clave admin_role de config/app.php debe seguir siendo admin para que el panel abra.

Los superadministradores no son un rol. config/app.php → sudo es una lista de correos, y php artisan db:seed (a través de AdminSeeder) crea una cuenta por cada uno y le asigna el rol de administrador. Ese rol es el que abre la puerta; estar además en la lista sudo desbloquea la Dev Zone y el registro de actividad. Mira /help/sudo-and-super-administrators.

Ya dentro, cada pantalla revisa su propia política, y la política revisa un permiso con la forma {acción} {recurso}. El rol de administrador sembrado tiene todos los permisos, así que una instalación nueva lo muestra todo. Un rol que crees muestra sólo lo que le concedas, y un recurso que su rol no puede leer desaparece del menú. Mira /help/roles-and-permissions.

La disposición

Barra lateral. resources/views/layouts/sidebars/admin.blade.php renderiza el componente <x-sidebar-menu> (App\View\Components\SidebarMenu) con dos tipos de entradas: los enlaces manuales que declara (Dashboard en /admin y Dev Zone en /admin/dev, visible sólo para cuentas sudo) y cada recurso registrado que devuelve true en showOnMenu() y cuyo modelo pasa la revisión viewAny de su política para el usuario actual. Los recursos se agrupan por su $menu_group; uno sin grupo queda en el bloque sin encabezado de arriba. La barra declara el orden de sus grupos (Logs, Plans, Users); un grupo que no nombra va después de esos, en orden alfabético. Cada grupo recuerda en localStorage si lo dejaste abierto.

Búsqueda. Cuando el modelo del recurso usa el trait Searchable, la barra superior muestra un cuadro de búsqueda que filtra el índice por las columnas $searchable del modelo. Usuarios, roles y avisos se pueden buscar de fábrica.

Dashboard. /admin es un componente Livewire (App\Livewire\Admin\Dashboard) con un rango de fechas (por omisión, los últimos 30 días) y un selector de métrica. Las métricas siempre disponibles son New Registered Users, Total Accumulated Users, Activity Log Events, Daily Logged Users y Users by Country. Tracking Events aparece cuando FEATURE_TRACKING_ENABLED está encendida, Referral Subscriptions cuando FEATURE_REFERRALS_ENABLED está encendida, y el paquete de cobros agrega las suyas cuando está instalado. La métrica elegida se guarda en la URL, así que una vista del dashboard se puede guardar como marcador. Cada métrica está descrita en /help/dashboard-metrics-and-visitor-tracking.

Lo que trae el panel

Cada clase en app/Front/Resources/ es un recurso. Todas extienden la clase local App\Front\Resources\Resource, que fija los valores por omisión $section = 'admin', $showOnMenu = true y el icono circle-stack.

Tres pantallas son componentes Livewire normales registrados en el mismo archivo:

Registra un recurso propio

El ejemplo de abajo agrega un recurso Plan. Cambia el nombre por el tuyo.

1. Genera la clase

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

-a crea también App\Models\Plan, su migración y App\Policies\PlanPolicy. Usa -m para sólo el modelo y la migración, -p para sólo la política, o ninguna bandera cuando el modelo ya existe. El comando escribe app/Front/Resources/Plan.php desde una plantilla con $base_url = '/admin/plans'; la URL es el plural en snake case del nombre de la clase bajo el default_base_url (/admin) de la configuración del paquete.

composer dump-autoload importa: el seeder de permisos descubre los recursos en el mapa de clases de Composer, y el ajuste optimize-autoloader del proyecto sólo refresca ese mapa cuando lo vuelcas.

2. Describe la pantalla

<?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'),
        ];
    }
}

Las propiedades que entiende el recurso:

Campos. fields() devuelve inputs de WeblaborMx\Front\Inputs. El primer argumento es la etiqueta; la columna es su snake case salvo que pases un segundo argumento (Inputs\Text::make('Sent At', 'created_at')). Inputs disponibles: 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. El proyecto agrega los suyos bajo App\Front\Inputs: Password con botón generador, Pin, PermissionSelector y Categories.

Encadena esto en cualquier input:

Filtros. filters() devuelve instancias de las clases de app/Front/Filters/: TextFilter, SelectFilter (->options([...]), ->multiple()), BooleanFilter (->setTrueValue(...)) y DateFilter. setTitle($title, $field, $slug) nombra el filtro y, opcionalmente, la columna y la clave del query string; setOperator('>=') cambia la comparación y setScope('byPlan') delega en un scope del modelo. Cuando el modelo se puede buscar, el filtro de búsqueda se agrega solo.

Acciones. actions() devuelve clases que extienden App\Front\Actions\Action, un botón por registro. Define $title e $icon, pon $show_on_index = true para ofrecer el botón también en la lista y no sólo en el detalle, devuelve un booleano en hasPermissions($object) y haz el trabajo en handle($object). Devuelve una redirección o nada. Cuando fields() devuelve inputs, la acción muestra primero un formulario y recibe sus datos en $this->data. index_actions() hace lo mismo con clases que extienden App\Front\Actions\IndexAction, que actúan sobre la lista y no sobre un registro. ActingAs, BlockUser, ResetPin y CloneRole en app/Front/Actions/ son ejemplos que funcionan. GoToCategories es una acción lista cuyo handle() no recibe registro: redirige a la pantalla de categorías del tipo que le des con (new Actions\GoToCategories)->setTitle('Tags')->setType('tag').

Tarjetas. cards() devuelve tarjetas que se dibujan sobre la tabla del índice; el paquete trae WeblaborMx\Front\Cards\NumericCard, que extiendes con un método value() y que guarda su número en caché cinco minutos.

Páginas. Una pantalla que no es un CRUD — un reporte, un formulario de ajustes — extiende App\Front\Pages\Page, declara fields() para lo que muestra y post() para lo que guarda, y se registra con Route::page('Settings', 'settings'), que monta App\Front\Pages\Settings en /admin/settings para GET, POST, PUT y DELETE.

Ganchos. Sobrescribe estos para ejecutar código alrededor del CRUD: indexQuery($query) para cambiar la consulta del listado, indexResult($result) para cambiar la colección, processDataBeforeSaving($data) para editar la entrada antes de escribirla, beforeUpdate($object, $request), store($object, $request) y update($object, $request) después de guardar, processAfterSave($object, $request) después de cualquiera de los dos, destroy($object) antes de eliminar (devuelve false para impedirlo), y beforeRequest() para secuestrar cualquier petición después de la autorización.

Los ganchos de layout del paquete se configuran en config/front.php. El kit pone scripts_stack en scripts, el stack de Blade que el layout de la aplicación ya imprime, así que un input que necesita JavaScript lo empuja ahí.

3. Agrega la ruta

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

Route::front registra el CRUD completo en una línea. Dentro de routes/admin.php las rutas toman la familia de nombres admin.front.plans y el prefijo /admin/plans:

Un recurso registrado pero sin enlace desde ningún lado sigue siendo accesible por URL y sigue protegido por su política.

4. Escribe la política

<?php

namespace App\Policies;

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

$name es el singular de la tabla del modelo, y es la segunda palabra de cada permiso que el recurso necesita. $requiredConfig es opcional: cuando la clave de configuración que nombra es falsa, toda revisión falla, la pantalla se oculta del menú y sus rutas devuelven 403. Laravel encuentra App\Policies\PlanPolicy para App\Models\Plan por sí solo; sólo un modelo fuera de App\Models necesita Gate::policy() en AppServiceProvider::boot(), que es como se conecta ActivityPolicy.

5. Crea los permisos

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

El primer comando crea create plan, retrieve plan, update plan y delete plan; el segundo se los concede al rol de administrador. Hasta que corras ambos, incluso el administrador ve un 403 en la pantalla nueva. Las reglas completas están en /help/roles-and-permissions.

6. Ponlo en el menú

Nada que hacer: la barra lateral lee $menu_group, $menu_order e $icon de la clase, y oculta la entrada a quien su rol no tenga retrieve plan. Para darle una posición fija a un grupo nuevo, agrégalo a la lista :groups de resources/views/layouts/sidebars/admin.blade.php; para agregar un enlace que no es un recurso, agrégalo a :items con name, url, icon, un menu_group opcional, order y un booleano show.