Migra los helpers de font-size, gap y espaciado juntos

Usa wp pom migrate-helpers para actualizar los helpers heredados de font-size, espaciadores, margen y padding en una sola pasada. Esta guía es para propietarios de sitios y desarrolladores que ejecutan WP-CLI. Requiere el POM Theme actualizado, acceso a la línea de comandos del sitio de destino y un directorio de copia de seguridad privado para la aplicación.

Los comandos individuales migrate-font-size-helpers, migrate-gap-helpers y migrate-spacing-helpers usan el mismo motor y las mismas opciones, limitados a su familia con nombre. Los cuatro comandos ejecutan por defecto una simulación (dry run). Los comandos de font-size y gap también requieren --apply y --backup-dir para escribir.

Previsualiza y aplica

1. Mantén una copia de seguridad coordinada de la base de datos y de los ajustes gestionados. Verifica la actualización en staging y pausa la edición y las importaciones durante la aplicación. No ejecutes una migración anterior de forma simultánea con el nuevo comando.

2. Previsualiza el sitio seleccionado:

   wp pom migrate-helpers --url=https://example.test --dry-run

3. Revisa el resumen y cualquier aviso de revisión manual. Añade --verbose para imprimir cada ubicación propuesta. El comportamiento por defecto informa del progreso incluso cuando no se encuentran reemplazos.

4. Proporciona un directorio existente con permisos de escritura fuera de WordPress, accesible solo para la cuenta que ejecuta WP-CLI (modo 0700). Aplica el alcance revisado:

   wp pom migrate-helpers --url=https://example.test --apply --backup-dir=/private/migrations

5. Conserva la copia de seguridad privada helpers-<run-id>/plan.jsonl hasta que finalice la verificación. El comando guarda los valores exactos originales y propuestos antes de su primera escritura de contenido. Un fallo en la copia de seguridad impide la aplicación.

6. Verifica que no queden reemplazos seguros:

   wp pom migrate-helpers --url=https://example.test --dry-run --fail-on-remaining

7. Inspecciona páginas representativas, plantillas de feed/archivo/artículo individual, tipografía fija, bloques Gap y espaciado responsivo en el editor y en el frontend. Revisa por separado cualquier valor omitido.

Progreso y rendimiento

Se identifica cada sitio, almacén de contenido, escaneo de archivos gestionados, fase de copia de seguridad y de aplicación. Una barra de progreso se actualiza aproximadamente cada dos segundos mientras el trabajo avanza. Los porcentajes de la base de datos describen el progreso a través de un rango fijo de IDs, no un porcentaje de filas: los IDs eliminados pueden hacer que el porcentaje salte. El recuento separado de inspeccionados informa de las filas reales. Los archivos gestionados usan una barra indeterminada y un recuento de archivos, evitando un segundo escaneo del directorio. Las barras de copia de seguridad y aplicación tienen totales conocidos. La salida también es legible cuando se redirige a un registro.

El comando obtiene valores completos por lotes en lugar de consultar cada fila de metadatos individualmente. --batch-size acepta de 25 a 2000 filas (250 por defecto); los valores de gran tamaño reducen el tamaño efectivo del lote. Las filas añadidas más allá del ID superior inicial de un almacén se dejan para una ejecución posterior. Las filas/archivos sobredimensionados se informan antes de la aplicación. El progreso no puede avanzar mientras una operación de base de datos o del sistema de archivos esté bloqueada; la fase con nombre identifica el trabajo en curso. --debug=pom-migrate-helpers imprime las operaciones antes de que comiencen cuando se necesita un diagnóstico más detallado.

Alcance y preservación

Por defecto, --url selecciona un sitio de tema POM. Todos los tipos de contenido y estados, revisiones, extractos, metadatos estándar, opciones no transitorias, descripciones de términos, comentarios y ajustes/plantillas gestionados de POM Framework se inspeccionan una vez para las familias seleccionadas. El comando no reescribe el código fuente de temas/plugins, las subidas, tablas personalizadas de terceros ni plantillas externas. Se excluyen las copias de seguridad, los archivos temporales de migración, los directorios de caché y los recursos gestionados minificados.

• --network procesa los sitios de tema POM de la red actual; se omiten otros temas.
• --include-shared añade explícitamente metadatos de usuario compartidos, opciones de la red actual y plantillas gestionadas compartidas. Estos pueden afectar a otros sitios y temas.
• --include-network-options añade opciones de la red actual sin añadir metadatos de usuario ni archivos compartidos. Los metadatos propios de los sitios seleccionados ya están incluidos.
• Los datos compartidos no se incluyen automáticamente mediante --network ni --url.

Los valores escalares/de matrices serializados, JSON, payloads base64 y codificados en URL admitidos, y las cadenas PHP gestionadas se procesan sin evaluar PHP ni instanciar objetos serializados. Los objetos/referencias no admitidos, el espaciado ambiguo y el código no resuelto se dejan sin cambios y se informan. Un valor omitido se conserva en su totalidad, incluidos los helpers convertibles que contenga. Se conservan los valores numéricos arbitrarios, las fechas de las entradas, los nombres de shortcodes, las declaraciones en línea de margen/padding y los atributos de espaciado de Gutenberg. Los bloques Legacy Gap son la conversión explícita de atributos de bloque.

Los mapas de reemplazo exactos se documentan en font sizes, gaps y margin/padding.

Comportamiento de la caché

Los cuatro comandos dejan las cachés y los recursos generados sin cambios. No vacían las cachés de objetos, no eliminan entradas de caché individuales, no invalidan OPcache, no eliminan los esqueletos de traducción ni los transitorios de estilos editables, no purgan cachés de páginas/CDN ni regeneran recursos. Las escrituras conservan las fechas de contenido almacenadas y omiten los hooks de guardado de contenido.

Por lo tanto, las respuestas en caché existentes o el bytecode PHP pueden seguir mostrando el contenido anterior hasta que surta efecto el ciclo de vida normal de la caché del sitio o una actualización gestionada por separado. Una migración correcta confirma los valores almacenados, no que cada respuesta en caché del frontend ya los refleje. El mantenimiento de la caché y de los recursos sigue siendo una operación separada del propietario del sitio.

Ejecuciones repetidas e interrupciones

Los reemplazos completados se conservan. Puedes ejecutar el comando unificado después de una migración anterior de font-size, gap o espaciado parcialmente completada; lee los valores almacenados actuales y cambia solo los helpers heredados restantes. No restaura copias de seguridad antiguas ni repite conversiones de los tokens rem actuales. Una simulación interrumpida no ha realizado cambios de contenido.

La aplicación no es una transacción que cubra todo el sitio. Ante un fallo de escritura, las ubicaciones anteriores correctas siguen migradas y sus originales exactos permanecen en la copia de seguridad de esa ejecución. Resuelve la causa indicada y vuelve a ejecutar el mismo comando; no hay un checkpoint ni un ID de reinicio que proporcionar. Conserva las copias de seguridad de cada ejecución si puede ser necesaria una reversión completa. El comando comprueba los valores originales antes de escribir y se detiene ante cambios concurrentes detectados. Las aplicaciones concurrentes del nuevo motor se rechazan inmediatamente.

Una barra de progreso detenida va seguida de un registro Migration failed en la salida normal, así como del error en la salida de error estándar. El registro incluye la excepción, la ubicación actual y el número de ubicaciones aplicadas sin imprimir el contenido almacenado. Un fallo durante la comprobación previa ha aplicado cero ubicaciones. Conserva la salida completa al diagnosticar una ejecución fallida; la etiqueta de código de salida de un lanzador por sí sola no identifica la causa.

Una lista de clases de espaciado que mezcle clases de píxeles antiguas con nombres compactos como mt-1 se informa para su revisión. Usa --keep-mixed-classes solo si los nombres compactos ya tienen su significado rem previsto. Alternativamente, --remove-compact-classes=mt-1,pt-1 elimina los nombres compactos exactos revisados solo de las listas reconocidas que aún contienen un helper de espaciado heredado. Las listas completamente migradas permanecen sin cambios en ejecuciones posteriores.

Los errores de lectura/escritura, las filas/archivos sobredimensionados y el PHP reescrito no válido detienen o bloquean la aplicación. Los valores no admitidos aparecen bajo manual_review y permanecen sin cambios mientras las ubicaciones seguras pueden continuar. --fail-on-remaining hace que una simulación falle cuando quedan reemplazos seguros; los avisos de revisión manual siguen siendo informativos y deben revisarse de forma independiente. Los valores superiores a 16 MiB y el anidamiento más allá de 16 niveles requieren un manejo separado.