Hooks y recipes
Automatiza datos seed, impuestos, cache warmup y personalizaciones específicas del proyecto.
Desde 0.4.0, ps-lando incluye un mecanismo ligero de hooks para que automatices personalizaciones específicas de proyecto (datos seed, reglas de IVA, cache warm-up, etc.) sin tener que forkear la CLI.
Cómo funciona
Dos carpetas convencionales viven en la raíz de cualquier proyecto ps-lando:
| Carpeta | Cuándo se ejecuta |
|---|---|
init-scripts/ | Después de install-modules, antes del smoke test. |
post-scripts/ | Después del smoke test, antes del resumen final. |
Mete cualquier archivo *.sh ejecutable ahí. Los scripts se ejecutan en orden lexicográfico — pon prefijo 01-, 02-... para controlarlo. Los archivos no ejecutables y los que no son .sh se ignoran.
Variables de entorno inyectadas en los hooks
Cada script recibe este bundle canónico (los nombres son estables desde 0.4.0; el set de v1.0 añade las 4 entradas nuevas de abajo):
PS_LANDO_PROJECT # p. ej. my-shop
PS_LANDO_DOMAIN # p. ej. my-shop.lndo.site
PS_LANDO_ADMIN_DIR # p. ej. admin233kcmq1wuumt38aojg (aleatorizado)
PS_LANDO_ADMIN_EMAIL # p. ej. admin@example.com
PS_LANDO_PS_VERSION # p. ej. 9.1.0
PS_LANDO_PROJECT_DIR # ruta absoluta del proyecto
PS_LANDO_RECIPE_DIR # solo se setea para recipes incluidas — ruta a recipes/<name>/Nuevas en 1.0.0
PS_LANDO_THEME_NAME # p. ej. panda — nombre del tema resuelto (o "none")
PS_LANDO_PRESETS # p. ej. panda — lista separada por coma de presets resueltos ("" si ninguno)
PS_LANDO_MODULES_INSTALLED # SOLO post — número de módulos realmente instalados (p. ej. 6)
PS_LANDO_RESOLVED_PLAN_JSON # JSON del plan completo resuelto; ver fallback abajo| Variable | Fase | Ejemplo |
|---|---|---|
PS_LANDO_THEME_NAME | init + post | panda, falcon, none |
PS_LANDO_PRESETS | init + post | panda (uno), panda,custom (varios), `` (ninguno) |
PS_LANDO_MODULES_INSTALLED | solo post | 6 (se setea cuando el bucle de install termina) |
PS_LANDO_RESOLVED_PLAN_JSON | init + post | Un JSON con tema resuelto, módulos, hooks, etc. |
Fallback de 32KB para PS_LANDO_RESOLVED_PLAN_JSON
Si el JSON del plan resuelto supera 32 KB (sets grandes de módulos, metadatos de preset profundamente anidados), ps-lando lo escribe a un archivo temporal cerca de .pslando-cache.json y expone la ruta con un @ por delante:
# Inline (default — bajo 32 KB)
PS_LANDO_RESOLVED_PLAN_JSON='{"theme":{"name":"panda",...}}'
# File fallback (más de 32 KB)
PS_LANDO_RESOLVED_PLAN_JSON='@/ruta/abs/.pslando/resolved-plan-XXXX.json'Los hooks deberían detectar ambas formas:
#!/usr/bin/env bash
set -eu
if [[ "$PS_LANDO_RESOLVED_PLAN_JSON" == @* ]]; then
plan="$(cat "${PS_LANDO_RESOLVED_PLAN_JSON#@}")"
else
plan="$PS_LANDO_RESOLVED_PLAN_JSON"
fi
theme=$(echo "$plan" | jq -r .theme.name)
echo "Tema resuelto: $theme"Por defecto, si un script falla la CLI loguea un warning y continúa. Pasa --on-hook-failure fail para abortar al primer fallo.
Recipes incluidas
ps-lando viene con 6 recipes listas. Descúbrelas con:
ps-lando hooks list| Recipe | Fase | Requiere | Qué hace |
|---|---|---|---|
demo-catalog-10 | init | panda | 10 productos demo en una categoría "Demo" con imágenes de picsum.photos. |
demo-customer-with-orders | init | — | Un cliente demo + dirección de España + 3 pedidos en estados distintos. |
demo-cms-pages | init | — | Páginas CMS Sobre / Contacto / Términos en ES + EN. |
spain-taxes | init | — | Grupos de reglas de IVA español 21% / 10% / 4%; país por defecto ES + EUR. |
clean-seed | init | — | Borra los datos demo nativos de PS (productos 1-9, clientes demo, imágenes). |
cache-warmup | post | — | Pega front + BO + categoría + carrito + contacto con curl para precalentar la cache. |
Mira el Catálogo de recipes para el detalle por recipe (tablas tocadas, idempotencia, compatibilidad por versión).
Ejecutar recipes
Tres formas de aplicar una recipe:
# 1. En tiempo de create — multiselect interactivo después de los prompts de locale
ps-lando create
# 2. En tiempo de create — no interactivo, eligiendo por nombre
ps-lando create -y --recipes spain-taxes,demo-cms-pages
# 3. En un sandbox existente, una a una
cd my-shop
ps-lando hooks run spain-taxes
ps-lando hooks run demo-cms-pagesEl comando hooks
Cuatro subcomandos:
| Subcomando | Qué hace |
|---|---|
ps-lando hooks list | Lista los scripts descubiertos en init-scripts/ + post-scripts/ y todas las recipes incluidas. |
ps-lando hooks run <name> | Ejecuta una recipe incluida por nombre (resuelve a recipes/<name>/run.sh). |
ps-lando hooks run-all | Ejecuta cada script ejecutable en init-scripts/ y luego post-scripts/. Útil después de db reset si quieres re-seedear. |
ps-lando hooks install <name> | Copia una recipe incluida en el init-scripts/ de tu proyecto (o post-scripts/ si su fase es post) para que cada create nuevo la aplique automáticamente. |
Ejemplo — instalar la recipe de IVA español como hook local del proyecto:
ps-lando hooks install spain-taxes
# Crea: init-scripts/50-spain-taxes/run.sh
ps-lando hooks install spain-taxes --prefix 10
# Crea: init-scripts/10-spain-taxes/run.sh — se ejecuta antesPolítica de fallo
ps-lando create --on-hook-failure fail| Valor | Comportamiento |
|---|---|
continue (por defecto) | Loguea un warning, sigue ejecutando el resto del pipeline. |
fail | Aborta create al primer hook fallido. |
Escribir tu propia recipe
Cualquier *.sh ejecutable en init-scripts/ o post-scripts/ se recoge automáticamente. Ejemplo — seedear un grupo de empleados personalizado, gateado al preset panda:
# init-scripts/10-custom-group.sh
#!/usr/bin/env bash
set -eu
cd "$PS_LANDO_PROJECT_DIR"
# Salta si el preset panda no está activo — mantiene el hook seguro entre temas.
case ",$PS_LANDO_PRESETS," in
*,panda,*) ;;
*) echo "preset panda no activo — saltando"; exit 0 ;;
esac
echo "Tema: $PS_LANDO_THEME_NAME"
lando ssh -s appserver -c "mysql -hdatabase -ulamp -plamp lamp" <<SQL
INSERT IGNORE INTO ps_group
(reduction, price_display_method, show_prices, date_add, date_upd)
VALUES
(0, 0, 1, NOW(), NOW());
SQLO en un hook de post-scripts/, loguea cuántos módulos quedaron instalados:
# post-scripts/99-summary.sh
#!/usr/bin/env bash
set -eu
echo "Sandbox '$PS_LANDO_PROJECT' listo: theme=$PS_LANDO_THEME_NAME presets=$PS_LANDO_PRESETS modules=$PS_LANDO_MODULES_INSTALLED"No te olvides del bit de ejecutable:
chmod +x init-scripts/10-custom-group.shAhora se ejecutará en cada ps-lando create desde este directorio.
Usa here-docs estilo landoMysql (pipe SQL vía stdin) para evitar el infierno de comillas anidadas de lando ssh -c 'mysql ... -e "..."'. Mira las recipes incluidas en el directorio recipes/ del paquete npm para ejemplos que funcionan.