Cómo darle a un plugin su propia sección en el panel de administración: la página, su entrada en el menú, el controlador, las vistas con el aspecto del panel, los permisos y los hooks del admin. Los ajustes simples no necesitan nada de esto: con $plugin->setting() el núcleo pinta el formulario por ti.
Registrar una página #
// plugin.php
$plugin->adminPage('panel', __('mi-plugin::menu'), [MiPlugin\AdminController::class, 'handle'], [
'parent' => 'top',
'icon' => 'star',
'cap' => 'manage_content',
'order' => 60,
]);| Argumento | Qué es |
|---|---|
$key | Identificador de la página dentro del plugin. Forma la URL: /admin/p/<slug>/<key>. |
$label | Texto del menú y título por defecto de la página. Pásalo traducido. |
$handler | [Clase::class, 'metodo'], un closure o cualquier callable. Se llama igual que un controlador de ruta. |
$options | Opciones de la tabla siguiente. |
| Opción | Por defecto | Efecto |
|---|---|---|
parent | system | Grupo del menú donde aparece: movies, series, content, import, player, appearance, system, o top para una entrada propia en el primer nivel. |
icon | dot | Icono del menú (lista abajo). En los submenús se suele dejar dot. |
cap | manage_settings | Capacidad necesaria para ver la entrada y abrir la página. |
order | 50 | Posición dentro del grupo (menor = más arriba). Las entradas de primer nivel del núcleo van de 0 a 97. |
methods | ['GET', 'POST'] | Métodos HTTP que acepta la URL. |
Cada página tiene el nombre de ruta admin.plugin.<slug>.<key>, así que su URL se obtiene con route('admin.plugin.mi-plugin.panel'). Puedes registrar varias páginas con claves distintas; cada una es una entrada del menú.
Iconos del menú #
home, video, film, tv, folder, tag, star, image, file, palette, layout, plug, users, user, settings, refresh, cpu, server, dot, sliders, search, list, clock, inbox, globe, layers, play, filter, key, download, upload, check, alert, info, trash, edit, eye, plus, external.
Los mismos nombres sirven dentro de las vistas: @include('admin::partials/icon', ['name' => 'refresh']).
El controlador #
Hereda de MovieMaster\Admin\AdminController. Te da el layout del panel, los avisos y las redirecciones con mensaje:
| Método | Qué hace |
|---|---|
render(string $template, array $data = [], ?Request $request = null): Response | Pinta la vista con las variables del layout (usuario, menú, avisos, errores). Pasa page_title en $data para el título y la miga de pan. La respuesta sale con no-store. |
redirect(string $to, ?string $success = null, ?string $error = null): Response | Redirige y deja un aviso verde ($success) o rojo ($error) en la siguiente página. |
back(Request $request, array $errors, ?string $to = null): Response | Vuelve al formulario con los errores por campo y lo que se había escrito. |
json(mixed $data, int $status = 200): Response | Respuesta JSON, para llamadas desde JavaScript. |
Propiedades disponibles: $this->view, $this->session, $this->auth y $this->menu. Si necesitas más servicios, añádelos al constructor y llama al del padre:
<?php
declare(strict_types=1);
namespace MiPlugin;
use MovieMaster\Admin\AdminController as Base;
use MovieMaster\Admin\Menu;
use MovieMaster\Auth\Auth;
use MovieMaster\Auth\Session;
use MovieMaster\Http\Request;
use MovieMaster\Http\Response;
use MovieMaster\View\Engine;
final class AdminController extends Base
{
public function __construct(Engine $view, Session $session, Auth $auth, Menu $menu, private Repository $repo)
{
parent::__construct($view, $session, $auth, $menu);
}
public function handle(Request $request): Response
{
$here = route('admin.plugin.mi-plugin.panel');
if ($request->isPost()) {
$nombre = trim($request->string('nombre'));
if ($nombre === '') {
return $this->back($request, ['nombre' => __('mi-plugin::nombre_obligatorio')]);
}
$this->repo->crear($nombre);
return $this->redirect($here, __('mi-plugin::guardado'));
}
return $this->render('mi-plugin::admin', [
'page_title' => __('mi-plugin::menu'),
'items' => $this->repo->todos(),
'here' => $here,
], $request);
}
}Una sola URL atiende el GET (pintar) y el POST (guardar). Si la página tiene varias acciones, distingue con un campo oculto (<input type="hidden" name="action" value="borrar">) y un switch. Para varias vistas en la misma página, usa un parámetro ?tab=.
Vistas con el aspecto del panel #
Las vistas del plugin extienden el layout del panel con @extends('admin::layout'):
{{-- views/admin.tpl --}}
@extends('admin::layout')
@section('actions')
<a class="btn" href="{{ route('admin.settings', ['group' => 'plugin-mi-plugin']) }}">
@include('admin::partials/icon', ['name' => 'settings']) {{ __('admin.menu.settings') }}
</a>
@endsection
@section('help')
<p>{{ __('mi-plugin::ayuda') }}</p>
@endsection
@section('content')
<div class="grid two">
<section class="card">
<div class="card-head"><h2>{{ __('mi-plugin::nuevo') }}</h2></div>
<form method="post" action="{{ $here }}">
@csrf
<div class="field {{ isset($errors['nombre']) ? 'has-error' : '' }}">
<label for="nombre">{{ __('mi-plugin::nombre') }}</label>
<input id="nombre" name="nombre" value="{{ old('nombre') }}" required>
@if(isset($errors['nombre']))<p class="error">{{ $errors['nombre'] }}</p>@endif
</div>
<div class="form-actions">
<button class="btn primary" type="submit">{{ __('common.save') }}</button>
</div>
</form>
</section>
<section class="card">
<div class="card-head"><h2>{{ __('mi-plugin::lista') }}</h2></div>
@if($items)
<div class="table-wrap">
<table class="table">
<thead><tr><th>{{ __('mi-plugin::nombre') }}</th><th></th></tr></thead>
<tbody>
@foreach($items as $it)
<tr>
<td>{{ $it['nombre'] }}</td>
<td>
<form method="post" action="{{ $here }}" class="inline" data-confirm="{{ __('mi-plugin::confirmar_borrar') }}">
@csrf
<input type="hidden" name="action" value="borrar">
<input type="hidden" name="id" value="{{ $it['id'] }}">
<button class="btn ghost small">@include('admin::partials/icon', ['name' => 'trash'])</button>
</form>
</td>
</tr>
@endforeach
</tbody>
</table>
</div>
@else
<p class="empty muted">{{ __('mi-plugin::vacio') }}</p>
@endif
</section>
</div>
@endsectionSecciones del layout #
| Sección | Dónde sale |
|---|---|
content | El cuerpo de la página. Obligatoria. |
actions | Botones a la derecha del título (.page-actions). |
help | Un botón «?» junto al título que despliega este contenido. |
page_head | Sustituye la cabecera entera (título, acciones y ayuda). Para cabeceras a medida. |
head | Dentro del <head> del panel, solo en esta página: un <style> o un <script> propio. |
El layout ya muestra el título (page_title), la miga de pan y los avisos de redirect().
Variables del layout #
Además de lo que pases en $data, la vista recibe: $user (el usuario del panel), $menu, $flash (success/error), $errors (los de back(), por campo) y $page_title. Para repoblar un formulario tras un error usa old('campo', $valorPorDefecto).
Clases y componentes #
El CSS del panel ya está cargado. Usa sus clases para que tu página se vea como el resto:
| Clase | Uso |
|---|---|
.card, .card-head, .cards | Tarjetas con cabecera. |
.grid.two | Dos columnas que pasan a una en móvil. |
.field, .check, .row | Campo de formulario con su label; casilla; varios campos en una fila. Un campo con error lleva .field.has-error y el mensaje en <p class="error">. |
.form-actions (.sticky) | Barra de botones del formulario (fija al pie con .sticky). |
.btn, .btn.primary, .btn.ghost, .small | Botones. |
.table-wrap + .table (.compact) | Tablas con scroll horizontal en móvil. |
.badge, .tag | Etiquetas pequeñas de estado. |
.muted, .small, .empty, .inline | Texto secundario, pequeño, estado vacío, formulario en línea. |
.kpi, .kpi-head, .kpi-value | Cifras destacadas. |
Para tus propios estilos, usa las variables del panel y así respetas el modo claro y el oscuro: --color-bg, --color-card, --color-card-2, --color-ink, --color-ink-2, --color-muted, --color-line, --color-line-2, --color-primary, --color-primary-soft, --color-on-primary, --color-ok, --color-ok-soft, --color-warn, --color-warn-soft, --color-bad, --color-bad-soft, --color-info, --color-info-soft, --radius-sm, --radius-md, --radius-lg. Prefija tus clases (.mp-…) para no chocar con las del panel.
Comportamientos con atributos #
admin.js añade comportamiento a cualquier marcado que lleve estos atributos, también en las páginas de un plugin:
| Atributo | Efecto |
|---|---|
data-confirm="¿Seguro?" | En un <form>, botón o enlace: pide confirmación en un diálogo antes de seguir. |
[data-tabs] con botones [data-tab="x"] y paneles [data-panel="x"] | Pestañas dentro de la página. |
.field[data-hide-when="nombre"] | Oculta el campo mientras la casilla nombre está marcada. |
input[data-slug-from="#titulo"] | Rellena un slug a partir de otro campo. |
[data-media-picker] con un input oculto, [data-pick] y [data-clear] | Selector de la biblioteca de medios. |
label[data-dropzone] con input[type=file] | Zona para arrastrar archivos. |
Formularios y seguridad #
- CSRF: todas las peticiones a
/adminque no seanGET,HEADuOPTIONSdeben llevar el token. Pon@csrfen cada formulario; en JavaScript, envía la cabeceraX-CSRF-Token. El layout del panel ya imprime el token en<meta name="csrf-token">. Sin token la respuesta es un error 419. - Permisos: el núcleo comprueba la
capde la página antes de llamar a tu controlador. Si dentro hay acciones más delicadas, compruébalas tú:if (!$this->auth->can('manage_settings')) { … }. - Escapa todo lo que venga de la base de datos con
{{ }}. Usa{!! !!}solo con HTML que hayas generado tú. - Secretos: guarda claves de API con un ajuste de tipo
secret(cifrado en la base de datos), nunca en un campo de texto normal.
// Llamada desde JavaScript a tu propia página del panel
await fetch(url, {
method: 'POST',
headers: { 'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]')?.content ?? '' },
body: new FormData(form),
});Capacidades y roles #
| Capacidad | Quién la tiene |
|---|---|
access_admin | Todos los usuarios del panel. |
manage_content, upload_media | admin, editor y author. |
manage_terms, manage_people, manage_pages, publish_content… | admin y editor. |
manage_settings, manage_users | Solo admin. |
Una capacidad nueva (mi_plugin_moderar) solo la tiene admin hasta que se la des a otro rol con el filtro role_capabilities. La tabla completa está en la API PHP.
Rutas propias en el panel #
Si necesitas URLs que no son una entrada del menú (un endpoint JSON, una exportación, una acción de un botón), regístralas con la acción admin_routes. Quedan bajo /admin, con la sesión, la comprobación de login y el CSRF del panel:
add_action('admin_routes', function (\MovieMaster\Http\Router $r): void {
$r->get('/mi-plugin/exportar.csv', [MiPlugin\Export::class, 'csv'], [
'name' => 'mi-plugin.export', // route('admin.mi-plugin.export')
'cap' => 'manage_content',
]);
$r->post('/mi-plugin/api/ordenar', [MiPlugin\Api::class, 'ordenar'], ['cap' => 'manage_content']);
});El nombre recibe el prefijo admin.. Sin cap, basta con access_admin. Usa siempre un prefijo con el slug de tu plugin para no chocar con rutas del núcleo.
Modificar el menú #
El filtro admin_menu recibe todas las entradas antes de filtrar por permisos. Cada entrada es un array con key, label, route (nombre de ruta o URL), icon, cap, order y children (las entradas del grupo, por clave):
add_filter('admin_menu', function (array $items): array {
// Un enlace externo dentro del grupo Sistema
$items['system']['children']['mi-plugin-docs'] = [
'key' => 'mi-plugin-docs', 'label' => 'Ayuda de Mi Plugin',
'route' => 'https://mi-plugin.com/docs', 'icon' => 'dot',
'cap' => 'manage_settings', 'order' => 99, 'match' => null, 'children' => [],
];
// Ocultar una entrada a quien no sea admin
if (isset($items['import']['children']['queue'])) {
$items['import']['children']['queue']['cap'] = 'manage_settings';
}
return $items;
});Las claves de los grupos del núcleo son dashboard, movies, series, content, import, player, seo, appearance, settings y system. Para una página de tu plugin no hace falta este filtro: adminPage() ya crea la entrada.
Ajustes del plugin #
Los campos declarados con $plugin->setting() aparecen en Ajustes, en el grupo del plugin. Enlaza a ellos desde tu página:
route('admin.settings', ['group' => 'plugin-mi-plugin'])Y léelos con $plugin->get('clave') o, desde una clase, con setting('plugin.mi-plugin.clave'). Los tipos de campo, la validación y hide_when están en crear plugins.
Hooks del panel #
| Hook | Tipo | Para qué |
|---|---|---|
admin_menu | filtro | Cambiar las entradas del menú. |
admin_routes | acción | Registrar rutas bajo /admin. |
admin_head | acción | Imprimir en el <head> de todas las páginas del panel (CSS de tu plugin). |
admin_footer | acción | Imprimir antes de </body> del panel (JavaScript). |
admin_dashboard_widgets | filtro | Añadir tarjetas al escritorio. |
admin_dashboard_status_cards | filtro | Añadir tarjetas al bloque de estado del escritorio. |
admin_search_results | filtro | Añadir resultados al buscador del panel. |
admin_settings_field | acción | HTML propio debajo de un campo de Ajustes. |
admin_settings_links_for | filtro | Enlaces junto a un campo de Ajustes. |
admin_titles_index_top, admin_title_form_top, admin_title_actions | acción | Huecos en el listado y el editor de títulos. |
admin_catalog_panel | acción | Bajo el formulario de Admin → Catálogo. |
admin_onboarding_steps, admin_onboarding_items | filtro | Pasos de «Primeros pasos». |
Argumentos y detalles de cada uno en la referencia de hooks.
Un widget en el escritorio #
add_filter('admin_dashboard_widgets', function (array $widgets): array {
if (!app(\MovieMaster\Auth\Auth::class)->can('manage_content')) {
return $widgets;
}
$n = (int) db()->table('mi_plugin_items')->count();
$widgets[] = [
'title' => __('mi-plugin::widget'),
'html' => '<p class="kpi-value">' . e((string) $n) . '</p>'
. '<a class="btn small" href="' . e(route('admin.plugin.mi-plugin.panel')) . '">' . e(__('mi-plugin::abrir')) . '</a>',
];
return $widgets;
});El html se imprime tal cual dentro de una .card: escapa tú los datos con e(). Las tarjetas se muestran a todos los usuarios del panel, así que comprueba la capacidad antes de añadir la tuya.
CSS y JavaScript en todo el panel #
add_action('admin_head', function () use ($plugin): void {
echo '<link rel="stylesheet" href="' . e($plugin->asset('admin.css')) . '">';
});
add_action('admin_footer', function () use ($plugin): void {
echo '<script src="' . e($plugin->asset('admin.js')) . '" defer></script>';
});Si solo lo necesita tu página, ponlo en @section('head') de tu vista en lugar de cargarlo en todo el panel.
Buenas prácticas #
- Una entrada de menú por plugin es casi siempre suficiente. Organiza el resto con pestañas (
?tab=). - Elige la
capmínima que tenga sentido:manage_contentpara herramientas de contenido,manage_settingspara configuración. - Traduce todas las etiquetas (
__('mi-plugin::…')) y prueba la página en español y en inglés. - Prueba en móvil: el panel es responsive y tus tablas deben ir dentro de
.table-wrap. - Las tareas largas (importar, recorrer el catálogo) no van en la petición: mételas en la cola de trabajos y muestra el progreso.
- Si tu página cambia contenido público, purga la caché de páginas afectada. Ver caché de páginas.