Planificador de Grav

El planificador de tareas (scheduler) de Grav es una nueva característica añadida en Grav 1.6 que permite ejecutar trabajos de forma periódica. El procesamiento subyacente depende del servicio cron del servidor, pero una vez que se ha añadido una entrada al servicio cron, todos los trabajos y programaciones específicas pueden configurarse a través de Grav.

Una de las principales ventajas de utilizar el planificador para manejar tareas es que pueden realizarse sin interacción del usuario y de forma independiente al frontend. Tareas como limpieza periódica de caché, copias de seguridad, sincronización, indexación de búsquedas, etc., son candidatos ideales para trabajos programados.

Instalación

El primer paso para configurar el planificador es añadir el comando bin/grav scheduler al servicio cron. El enfoque más simple es utilizar el propio comando CLI para mostrar el comando apropiado para la instalación:

$ bin/grav scheduler -i

Instalar Planificador
=====================

 [ERROR] Aún necesitas configurar el Planificador de Grav en tu crontab

Nota

Para instalar, ejecuta el siguiente comando en tu terminal:

 (crontab -l; echo "* * * * * cd /Users/andym/grav;/usr/local/bin/php bin/grav scheduler 1>> /dev/null 2>&1") | crontab -

En sistemas Mac, se muestra el comando completo necesario, por lo que solo debes copiar y pegar todo en tu terminal y presionar enter.

Debes iniciar sesión en la shell con el mismo usuario que tu servidor web. Esto asegura que el usuario que ejecuta los comandos del planificador coincida con el usuario del servidor web que necesita interactuar con esos archivos. Si instalas la entrada crontab con otro usuario (ej. root), los archivos creados tendrán ese usuario root y no el usuario webserver, lo que puede causar problemas.

(crontab -l; echo "* * * * * cd /Users/andym/grav;/usr/local/bin/php bin/grav scheduler 1>> /dev/null 2>&1") | crontab -

No recibirás una respuesta, pero tampoco deberías obtener errores. Luego puedes confirmar que todo está correcto volviendo a ejecutar el comando bin/grav scheduler -i:

bin/grav scheduler -i

Instalar Planificador
=====================

 [OK] ¡Todo listo! Ya has configurado el Planificador de Grav en tu crontab

También puedes obtener el comando necesario desde el plugin Admin navegando a Herramientas → Planificador.

Conceptos básicos de programación

La frecuencia de los trabajos se controla mediante un formato flexible:

* * * * * *
| | | | | |
| | | | | +-- Año              (rango: 1900-3000)
| | | | +---- Día de la semana (rango: 1-7, 1=lunes)
| | | +------ Mes del año      (rango: 1-12)
| | +-------- Día del mes      (rango: 1-31)
| +---------- Hora             (rango: 0-23)
+------------ Minuto           (rango: 0-59)

Algunos ejemplos:

0 * * * * ejecutar una vez por hora (cada hora en el minuto 0)
0 0 * * * ejecutar una vez al día (cada día a medianoche)
0 0 1 * * ejecutar una vez al mes (el primer día de cada mes)
0 0 1 1 * ejecutar una vez al año (el primer día de enero)

Opciones avanzadas:

*/5 * * * * ejecutar cada 5 minutos

Archivo de configuración

Puedes ver qué trabajos están disponibles actualmente para el Planificador ejecutando bin/grav scheduler -j:

bin/grav scheduler -j

Scheduler Jobs Listing
======================

| Job ID              | Command                            | Run At    | Status  | Last Run         | State   |
|---------------------|------------------------------------|-----------|---------|------------------|---------|
| cache-purge         | Grav\Common\Cache::purgeJob        | * * * * * | Success | 2019-02-21 11:23 | Enabled |
| cache-clear         | Grav\Common\Cache::clearJob        | * * * * * | Success | 2019-02-21 11:23 | Enabled |
| default-site-backup | Grav\Common\Backup\Backups::backup | 0 3 * * * | Ready   | Never            | Enabled |
| pages-backup        | Grav\Common\Backup\Backups::backup | * 3 * * * | Success | 2018-09-20 09:55 | Enabled |
| ls-job              | ls                                 | * * * * * | Success | 2019-02-21 11:23 | Enabled |

[NOTA] Para detalles de errores ejecuta "bin/grav scheduler -d"

El planificador de Grav se controla mediante un archivo de configuración principal ubicado en user/config/scheduler.yaml, que debe tener cada trabajo como enabled para poder ejecutarse.

La configuración muestra los trabajos disponibles y si están activados o no. Simplemente establece una entrada como disabled para detener su ejecución.

status:
  ls-job: enabled
  cache-purge: enabled
  cache-clear: enabled
  default-site-backup: enabled
  pages-backup: enabled

Para ver más detalles sobre posibles errores o cuándo se ejecutará el próximo trabajo, usa /bin/grav scheduler -d:

bin/grav scheduler -d

Job Details
===========

┌─────────────────────┬──────────────────┬──────────────────┬────────┐
│ Job ID              │ Last Run         │ Next Run         │ Errors │
├─────────────────────┼──────────────────┼──────────────────┼────────┤
│ cache-purge         │ 2019-02-21 11:29 │ 2019-02-21 11:31 │ None   │
│ cache-clear         │ 2019-02-21 11:29 │ 2019-02-21 11:31 │ None   │
│ default-site-backup │ Never            │ 2019-02-22 03:00 │ None   │
│ pages-backup        │ 2018-09-20 09:55 │ 2019-02-22 03:00 │ None   │
│ ls-job              │ 2019-02-21 11:29 │ 2019-02-21 11:31 │ None   │
└─────────────────────┴──────────────────┴──────────────────┴────────┘

Ejecución manual de trabajos

El comando CLI proporciona una forma simple de ejecutar trabajos manualmente. De hecho, esto es lo que hace el planificador cuando se ejecuta periódicamente.

bin/grav scheduler

Esto ejecutará los trabajos silenciosamente, pero también puedes ver detalles con:

bin/grav scheduler -v

Trabajos del sistema Grav

El núcleo de Grav proporciona algunos trabajos listos para usar, incluyendo tareas útiles de mantenimiento:

cache-purge - Útil si usas caché de archivos en Grav, ya que limpia archivos antiguos expirados.
cache-clear - Similar al comando bin/grav clear que se ejecuta manualmente.
default-site-backup - Trabajo de copia de seguridad disponible en la configuración de Backup de Grav.

Trabajos personalizados

El Planificador de Grav puede configurarse manualmente con cualquier número de trabajos personalizados en el archivo scheduler.yaml. Por ejemplo:

custom_jobs:
  ls-job:
    command: ls
    args: '-lah'
    at: '* * * * *'
    output: logs/cron-ls.out
    output_mode: overwrite
    email: user@email.com

Trabajos de plugins

Una de las características más potentes es que los plugins de terceros pueden proporcionar sus propios trabajos. Un gran ejemplo es el plugin TNTSearch, que permite reindexar contenido periódicamente.

Los plugins deben suscribirse al evento onSchedulerInitialized() y añadir trabajos cuando se llame:

public function onSchedulerInitialized(Event $e): void
{
    $config = $this->config();

    if (!empty($config['scheduled_index']['enabled'])) {
        $scheduler = $e['scheduler'];
        $at = $config['scheduled_index']['at'] ?? '* * * * *';
        $logs = $config['scheduled_index']['logs'] ?? '';
        $job = $scheduler->addFunction('Grav\Plugin\TNTSearchPlugin::indexJob', [], 'tntsearch-index');
        $job->at($at);
        $job->output($logs);
        $job->backlink('/plugins/tntsearch');
    }
}

PMORENO
15-04-2025