Motor Twig

MageObsidian incluye un motor de plantillas Twig que corre junto al .phtml nativo de Magento. Viene incluido por defecto con la instalación de los componentes —no tienes que activarlo. Se entrega como su propio módulo, así que puedes apagarlo sin afectar nada más.

Incluido por defecto, nunca obligatorio, totalmente retrocompatible. Twig viene con la instalación pero nada te obliga —ni a ti ni a módulos/temas de terceros— a usarlo: .phtml sigue funcionando intacto, y adoptar Twig nunca es una migración. .twig y .phtml coexisten en el mismo tema, el fallback de temas funciona idéntico para ambos. Puedes escribir .twig una plantilla a la vez, solo .phtml, o deshabilitar el motor por completo.

---

Por Qué Twig

Twig se posiciona con honestidad como una mejora de experiencia de desarrollo para el shell de plantilla del lado servidor —no como una feature de rendimiento de front. La página que llega al navegador es idéntica tanto si el shell fue un .phtml como un .twig; ambos compilan a PHP y corren en el servidor.

Lo que te aporta Twig sobre el .phtml crudo:

• Auto-escaping de HTML por defecto —la principal ganancia de seguridad. La salida se escapa salvo que la marques explícitamente como segura.
• Herencia de plantillas limpia ({% extends %}, {% block %}, {% include %}) con la sintaxis familiar de Twig.
• Una superficie restringida —las plantillas expresan presentación, no PHP arbitrario.
• Soporte de IDE de primera clase para el lenguaje Twig.

El rendimiento de front sigue viniendo de la arquitectura de islas Vue, que una plantilla .twig dirige exactamente igual que un .phtml (mediante el helper render_vue).

---

Cómo Coexiste Con phtml

Magento despacha una plantilla a un motor según su extensión de archivo (Magento\Framework\View\Element\Template::fetchView). El motor nativo está registrado para phtml; este módulo registra una entrada más para twig:

• Un bloque cuyo template="…​.twig" lo renderiza Twig.
• Un bloque cuyo template="…​.phtml" sigue usando el motor PHP nativo.
• El mapa engines es un argumento de tipo array que se fusiona entre módulos, así que esto solo añade twig —nunca reemplaza phtml.

El fallback de temas no cambia: Magento resuelve una plantilla por ruta, agnóstico a su extensión, así que un tema hijo sobrescribe el .twig de un padre exactamente como sobrescribe un .phtml.

---

Instalación

Nada que instalar. El módulo mage-obsidian/module-modern-frontend-twig es una dependencia de mage-obsidian/component-modern-frontend, así que composer require mage-obsidian/component-modern-frontend (la instalación estándar) ya lo incluye. Arrastra consigo twig/twig ^3.12.

Deshabilitar Twig

Twig es un módulo normal de Magento, así que deshabilitarlo es una sola línea —.phtml sigue funcionando exactamente igual:

bin/magento module:disable MageObsidian_ModernFrontendTwig
bin/magento setup:upgrade

Tras esto, la extensión .twig deja de estar registrada como motor. Vuélvelo a activar cuando quieras con bin/magento module:enable MageObsidian_ModernFrontendTwig. No hay feature flag —el estado habilitado del módulo es el interruptor.

---

Una Primera Plantilla

Una plantilla .twig se renderiza dentro del contexto de su bloque de Magento. A diferencia de .phtml, no hay un $this implícito; el bloque se expone como la variable block:

{# view/frontend/templates/example.twig #}
<section class="example">
    <h1>{{ block.getTitle() }}</h1>

    {# Monta una isla Vue, exactamente como el renderVueComponent de phtml #}
    {{ render_vue('Acme_Catalog::ProductCard', { id: block.getProductId() }) }}
</section>

Cablealo desde el layout con cualquier bloque —para los helpers de MageObsidian (render_vue, hero_icon, …) usa un bloque que extienda MageObsidian\ModernFrontend\Block\Template:

<referenceContainer name="content">
    <block class="MageObsidian\ModernFrontend\Block\Template"
           name="acme.example"
           template="Acme_Catalog::example.twig"/>
</referenceContainer>

---

Caché

Twig compila cada plantilla a una clase PHP la primera vez que se renderiza. Esas clases son un tipo de caché real de Magento, Twig Templates (twig_templates), así que aparecen en bin/magento cache:status y en la grilla de Cache Management del admin junto a todos los demás:

bin/magento cache:clean twig_templates   # reconstruir las plantillas compiladas
bin/magento cache:flush                  # las incluye, como a cualquier otro tipo
bin/magento cache:disable twig_templates # compilar en cada request

Deshabilitar el tipo es la forma soportada de depurar una plantilla que parece trabada: no se escribe nada en disco y cada request recompila. Con esto activo la respuesta es notoriamente más lenta.

No deberías tener que limpiar esta caché después de un deploy. Las clases compiladas viven en un directorio identificado por el conjunto de paquetes instalados, así que un composer install o composer update arranca con un espacio limpio y los archivos del build anterior se podan. Las plantillas editadas en el lugar se detectan por su fecha de modificación. Ambos mecanismos hacen falta: Composer conserva las fechas empaquetadas, así que un paquete instalado hoy puede traer archivos fechados semanas atrás — más viejos que la caché construida con su versión anterior.

En modo developer {{ dump() }} está disponible y una variable indefinida lanza un error (strict_variables) en lugar de renderizarse como cadena vacía. El auto-escaping de HTML siempre está activo, en todos los modos.

---

Próximos Pasos

• Helpers y Filtros — la referencia completa de funciones Twig de MageObsidian y filtros de escape.
• Islas Vue — cómo render_vue monta componentes.