Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

Referencia de la API PHP

18 min de lectura 11 apartados

En esta página

Todas las funciones globales y las clases del núcleo que un plugin o un theme puede usar, con sus firmas reales. Los servicios se piden al contenedor con app(Clase::class) o, mejor, se reciben en el constructor de tus clases (inyección por tipo).

Funciones globales #

Núcleo #

FunciónDevuelve
app(?string $abstract = null): mixedSin argumentos, la aplicación ($app->container, $app->hooks()). Con una clase, el servicio resuelto por el contenedor.
config(string $key, mixed $default = null): mixedConfiguración de config.php con notación de puntos (config('app.url')).
setting(string $key, mixed $default = null): mixedUn ajuste guardado (setting('general.site_name')).
db(): ConnectionLa conexión a la base de datos.
cache(): CacheManagerLa caché de objetos (archivos, APCu o Redis).
logger(): LoggerEl registro en content/logs/app.log.
request(): RequestLa petición actual.
hooks(): HookManagerEl gestor de hooks. Ver la referencia de hooks.
media(): MediaRepositoryLa biblioteca de medios.
mm_version(): stringVersión del núcleo (0.9.54).
now(): stringFecha y hora UTC en formato Y-m-d H:i:s, la que usan las columnas de la base de datos.

Texto y datos #

FunciónQué hace
e(mixed $value): stringEscapa para HTML. null → '', true → '1', arrays y objetos → JSON escapado.
str_limit(string $s, int $max = 160, string $end = '…'): stringRecorta un texto sin partir caracteres multibyte.
array_get(array $arr, string $key, mixed $default = null): mixedLee un array con notación de puntos ('a.b.c').
compact_number(int $n): string1500 → 1.5K, 2000000 → 2M.
minify_css(string $css): stringMinifica CSS (lo usan inline_css y tus estilos en línea).

Idiomas y URL #

FunciónQué hace
__(string $key, array $replace = [], ?string $lang = null): stringTraduce. 'dominio::clave' para los textos de un plugin o theme.
_n(string $key, int $count, array $replace = [], ?string $lang = null): stringTraduce con plural ('uno|varios'); rellena :count.
current_lang(): stringIdioma de la petición (es, en).
url(string $path = '/', bool $absolute = false): stringURL de una ruta del sitio en el idioma actual, con las palabras de URL del dueño (/movies → /peliculas).
lang_url(string $path, ?string $lang = null, bool $absolute = false): stringIgual, pero eligiendo idioma.
route(string $name, array $params = [], ?string $lang = null, bool $absolute = false): stringURL de una ruta con nombre. Los parámetros que sobran van a la query string.
site_url(string $path = '/'): stringURL absoluta con el dominio del sitio, sin traducir palabras ni añadir idioma (archivos, webhooks).

Vistas, formularios y medios #

FunciónQué hace
view(string $name, array $data = []): stringPinta una plantilla ('partials/card', 'mi-plugin::caja', 'admin::layout').
csrf_token(): string / csrf_field(): stringToken del panel y su <input type="hidden" name="_token">.
old(string $key, mixed $default = null): mixedValor enviado en el formulario anterior (tras un error de validación).
media_url(int $id, string $size = 'thumb', string $format = 'jpg'): stringURL de una variante de una imagen.
img(?array $media, string|int $size = 'thumb', array $options = []): string<picture> AVIF → WebP → JPEG con srcset, width y height. Opciones: alt, lazy (por defecto true), priority (la imagen del LCP), sizes, class, max.
art_img(?array $wide, ?array $tall, string $alt = '', bool $priority = false, string $class = 'bg'): stringImagen de fondo con arte horizontal en escritorio y vertical en móvil.

Las funciones de theme (player(), trailer_facade(), wordmark(), rating_badge(), rank_svg(), pagination(), lang_switcher(), theme_setting(), theme_vars(), inline_css(), theme_asset(), child_theme_asset(), brand_asset(), theme_file(), theme_dirs()) están en crear themes.

Extensiones #

FunciónQué hace
plugin_setting(string $slug, string $key, mixed $default = null): mixedAjuste de un plugin (los secret llegan descifrados).
plugin_active(string $slug): bool¿Está activo ese plugin?
plugin_providers(string $contract): arraySlugs de los plugins activos que declaran ese contrato en provides.
active_theme(): ?arrayManifest del theme activo (slug, name, version, contracts, supports…).
register_install_hook(string $slug, callable $fn)También register_activation_hook, register_upgrade_hook, register_deactivation_hook, register_uninstall_hook. Ver ciclo de vida.

Petición y respuesta #

MovieMaster\Http\Request #

MétodoDevuelve
method(), isGet(), isPost(), isMethod('PUT')Método HTTP (isGet() incluye HEAD).
path(): stringRuta normalizada, sin query string.
query(?string $key = null, $default = null)Parámetros de la query string (sin clave: todos).
post(?string $key = null, $default = null)Campos del formulario.
input(string $key, $default = null)Busca en el cuerpo JSON, el formulario y la query string.
all(): arrayTodo lo anterior junto.
string(string $key, string $default = '')Campo como texto recortado.
int(string $key, int $default = 0)Campo como entero.
bool(string $key, bool $default = false)Campo como booleano (1, true, on, yes).
array(string $key): arrayCampo como array.
json(): mixedCuerpo JSON decodificado.
rawBody(): stringCuerpo sin procesar (webhooks con firma).
file(string $key): ?array / files()Archivos subidos.
cookie(string $key, ?string $default = null), hasCookie(), cookies()Cookies.
header(string $name, ?string $default = null), headers()Cabeceras (sin distinguir mayúsculas).
ip(): stringIP del visitante.
isSecure(), scheme(), host(), baseUrl(), url(), fullUrl()Datos de la URL.
isAjax(), wantsJson(), userAgent(), referer()Datos del cliente.
param(string $key, $default = null)Parámetro de la ruta ({id}).
attribute(), setAttribute()Datos que los middleware pasan al controlador.

MovieMaster\Http\Response #

php
Response::html(string $body, int $status = 200)
Response::json(mixed $data, int $status = 200, int $flags = 0)
Response::xml(string $body, int $status = 200)
Response::text(string $body, int $status = 200)
Response::redirect(string $url, int $status = 302)
Response::notFound(string $body = 'Not Found')

Métodos encadenables: setStatus(int), setBody(string), header(string $name, string $value), cookie(string $name, string $value, int $expires = 0, array $options = []), cacheTags(array $tags) y noCache() (impide guardarla en la caché de páginas y envía Cache-Control: no-store).

Para cortar con un error desde cualquier punto: throw new \MovieMaster\Http\HttpException(404).

Router #

Lo recibes en las acciones routes (sitio público) y admin_routes (dentro de /admin). Para rutas públicas usa mejor $plugin->route().

php
$r->get(string $pattern, mixed $handler, array $options = []);   // también post, put, delete, any
$r->add(string|array $methods, string $pattern, mixed $handler, array $options = []);
$r->group(string $prefix, array $options, callable $fn);
$r->has(string $name): bool;
$r->url(string $name, array $params = []): string;

Base de datos #

Connection (db()) #

MétodoPara qué
table(string $table): QueryEmpieza una consulta. El nombre va sin prefijo.
select(string $sql, array $bindings = []): arraySQL a mano: todas las filas.
selectOne(string $sql, array $bindings = []): ?arraySQL a mano: una fila.
scalar(string $sql, array $bindings = []): mixedSQL a mano: un valor.
execute(string $sql, array $bindings = []): intSQL a mano que modifica: filas afectadas.
transaction(callable $fn): mixedEjecuta $fn en una transacción; si lanza, deshace.
prefixed(string $table): stringNombre real de la tabla (votos → mm_votos), para SQL a mano.
quoteId(string $id): stringEntrecomilla un identificador según el motor.
driver(), isMysql(), isSqlite()Motor en uso.
lastInsertId(): intÚltimo id insertado.

Query #

Constructor fluido. Todos los métodos de filtro devuelven la propia consulta.

GrupoMétodos
Selecciónselect(...$cols), addSelect(...), distinct(), from($table, $alias), Query::raw($sql, $bindings)
Condicioneswhere($col, $op, $val) (o where($col, $val)), orWhere(...), where(fn($q) => …) para agrupar, whereRaw($sql, $bindings), whereIn($col, array|Query), whereNotIn(...), whereNull($col), whereNotNull($col), whereBetween($col, $a, $b), whereLike($col, $value), whereExists(Query $sub)
Unionesjoin($table, $first, $op, $second), leftJoin(...), joinRaw($sql)
Orden y límitesorderBy($col, 'ASC'|'DESC'), orderByRaw($sql), latest($col = 'created_at'), inRandomOrder(), groupBy(...), having($sql, $bindings), limit($n), offset($n), forPage($page, $perPage)
Lecturaget(): array, first(): ?array, find($id, $col = 'id'), value($col), pluck($col, $key = null), exists(): bool, count(), sum($col), max($col), min($col), paginate($page, $perPage) → items, total, page, per_page, last_page
Escriturainsert(array) (una fila o varias), insertGetId(array): int, insertOrIgnore(array), upsert(array $values, array $uniqueBy, ?array $update), update(array): int, increment($col, $n = 1, $extra = []), decrement(...), delete(): int, truncate()
DepuracióntoSql(): array (SQL y bindings)
php
$top = db()->table('votos')
    ->select('title_id', Query::raw('COUNT(*) AS total'))
    ->where('created_at', '>=', gmdate('Y-m-d H:i:s', time() - 86400 * 7))
    ->groupBy('title_id')
    ->orderBy('total', 'DESC')
    ->limit(10)
    ->get();

db()->table('votos')->upsert(
    ['title_id' => 42, 'ip_hash' => $hash, 'estrellas' => 5, 'created_at' => now(), 'updated_at' => now()],
    ['title_id', 'ip_hash'],
    ['estrellas', 'updated_at'],
);

Migraciones: Schema y Blueprint #

Una migración extiende MovieMaster\Database\Migration e implementa up(Schema $schema, Connection $db): void. Ver base de datos y migraciones.

SchemaBlueprint (columnas)Column (modificadores)
create($table, fn(Blueprint $t)), table($table, fn) (alterar), drop($table), hasTable($table), hasColumn($table, $col), columns($table), rename($from, $to)id(), string($name, $len = 190), char(), text(), mediumText(), longText(), integer(), unsignedInteger(), bigInteger(), unsignedBigInteger(), smallInteger(), tinyInteger(), boolean(), decimal(), float(), date(), dateTime(), timestamp(), timestamps(), json(), binary(); índices primary(), unique(), index(), fulltext(); al alterar dropColumn(), dropIndex(), dropUnique(), renameColumn()nullable(), default($v), unsigned(), primary(), unique(), index(), useCurrent(), after($col) (solo MySQL)

Los tipos se traducen a MySQL/MariaDB y a SQLite automáticamente.

Ajustes y caché #

MovieMaster\Content\Settings #

MétodoPara qué
get(string $key, mixed $default = null): mixedLeer. Lo mismo que setting().
set(string $key, mixed $value, bool $autoload = true): voidGuardar uno. autoload = false para valores grandes que no hacen falta en cada petición.
setMany(array $values, bool $autoload = true): voidGuardar varios.
delete(string $key) / deleteGroup(string $prefix)Borrar uno o todos los que empiezan por un prefijo.
group(string $prefix): arrayTodos los de un prefijo ('plugin.mi-plugin.').

Caché de objetos (cache()) #

php
$datos = cache()->remember('mi-plugin:ranking', 600, fn() => calcularRanking());   // 10 minutos
cache()->get($key, $default); cache()->set($key, $value, $ttl = 3600); cache()->has($key);
cache()->delete($key); cache()->increment($key, $by = 1, $ttl = 3600);

El driver lo elige el dueño (archivos, APCu o Redis con el plugin Redis Cache). Un plugin puede añadir uno con CacheManager::extend('nombre', fn() => new MiDriver()) implementando MovieMaster\Cache\CacheInterface. Prefija siempre tus claves.

Caché de páginas y purgas #

Clase y métodoPara qué
PurgeService::title(int $id, array $extraTags = [])Purga la ficha, sus tarjetas, listados, portada, sitemaps, RSS y búsqueda.
PurgeService::term(int $id, string $taxonomy), person(int $id), page(int $id)Igual para términos, personas y páginas.
PurgeService::purge(array $tags)Purga etiquetas concretas (las tuyas).
PurgeService::all()Vacía toda la caché de páginas.
PageCache::purgePath(string $uri)Borra una URL concreta.
PageCache::enabled(): bool¿Está activa la caché estática?

Etiquetas que usa el núcleo: home, title:<id>, card:<id>, term:<id>, person:<id>, list:titles, list:movies, list:series, list:people, list:terms:genre, list:terms:tag, sitemap, rss, search, robots, pwa.

Contenido #

Los repositorios están en MovieMaster\Content\Repositories. Devuelven arrays ya traducidos al idioma pedido ($lang, por defecto el actual) y con url lista para enlazar. Escribe siempre a través de ellos: generan los 410 y 301, purgan la caché, reindexan la búsqueda y avisan a IndexNow.

TitleRepository (películas y series) #

MétodoPara qué
find(int $id, ?string $lang = null, bool $withRelations = true, int $castLimit = 0): ?arrayUn título con géneros, reparto, etc.
findBySlug(string $type, string $slug, ?string $lang = null, bool $publishedOnly = true): ?arrayPor slug (movie/series).
findByTmdb(string $type, int $tmdbId): ?intId local de un título de TMDB.
list(array $filters, int $limit, ?string $lang = null, bool $withRelations = false): arrayUna lista.
paginate(array $filters, int $page, int $perPage, ?string $lang = null, bool $withRelations = false): arrayUna página: items, total, page, per_page, last_page.
query(array $filters, ?string $lang = null): QueryLa consulta sin ejecutar, para afinarla tú.
published(?string $type = null): QuerySolo publicados y visibles.
related(array $title, int $limit, ?string $lang = null): arrayRelacionados.
hero(int $limit, ?string $lang = null): arrayLos del carrusel de portada.
counts(): array, years(?string $type = null): arrayTotales y años con títulos.
save(array $data, array $translations, ?array $termIds, ?array $credits, ?int $id = null): intCrear o editar.
delete(int $id): void, setStatus(array $ids, string $status): voidBorrar o cambiar estado (published, draft).
TitleRepository::isPublic(array $t): bool¿Lo puede ver un visitante?

Filtros de list, paginate y query:

FiltroValor
typemovie o series
ordernewest (por defecto), popular, views, trending, rating, year, release, updated, random
term_idId de un género o etiqueta
person_idId de una persona del reparto o equipo
yearAño
searchTexto a buscar
featured1 = solo destacados
with_backdrop1 = solo con imagen de fondo
excludeArray de ids a excluir
statusEstado (por defecto, solo publicados)
no_sources1 = solo sin fuentes de vídeo

Campos de un título: id, type, slug, url, title, overview, tagline, year, rating, runtime_label, poster, backdrop, logo (filas de media para img()), genres, tags, terms, cast, directors, writers, creators, meta_title, meta_description, noindex, is_fallback (la traducción vino del idioma por defecto).

EpisodeRepository #

MétodoPara qué
seasons(int $titleId, ?string $lang = null): array / season($titleId, $number, $lang)Temporadas.
episodes(int $titleId, int $seasonNumber, ?string $lang = null): arrayCapítulos de una temporada.
episode(int $titleId, int $season, int $episode, ?string $lang = null): ?array / find(int $id)Un capítulo.
neighbours(array $ep, ?string $lang = null): arrayAnterior y siguiente.
latest(int $limit, ?string $lang = null): arrayÚltimos capítulos publicados.
saveSeason(...), saveEpisode(...), deleteSeason(...), deleteEpisode(int $id)Escribir.
url(string $seriesSlug, int $season, int $episode, ?string $lang = null) / seasonUrl(...)URL de un capítulo o temporada.

PersonRepository, TermRepository y PageRepository #

RepositorioLecturaEscritura
PersonRepositoryfind, findBySlug, findMany(array $ids), paginate($page, $perPage, $lang, $search, $order), search($q, $limit), creditsForTitles(array $titleIds), findByTmdbsave, findOrCreateByName, delete, recount
TermRepositoryfind, findBySlug($taxonomy, $slug), findMany, all($taxonomy, $lang, $order, $limit, $onlyUsed), paginate($taxonomy, …), forTitles(array $titleIds, $lang, $taxonomy), search($taxonomy, $q), url(array $term)save($taxonomy, …), findOrCreateByName, findOrCreateByTmdb, delete, recount
PageRepositoryfind, findBySlug, all($lang, $publishedOnly, $footerOnly)save, delete

Las taxonomías del núcleo son genre y tag. Un plugin puede usar una propia ('plataforma') con TermRepository, y darle nombre y URL con los filtros taxonomy_label y taxonomy_url_prefix.

SourceRepository (fuentes de vídeo) #

MétodoPara qué
forTitle(int $titleId, ?int $episodeId = null, bool $activeOnly = true): arrayFuentes de una película o capítulo.
SourceRepository::grouped(array $sources): arrayAgrupadas por idioma, como las recibe player().
add(int $titleId, ?int $episodeId, string $url, array $meta = [])Añadir una (meta: language, quality, server, sort_order, is_active). Devuelve el id, o un texto con el error si la URL no es válida. Si ya existe, devuelve su id.
replace(int $titleId, ?int $episodeId, array $rows): arraySustituir todas.
delete(int $id)Borrar una.
SourceRepository::languages(), defaultLanguage(), serverName(string $url)Idiomas válidos, el inicial y el nombre del servidor de una URL.

MediaRepository (media()) #

MétodoPara qué
find(int $id): ?array, findMany(array $ids)Filas de media.
store(array|string $file, string $preset = 'thumb', ?int $userId = null, ?string $alt = null): arrayGuarda una imagen subida ($request->file('x')) o una ruta y genera las variantes.
importFromUrl(string $url, string $preset = 'thumb', ?int $userId = null, ?string $alt = null): arrayDescarga y procesa una imagen remota.
url(int|array $media, string|int $size = 'thumb', string $format = 'jpg'): stringURL de una variante.
delete(int $id): bool, updateAlt(int $id, string $alt)Borrar o cambiar el texto alternativo.

Presets: poster (2:3), backdrop (16:9), still (16:9), profile (2:3), thumb (16:9), logo, title_logo, cover, term, favicon, og. Para pintar, usa siempre img($media, 'poster', ['alt' => …]).

SEO, URL y redirecciones #

ClaseMétodos útiles
Seo\SeoBuildererror(int $status): PageSeo (base vacía para tus páginas), wrap(string $title): string (aplica el patrón de títulos del sitio).
Seo\PageSeoPropiedades públicas: title, description, canonical, robots, type, image, imageWidth, imageHeight, alternates, prev, next, videoUrl, videoDuration, publishedTime, graph.
Seo\MetaStoreget(string $entity, int $id, string $lang), save($entity, $id, array $byLang), forget($entity, $ids): título y descripción SEO propios de title, season, episode, term, person y page.
Seo\IndexNowenabled(), queue(array $paths, bool $urgent = false): avisa a Bing, Yandex y compañía de URL nuevas o cambiadas (los repositorios ya lo hacen).
Content\Redirectsadd(string $from, string $to, int $status = 301), gone(string $path) (410), find(string $path), delete(int $id), all().
Content\UrlKeyssetSeason(...), setEpisode(...): cambian la palabra de la URL de una temporada o capítulo creando los 301.
I18n\Langcurrent(), default(), enabled(), isEnabled($lang), url(string $path, ?string $lang), word(string $key, ?string $lang) (palabra de URL configurada: word('movie') → pelicula), locale().

Usuarios, permisos y seguridad #

Auth y roles #

php
$auth = app(\MovieMaster\Auth\Auth::class);
$auth->check();                  // ¿hay sesión en el panel?
$auth->user();                   // fila del usuario o null
$auth->id(); $auth->role();
$auth->can('manage_content');    // capacidad
RolCapacidades
adminTodas (*).
editoraccess_admin, manage_content, publish_content, edit_others_content, delete_content, upload_media, manage_terms, manage_people, manage_pages, view_stats
authoraccess_admin, manage_content, upload_media, view_stats

Las que solo tiene admin son manage_settings (ajustes, SEO, apariencia, plugins, themes, licencia, actualizaciones) y manage_users; también cualquier capacidad nueva que inventes, hasta que la des a otro rol. Un plugin puede dar capacidades nuevas a un rol con el filtro role_capabilities:

php
add_filter('role_capabilities', static function (array $caps, string $role): array {
    if ($role === 'editor') {
        $caps[] = 'mi_plugin_moderar';
    }
    return $caps;
});

Estos son los usuarios del panel. Los visitantes registrados del sitio son del plugin Members (Members\Guard, ver crear plugins).

Sesión, CSRF y límite de intentos #

ClaseMétodos
Auth\Session (solo panel)get, set, has, remove, flash($key, $value), getFlash($key), regenerate()
Auth\Csrf (solo panel)token(), validate(Request $request). En /admin ya se comprueba solo en cada POST.
Auth\RateLimitertooManyAttempts(string $key): bool, hit(string $key): int, availableIn(string $key): int (segundos), clear(string $key). Por defecto 5 intentos cada 15 minutos.
php
$limiter = app(\MovieMaster\Auth\RateLimiter::class);
$key = 'mi-plugin:voto:' . hash('sha256', $request->ip());
if ($limiter->tooManyAttempts($key)) {
    return Response::json(['error' => 'too_many'], 429);
}
$limiter->hit($key);

Secret #

MovieMaster\Extensions\Secret cifra con la clave del sitio (AES-256-GCM). Es lo que usan los ajustes secret.

php
$cifrado = Secret::encrypt($token);
$token = Secret::decrypt($cifrado);
Secret::isSet($cifrado);   // ¿hay valor guardado?

Correo #

php
$mailer = app(\MovieMaster\Mail\Mailer::class);
$mailer->later($to, $asunto, $texto);   // por la cola: lo normal
$mailer->send($to, $asunto, $texto);    // ahora mismo: true o false; el motivo en $mailer->error()
$mailer->usable();                      // ¿hay un método de envío configurado?

El correo es texto plano. El dueño elige el método en Ajustes → Correo; un plugin puede enviarlo por su cuenta (API de un proveedor) con el filtro mail_send.

Cola #

MovieMaster\Queue\Jobs (o $plugin->jobs()):

MétodoPara qué
push(string $type, array $payload = [], int $delaySeconds = 0, ?int $priority = null): intEncola un trabajo. Más prioridad = antes.
pushUnique(string $type, array $payload = [], int $delaySeconds = 0, ?int $priority = null): ?intIgual, salvo que ya haya uno pendiente con el mismo tipo y payload (null).
pending(): int, pendingOf(array $types): int, counts(): arrayCuántos esperan.
failed(int $limit = 50): array, retry(int $id): bool, delete(int $id)Gestionar fallidos.

Consola: Io #

Lo recibe run(array $args, Io $io) de un comando:

MétodoPara qué
line(string $s = ''), info(), success(), warn(), error(), title()Escribir (con color si la terminal lo admite; error va a stderr).
ask(string $question, ?string $default = null): stringPreguntar.
secret(string $question): stringPreguntar sin mostrar lo que se escribe.
confirm(string $question, bool $default = false): boolSí o no.
table(array $headers, array $rows)Tabla.

Registro (logger()) #

debug, info, notice, warning, error y critical reciben (string $mensaje, array $contexto = []); exception(Throwable $e) guarda la excepción con su traza. Todo va a content/logs/app.log.

php
try {
    $api->sync();
} catch (\Throwable $e) {
    logger()->exception($e, ['plugin' => 'mi-plugin']);
}

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?