Skip to content

ecomyseo/prestashop_skills / prestashop-example-modules

prestashop-example-modules

Verified

Conocimiento extraido del repositorio oficial PrestaShop/example-modules (clonado en <herramientas>/example-modules) y contrastado con las fuentes del nucleo en <herramientas>/prestashop. Extender el formulario de producto del back-office en la pagina clasica (V1) y en la nueva (V2), hooks por demo, formularios Symfony, y que se puede hacer SIN src/ ni composer ni services.yml. Usar al desarrollar o depurar modulos de PrestaShop 1.7 / 8.x / 9.x.

prestashop-example-modules

Conocimiento extraido del repositorio oficial https://github.com/PrestaShop/example-modules (clon local: <herramientas>/example-modules), contrastado en algunos puntos con el nucleo <herramientas>/prestashop/9.1.1/.

Uso previsto: material de CONSULTA para APIs, nombres de hooks y detalles tecnicos. No es autoridad sobre estructura de carpetas ni convenciones del proyecto. Si algo de aqui contradice el CLAUDE.md del proyecto, gana el CLAUDE.md.

Aviso de version transversal: la MAYORIA de las demos del repo oficial son solo PS 9.x. Los README estan desactualizados en varios modulos; la fuente fiable es siempre $this->ps_versions_compliancy en el fichero principal, no el README ni el config.xml (que casi nunca declara version).


1. Tabla resumen

DemoPara que sirveHooksVersion PSLegacy puro?
demoproductformCampos y PESTANAS nuevas en el formulario de producto V2 + formulario de combinacion; guardado por CQRS y por hookactionProductFormBuilderModifier, actionCombinationFormFormBuilderModifier, actionAfterUpdateCombinationFormFormHandler, displayAdminProductsExtra9.0.0–9.99.99 (demoproductform.php:45)NO (src/, composer, services.yml)
demoproductextracontentPestanas de contenido extra en la ficha de producto del FRONTdisplayProductExtraContent1.7.0–9.99.99 (demoproductextracontent.php:34)SI
demoextrafieldAPI nativa de extra properties (PS 9.2): campos custom en producto/categoria/cliente/direccion/CMS, con form BO, grid, API y front. Ademas via manual con hooks genericos sobre el form CMSdisplayProductAdditionalInfo, displayFooterProduct, displayCartExtraProductInfo, displayHeaderCategory, displayCustomerAccountTop, actionCmsPageFormBuilderModifier, actionCmsPageFormDataProviderData, actionAfterCreate/UpdateCmsPageFormHandler, displayCMSDisputeInformation9.2.0–9.9.99 (demoextrafield.php:52)SI
demoseoStructured data JSON-LD + meta title/description desde un solo hookactionFrontControllerSetVariables>=9.2.0 (demoseo.php:36); el hook existe desde 1.7.5, los structured_data desde 9.2SI (ni config.xml trae)
demosymfonyformCatalogo vivo de TODOS los form types de PrestaShop, 3 paginas BO, multiples formularios por paginaNinguno registrado; indirectos via Core\Form\Handler con hookName DemoConfiguration9.0.0+ (demosymfonyform.php:44)NO
demosymfonyformsimpleEsqueleto minimo de pagina de configuracion Symfony (6 ficheros) con validacion y erroresNinguno9.0.0+ (demosymfonyformsimple.php:26)NO
demoextendsymfonyform1Campo booleano en el form de Cliente + columna toggle y filtro en el grid; ObjectModel + repositorio DBALactionCustomerGridDefinitionModifier, actionCustomerGridQueryBuilderModifier, actionCustomerFormBuilderModifier, actionAfterCreate/UpdateCustomerFormHandler9.0.0–9.99.99 (demoextendsymfonyform1.php:63-66)NO
demoextendsymfonyform2Subida de imagen en el form de Proveedor + bloque HTML custom; Doctrine ORMactionSupplierFormBuilderModifier, actionAfterCreate/UpdateSupplierFormHandler9.0.0–9.99.99 (demoextendsymfonyform2.php:51)NO
demoextendsymfonyform3Igual que #1 pero con CQRS propio (#[AsCommandHandler] / #[AsQueryHandler])Los 5 de Customer9.0.0–9.99.99 (demoextendsymfonyform3.php:65-68)NO
demoformdataprovidersModificar los DATOS del formulario de producto V2 desde un modulo legacy puroactionProductFormDataProviderData, actionProductFormDataProviderDefaultData8.0.0–9.99.99 (demoformdataproviders.php:34)SI
demomultistoreformCRUD Symfony multitienda completo (grid, form, config multistore)displayFooterBefore; indirectos actionConfigurationFormForm/Save, actionContentBlockFormDataProvider*9.0.0+ real (demomultistoreform.php:48); README dice 1.7.8-8.1 OBSOLETONO
demoextendtemplates5 vias de extender plantillas Twig del BO sin tocar el core + decorador de controlador + EventSubscriberNinguno9.1.0+ (demoextendtemplates.php:34)Overrides Twig si; decorador/subscriber no
democontrollertabs5 escenarios de controlador Symfony + Tab de menu ($this->tabs vs Tab manual) + permisosNinguno9.0.0+ (democontrollertabs.php:39)NO
demo_gridGrid propio completo desde ceroNinguno; su grid EMITE action<GridId>Grid*Modifier9.0.0+ (demo_grid.php:34)NO
demoextendgridAnadir accion de fila al grid de Pedidos + JS AJAXactionOrderGridDefinitionModifier, actionAdminControllerSetMedia9.0.0+ real (demoextendgrid.php:42); README dice 1.7.7-8.1 OBSOLETOHook si; la ruta de la accion no
demofiltermodulesFiltrar que modulos se ejecutan en un hook del frontNinguno; tag core.hook_module_exec_filter8.2.1+ (demofiltermodules.php:79)NO
demomoduleroutesURLs amigables propias en el FRONTmoduleRoutes8.0.0–9.99.99 (demomoduleroutes.php:30)SI
demojsroutingComponente JS Router del BO para generar URLs Symfony desde JSNinguno; usa $tabs9.0.0+ (demojsrouting.php:47)NO (pero el Router SI es usable en legacy)
democonsolecommandComando bin/console propioNinguno; tag console.command9.0.0+ (democonsolecommand.php:34)NO
demodoctrineCRUD completo con Doctrine ORM + entidad lang + grid + form identifiable objectdisplayHome9.0.0+ (demodoctrine.php:40)NO
demooverrideobjectmodelAnadir un campo a Manufacturer por override + ALTER TABLE. El propio README lo marca como antipatronNinguno (Installer.php:60 array vacio)9.0.0+ (demooverrideobjectmodel.php:38); el mecanismo es identico en 1.7/8/9Practicamente si
api_moduleExponer recursos propios en la nueva API (API Platform)Ninguno; atributos #[ApiResource] + tags de servicio9.0.0–9.99.99 (api_module.php:42)NO
dashexampleIntegracion con el Dashboard Symfony de PS 9.2. Modulo "Symfony-light": renderiza Twig sin src/ ni services.ymldisplayAdminDashboardZoneOne/Two/Three, ...Top, ...Bottom, ...Toolbar9.2.0+ (dashexample.php:46) + feature flag dashboardSI
demovieworderhooksCatalogo de hooks de la pagina "Ver pedido": PESTANA (TabLink+TabContent), zonas, botones de la barra de acciones, preview del listadodisplayAdminOrderTabLink, displayAdminOrderTabContent, displayAdminOrderMain, ...MainBottom, ...Side, ...SideBottom, displayAdminOrder, displayAdminOrderTop, displayAdminOrderCreateExtraButtons, displayOrderPreview, actionGetAdminOrderButtons9.0.0–9.99.99 (demovieworderhooks.php:54)Los hooks si; Doctrine/servicios no
demowsextendRecurso propio en el Webservice clasico /apiaddWebserviceResources1.7.8+ (README; no declara compliancy)SI
example_module_mailthemeTemas de email: anadir tema, anadir/reemplazar layouts, inyectar variables, transformar el HTML finalactionListMailThemes, actionBuildMailLayoutVariables, actionGetMailLayoutTransformations9.0.0–9.99.99 (example_module_mailtheme.php:60)Hooks si; la pagina de config Symfony no

2. Formulario de producto

2.0 Regla de oro: hay DOS paginas de producto

  • V1 (clasica): AdminProductsController + HelperForm, PS 1.7 / 8.0. Del catalogo oficial, el UNICO hook que funciona ahi es displayAdminProductsExtra.
  • V2 (nueva): formulario Symfony (EditProductFormType), PS 8.1+ y 9.x. Aqui viven actionProductFormBuilderModifier, actionProductFormDataProvider*, extra properties, CQRS.

Ningun demo del repo cubre la V1 mas alla de displayAdminProductsExtra. Si el modulo debe soportar 8.0 clasica y 9.x, la unica via portable es displayAdminProductsExtra (solo lectura, cae en la pestana "Modulos").

2.1 V1 (clasica) y tambien V2: displayAdminProductsExtra

Hook de display normal. Recibe $params['id_product'], DEVUELVE un string HTML. En V2 el HTML se pinta dentro de la pestana Modulos. Es de SOLO LECTURA: no participa del guardado.

// version Twig del demo (demoproductform.php:105-116)
public function hookDisplayAdminProductsExtra(array $params): string
{
    $customProduct = new CustomProduct($params['id_product']);
    /** @var \Twig\Environment $twig */
    $twig = $this->get('twig');
    return $twig->render('@Modules/demoproductform/views/templates/admin/extra_module.html.twig', [
        'customProduct' => $customProduct,
    ]);
}

// version LEGACY equivalente (Smarty) - valida en V1 y V2
public function hookDisplayAdminProductsExtra(array $params)
{
    $this->context->smarty->assign(['id_product' => (int) $params['id_product']]);
    return $this->display(__FILE__, 'views/templates/admin/mi_panel.tpl');
}

Evidencia: demoproductform/demoproductform.php:97-116, views/templates/admin/extra_module.html.twig:20-31.

2.2 V2 — Anadir un CAMPO dentro de una pestana existente

Hook actionProductFormBuilderModifier. Recibe:

  • $params['form_builder'] — FormBuilderInterface raiz del formulario de producto.
  • $params['id'] — id del producto. Ausente/null en creacion: comprobar siempre.

Se baja a la pestana con ->get('<pestana>') y se posiciona con el servicio del core form.form_builder_modifier (metodo addAfter). Con ->add() a secas el campo va al final.

// Version del demo (con servicio propio)
public function hookActionProductFormBuilderModifier(array $params): void
{
    $modifier  = $this->get(ProductFormModifier::class);
    $productId = isset($params['id']) ? new ProductId((int) $params['id']) : null;
    $modifier->modify($productId, $params['form_builder']);
}

// Dentro del modifier (ProductFormModifier.php:58-83)
$descriptionTab = $productFormBuilder->get('description');
$this->formBuilderModifier->addAfter(
    $descriptionTab,
    'description',                  // campo ancla existente
    'demo_module_custom_field',     // nombre nuevo
    TextType::class,
    [
        'label'       => $this->translator->trans('Demo custom field', [], 'Modules.Demoproductform.Admin'),
        'label_attr'  => ['title' => 'h2', 'class' => 'text-info'],
        'data'        => $customProduct->custom_field,   // valor precargado
        'empty_data'  => '',
        'form_theme'  => '@PrestaShop/Admin/TwigTemplateForm/prestashop_ui_kit_base.html.twig',
    ]
);

Version LEGACY (sin src/, sin composer, sin services.yml) — el servicio del core se pide por su id string:

public function hookActionProductFormBuilderModifier(array $params)
{
    $builder = $params['form_builder'];
    $value   = isset($params['id']) ? $this->leerValor((int) $params['id']) : '';

    $this->get('form.form_builder_modifier')->addAfter(
        $builder->get('description'),
        'description',
        'ecom_mi_campo',
        \Symfony\Component\Form\Extension\Core\Type\TextType::class,
        [
            'label'      => 'Mi campo',
            'required'   => false,
            'data'       => $value,
            'empty_data' => '',
            'form_theme' => '@PrestaShop/Admin/TwigTemplateForm/prestashop_ui_kit_base.html.twig',
        ]
    );
}

Evidencia: demoproductform.php:88-95, src/Form/Modifier/ProductFormModifier.php:58-83, config/services.yml:3-7.

2.3 V2 — Anadir una PESTANA nueva completa

Una pestana no es una API especial: es un hijo directo del builder RAIZ cuyo tipo es un FormType propio. El titulo de la pestana es la opcion 'label' declarada en configureOptions() del FormType.

// Posiciona la pestana justo despues de "Precios" (ProductFormModifier.php:85-109)
$this->formBuilderModifier->addAfter(
    $productFormBuilder,      // BUILDER RAIZ, no un sub-builder
    'pricing',                // pestana ancla
    'custom_tab',             // nombre = clave en $formData al guardar
    CustomTabType::class,
    ['data' => ['custom_price' => $customProduct->custom_price]]
);
// Segunda pestana, anclada a la primera
$this->formBuilderModifier->addAfter(
    $productFormBuilder, 'custom_tab', 'custom_tab_content', CustomTabContentType::class,
    ['data' => ['custom_price' => $customProduct->custom_price]]
);

// El TITULO de la pestana sale de aqui (CustomTabType.php:76-85)
public function configureOptions(OptionsResolver $resolver)
{
    parent::configureOptions($resolver);
    $resolver->setDefaults(['label' => $this->trans('Customization', 'Modules.Demoproductform.Admin')]);
}

Version LEGACY: un class MiPestanaType extends \Symfony\Component\Form\AbstractType sin dependencias de constructor en classes/ (namespace global, cargado con require_once) funciona: Symfony instancia solo cualquier AbstractType con constructor vacio. El tag form.type de services.yml solo hace falta cuando el type tiene argumentos que inyectar. Se pierde TranslatorAwareType (exige $locales): traducir con Context::getContext()->getTranslator()->trans().

2.4 V2 — Pestana de solo lectura / dashboard: form theme propio

Un FormType puede declarar 'form_theme' apuntando a un twig del modulo. Ese twig extiende el tema base del UI-kit y sobreescribe el bloque <block_prefix>_widget, donde block_prefix es el snake_case del nombre de la clase sin el sufijo Type (CustomTabContentType -> custom_tab_content).

public function buildView(FormView $view, FormInterface $form, array $options)
{
    parent::buildView($view, $form, $options);
    $view->vars['custom_price'] = $options['data']['custom_price'] ?? null;
}
public function configureOptions(OptionsResolver $resolver)
{
    parent::configureOptions($resolver);
    $resolver->setDefaults([
        'label'      => $this->trans('Customization content', 'Modules.Demoproductform.Admin'),
        'form_theme' => '@Modules/demoproductform/views/templates/admin/FormTheme/product_tab_content_form_theme.html.twig',
    ]);
}
{% extends '@PrestaShop/Admin/TwigTemplateForm/prestashop_ui_kit_base.html.twig' %}
{% block custom_tab_content_widget %}
  <div class="alert alert-info">{{ 'This is your custom tab content'|trans({}, 'Modules.Demoproductform.Admin') }}</div>
  <p>{{ 'Custom price'|trans({}, 'Modules.Demoproductform.Admin') }}: {{ custom_price }}</p>
{% endblock %}

Evidencia: src/Form/Type/CustomTabContentType.php:32-51, views/templates/admin/FormTheme/product_tab_content_form_theme.html.twig:20-30. @Modules resuelve la carpeta del modulo, asi que el twig puede vivir en views/ sin src/.

2.5 V2 — Boton / enlace en el footer del formulario

$footer = $productFormBuilder->get('footer');
$footer->add('forms_info', IconButtonType::class, [
    'label' => $this->translator->trans('Open supplier website'),
    'type'  => 'link',
    'attr'  => ['href' => 'http://www.prestashop.com', 'target' => '_blank'],
]);

IconButtonType = PrestaShopBundle\Form\Admin\Type\IconButtonType. Evidencia: src/Form/Modifier/ProductFormModifier.php:111-122.

2.6 V2 — Cambiar solo los VALORES (sin anadir campos): FormDataProvider*

El patron mas valioso para arquitectura legacy. demoformdataproviders es un modulo entero de 4 ficheros (config.xml, el .php, index.php, README.md) que modifica el formulario de producto V2. Sin src/, sin composer.json, sin config/.

class DemoFormDataProviders extends Module
{
    public function install()
    {
        if (!parent::install()) { return false; }
        return $this->registerHook('actionProductFormDataProviderData')
            && $this->registerHook('actionProductFormDataProviderDefaultData');
    }

    // Se dispara al construir el formulario SIN id (alta)
    public function hookActionProductFormDataProviderDefaultData(array $params): void
    {
        $params['data']['details']['references']['mpn'] = 'NEWMPNPREFIX_';
    }

    // Se dispara al construir el formulario CON id (edicion)
    public function hookActionProductFormDataProviderData(array $params): void
    {
        $actual = $params['data']['details']['references']['mpn'];
        if (substr($actual, 0, 13) !== 'NEWMPNPREFIX_') {
            $params['data']['details']['references']['mpn'] = 'NEWMPNPREFIX_' . $actual;
        }
    }
}

Evidencia: demoformdataproviders.php:45-53, 66-82.

Por que funciona la mutacion aunque la firma no lleve &: el nucleo mete data y options en el array de parametros como referencias; al copiar el array, esos elementos siguen siendo referencias. id NO es referencia. Hay que ESCRIBIR en $params['data'][...]; reasignar $params entero no sirve.

// PrestaShop 9.1.1, src/Core/Form/IdentifiableObject/Builder/FormBuilder.php:119-127
$this->hookDispatcher->dispatchWithParameters(
    'action' . $this->camelize($this->getFormName()) . 'FormDataProviderData',
    ['data' => &$data, 'id' => $id, 'options' => &$options]
);

2.7 Como se calcula el nombre de estos hooks (regla general)

action + camelize(getBlockPrefix() del FormType RAIZ) + FormDataProviderData | FormDataProviderDefaultData | FormBuilderModifier.

Mapa real del producto V2 en PS 9.1:

FormType raizblock prefixHooks
EditProductFormTypeproductactionProductFormDataProviderData, actionProductFormBuilderModifier
CreateProductFormType (modal de alta)create_productactionCreateProductFormDataProviderDefaultData

Consecuencia: hookActionProductFormDataProviderDefaultData del demo NO se dispara nunca en la practica en PS 9.1 (el nucleo solo llama getFormFor() sobre el builder de edicion). El prefijo en un producto nuevo lo pone en realidad el hook ...Data tras el redirect. El README del demo es enganoso.

Evidencia nucleo: FormBuilder.php:121, 164-172; EditProductFormType.php:181-183; CreateProductFormType.php:69-72; form_builder.yml:218-232; ProductController.php:398, 467.

2.8 Anclas conocidas para addAfter

// PRODUCTO (builder raiz)
'description', 'pricing', 'stock', 'shipping', 'seo', 'options', 'header', 'footer'
$productFormBuilder->get('description');   // dentro: campo 'description'
$productFormBuilder->get('footer');

// COMBINACION
addAfter($combinationFormBuilder, 'references', ...);
addAfter($combinationFormBuilder, 'price_impact', ...);

// Ruta de datos util (arbol del form V2)
$params['data']['details']['references']['mpn']

Si el ancla no existe, addAfter falla: comprobar la version antes de asumir un nombre. Evidencia: ProductFormModifier.php:60, 88, 100, 113; CombinationFormModifier.php:64, 91; EditProductFormType.php:80 -> Details/DetailsType.php:54 -> Details/ReferencesType.php:41.

2.9 GUARDAR los datos — tres caminos

(a) Hooks identifiable object — no exige Symfony. Llegan DESPUES de que el core guarde, con $params['form_data'] ya validado.

// Producto (documentado como alternativa oficial en CustomProductCommandsBuilder.php:34-38)
public function hookActionBeforeUpdateProductFormHandler(array $params) { }
public function hookActionAfterUpdateProductFormHandler(array $params)
{
    $id   = (int) $params['id'];
    $data = $params['form_data'];
    // $data['description']['ecom_mi_campo'], $data['custom_tab']['custom_price'], ...
}

// Combinacion (demoproductform.php:137-152)
public function hookActionAfterUpdateCombinationFormFormHandler(array $params): void
{
    $combinationId = $params['form_data']['id'];
    $obj = new CustomCombination($combinationId);
    $obj->custom_field = $params['form_data']['demo_module_custom_field'] ?? '';
    $obj->custom_price = $params['form_data']['custom_tab']['custom_price'] ?? 0.0;
    if (empty($obj->id)) { $obj->id = $combinationId; $obj->force_id = true; $obj->add(); }
    else { $obj->update(); }
}

(b) CQRS (ProductCommandsBuilderInterface) — EXIGE services.yml. El core descubre el builder por el tag core.product_command_builder. No hay forma de registrar un tag sin services.yml.

PrestaShop\Module\DemoProductForm\CQRS\CommandBuilder\CustomProductCommandsBuilder:
    tags: ['core.product_command_builder']   # imprescindible
PrestaShop\Module\DemoProductForm\CQRS\CommandHandler\UpdateCustomProductCommandHandler:
    autoconfigure: true                       # para que #[AsCommandHandler] surta efecto
public function buildCommands(ProductId $productId, array $formData, ShopConstraint $c): array
{
    $command = null;
    if (isset($formData['description']['demo_module_custom_field'])) {
        $command = $this->getCommand($command, $productId->getValue())
            ->setCustomerField($formData['description']['demo_module_custom_field']);
    }
    if (isset($formData['custom_tab']['custom_price'])) {
        $command = $this->getCommand($command, $productId->getValue())
            ->setCustomPrice((string) $formData['custom_tab']['custom_price']);
    }
    return null !== $command ? [$command] : [];
}

Nota util: ProductFormDataHandler::create() crea el producto minimo y luego llama a update(), asi que no hace falta enganchar la creacion aparte (documentado en UpdateCustomProductCommandHandler.php:40-47). Evidencia: config/services.yml:15-22, CustomProductCommandsBuilder.php:40-62.

(c) PS 9.2+ — registerExtraProperty(): el core lo guarda TODO por ti. Ver 2.10.

2.10 V2 en PS 9.2+ — campos custom sin src/, sin composer, sin services.yml

Module::registerExtraProperty(new ExtraPropertyDefinition(...)) hace que el nucleo cree la columna SQL, el campo en el formulario Symfony, la columna del grid y la exposicion por API.

  • associatedForms: ['product'] -> el campo cae en una pestana nueva "Extra fields".
  • associatedForms: ['product:options.suppliers:before'] -> se inserta dentro de la pestana Options, seccion suppliers, antes de ella. Formato: entidad:tab.seccion:before.
  • formType acepta cualquier FormType de Symfony o de PrestaShopBundle por FQCN: por eso NO hace falta services.yml (esos tipos ya estan registrados en el contenedor del nucleo).
use PrestaShop\PrestaShop\Core\ExtraProperty\Definition\ExtraPropertyDefinition;
use PrestaShop\PrestaShop\Core\ExtraProperty\Definition\ExtraPropertyScope;
use PrestaShop\PrestaShop\Core\ExtraProperty\Definition\ExtraPropertyType;
use PrestaShopBundle\Form\Admin\Type\SwitchType;

$this->registerExtraProperty(new ExtraPropertyDefinition(
    entityName: 'product',
    propertyName: 'is_dangerous',
    type: ExtraPropertyType::BOOL,
    scope: ExtraPropertyScope::COMMON,
    defaultValue: 0,
    nullable: false,
    displayFront: true,
    associatedApis: ['/products', '/products/{productId}'],
    associatedForms: ['product:options.suppliers:before'],  // 'product' solo => pestana "Extra fields"
    associatedGrids: ['product:reference'],
    formType: SwitchType::class,
    labelWording: 'Dangerous product',
    labelDomain: 'Modules.Demoextrafield.Admin',
));

Scopes y tablas: COMMON -> <entidad>_extra; LANG -> <entidad>_extra_lang (una fila por idioma); SHOP -> por tienda. Tipos: BOOL, STRING, DATE, INT, FLOAT, JSON, HTML, CHOICE (con enumValues). Opcionales: sqlIndex (ExtraPropertySqlIndex::KEY|UNIQUE), size, required, nullable, displayFront, formOptions, constraints.

Las Constraint van en constraints, NUNCA en formOptions (este ultimo se persiste como JSON y no admite objetos).

Lectura/escritura desde PHP con el ObjectModel nativo:

$product = new Product($productId, false, $languageId); // CON langId => campos LANG como escalar
$product->extra_properties['demoextrafield']['date_last_seen'] = date('Y-m-d H:i:s');
$product->update();

Render en Smarty (regla obligatoria: el primer salto con ->, luego notacion punto, porque ObjectModel no implementa ArrayAccess):

{foreach from=$objectModel->extra_properties.demoextrafield key=fieldName item=fieldValue}
  <li><strong>{$fieldName|escape:'htmlall':'UTF-8'}:</strong> {$fieldValue|escape:'htmlall':'UTF-8'}</li>
{/foreach}
{if $product.extra_properties.demoextrafield.is_dangerous|intval} ... {/if}

Desinstalacion (el 2o argumento decide si se hace DROP de la columna):

return $this->unregisterExtraProperty(new ExtraPropertyDefinition('product', 'video_link'), false) // false = conservar datos
    && $this->unregisterExtraProperty(new ExtraPropertyDefinition('product', 'is_dangerous'), false)
    && parent::uninstall();

Evidencia: demoextrafield.php:76-95, 103-127, 186-220, 376-397, 531-569, 595-631; views/templates/hook/_extra_properties.tpl:5-28.

2.11 Ficha de producto en el FRONT: pestanas extra (1.7.0 → 9.x)

Es OBLIGATORIO devolver un array de objetos ProductExtraContent; HTML plano no funciona. La clase la autocarga el nucleo: FQCN inline, sin use, sin composer.

public function install() { return parent::install() && $this->registerHook('displayProductExtraContent'); }

public function hookDisplayProductExtraContent($params)
{
    return [
        (new PrestaShop\PrestaShop\Core\Product\ProductExtraContent())
            ->setTitle('Primera pestana')
            ->setContent($this->fetch('module:mimodulo/views/templates/front/tab1.tpl')),
    ];
}

Evidencia: demoproductextracontent.php:45-63.

2.12 Persistencia limpia: tabla propia con id espejo

Patron del demo: PK = exactamente el id_product (o id_product_attribute), force_id = true, y el modulo nunca toca product ni product_attribute.

final class CustomProduct extends \ObjectModel
{
    public $id;
    public string $custom_field = '';
    public float  $custom_price = 0.0;
    public $force_id = true;

    public static $definition = [
        'table'   => 'demoproductform_custom_product',
        'primary' => 'id',
        'fields'  => [
            'custom_field' => ['type' => self::TYPE_STRING],
            'custom_price' => ['type' => self::TYPE_FLOAT, 'validate' => 'isPrice'],
            'date_add'     => ['type' => self::TYPE_DATE, 'validate' => 'isDate'],
            'date_upd'     => ['type' => self::TYPE_DATE, 'validate' => 'isDate'],
        ],
    ];
}
// guardado
if (empty($o->id)) { $o->id = $productId; $o->force_id = true; $o->add(); }
else { $o->setFieldsToUpdate($updatedFields); $o->update(); }

Evidencia: src/Entity/CustomProduct.php:26-53, UpdateCustomProductCommandHandler.php:53-76, src/Install/install.sql:1-19.


3. Legacy vs Symfony

3.1 SE PUEDE HACER SIN src/, SIN composer.json, SIN config/services.yml

Prueba viva: demoformdataproviders, demomoduleroutes, demowsextend, demoproductextracontent, demoseo, demoextrafield y dashexample no tienen ninguno de esos ficheros (o dashexample, que tiene composer.json sin bloque autoload).

CapacidadComoEvidencia
Modificar VALORES de cualquier formulario Symfony del BOaction<BlockPrefix>FormDataProviderData / ...DefaultDatademoformdataproviders.php:66-82
ANADIR/quitar CAMPOS y PESTANAS a formularios del BO (producto V2, cliente, categoria, proveedor, CMS…)action<BlockPrefix>FormBuilderModifier + $this->get('form.form_builder_modifier')FormBuilder.php:145-157 (nucleo); demoproductform.php:88-95
PRECARGAR valores del formularioaction<Entidad>FormDataProviderData ($params['data'] llega por referencia)demoextrafield.php:731-750
PERSISTIR tras guardaractionAfterCreate<Entidad>FormHandler / actionAfterUpdate<Entidad>FormHandler ($params['id'], $params['form_data'])demoextendsymfonyform1.php:215-263
FormType propio SIN dependencias de constructorclass X extends \Symfony\Component\Form\AbstractType en classes/ con require_onceservices.yml solo hace falta si el type tiene argumentos
Form theme Twig del modulo'form_theme' => '@Modules/<modulo>/views/...'CustomTabContentType.php:32-51
Renderizar Twig en un hook del BO$this->get('twig')->render('@Modules/<mod>/views/templates/admin/x.html.twig', $vars) desde la clase Moduledashexample.php:143-149 (modulo SIN src/)
PESTANA en una pagina Symfony del BOPar display...TabLink + display...TabContent devolviendo HTML planodemovieworderhooks/views/templates/admin/tracking_link.html.twig:12-25
Columnas, filtros y acciones en grids del coreaction<GridId>GridDefinitionModifier, ...GridQueryBuilderModifier, ...GridDataModifier, ...GridFilterFormModifier, ...GridPresenterModifierdemoextendgrid.php:84-122
Inyectar CSS/JS en el BOactionAdminControllerSetMedia (+ filtrar por controller_name y action) o emitir <link>/<script> desde la salida de un hook con $this->getPathUri()demoextendgrid.php:64-79; dashexample/views/templates/admin/toolbar.html.twig:11-14
Campos custom en producto V2 + grid + API + front (PS 9.2+)registerExtraProperty()demoextrafield.php:76-95
URLs amigables en el FRONThookModuleRoutesdemomoduleroutes.php:57-88
Recurso en el Webservice /apiaddWebserviceResources + $webserviceParametersdemowsextend.php:74-83
SEO: JSON-LD y meta title/descriptionactionFrontControllerSetVariables mutando $params['templateVars']demoseo.php:51-114
Pestanas extra en la ficha de producto del FRONTdisplayProductExtraContentdemoproductextracontent.php:54-63
Temas / layouts / transformaciones de emailactionListMailThemes, actionBuildMailLayoutVariables, actionGetMailLayoutTransformationsexample_module_mailtheme.php:145-276
Override de plantillas Twig del BOConvencion de ruta: views/PrestaShop/<misma ruta que el core>/x.html.twig — cero PHPdemoextendtemplates no registra ni un hook
Tab de menu del BO$this->tabs en el constructor, o new Tab() en install()democontrollertabs.php:46-60, 80-102
Despachar comandos/consultas del NUCLEO$this->get('prestashop.core.command_bus') / 'prestashop.core.query_bus'demoextendsymfonyform3.php:197, 247
Componente JS Router del BOwindow.prestashop.instance.router.generate('ruta_del_core') — disponible en cualquier pagina del BOdemojsrouting/views/js/demo-page.js:19

3.2 EXIGE OBLIGATORIAMENTE src/ + composer.json (PSR-4) + config/services.yml (y a veces routes.yml)

CapacidadPor que
Crear un GRID propioEl GridFactory se ensambla en services.yml con 4 argumentos; definition factory y query builder necesitan parent: de servicios del core. demo_grid/config/services.yml:1-29
Controlador admin Symfony (PrestaShopAdminController)"when they do they must be defined as services". Necesita las tres piezas: PSR-4, services.yml (autowire+autoconfigure), routes.yml. presentGrid(), buildSearchResponse(), addFlash(), createForm(), render() Twig son suyos
Rutas Symfony propiasTodo lo que reciba un nombre de ruta: route de ToggleColumn/SubmitRowAction/LinkRowAction, submit_route de SubmitBulkAction, path() en Twig, $tab->route_name, _legacy_link
FormType con dependencias inyectadasTranslatorAwareType exige parent: 'form.type.translatable.aware' + tags: [{name: form.type}]. demosymfonyformsimple/config/services.yml:11-15
Core\Form\Handler + DataConfiguration/FormDataProviderEs un servicio; su 5o argumento es el hookName que genera action<X>Form / action<X>Save
FormBuilder/FormHandler de IdentifiableObjectSe crean SIEMPRE via factory del contenedor (prestashop.core.form.builder.form_builder_factory::create). Y son ellos los que disparan los hooks FormDataProvider*: un formulario montado a mano con form.factory pierde la extensibilidad
CQRS propio del modulo#[AsCommandHandler] / #[AsQueryHandler] solo se procesan con autoconfigure: true. El tag core.product_command_builder no tiene equivalente legacy
Doctrine ORM (entidades del modulo)Auto-descubrimiento sobre modules/<mod>/src/Entity — ruta obligatoria e inamovible. El repositorio se obtiene por factory: ['@doctrine.orm.default_entity_manager', getRepository]
API Platform (nueva API)Atributos #[ApiResource] descubiertos por PSR-4 + tags api_platform.state_provider / api_platform.state_processor
Comando de consolaUnicamente el tag console.command. No hay API legacy
Filtrar modulos por hookTag core.hook_module_exec_filter + HookModuleFilterInterface (PS 8.2.1+). Requiere ademas config/front/services.yml
Decorar un controlador del core#[AsDecorator] + #[MapDecorated], procesados solo por el contenedor
EventSubscriber sobre KernelEventsautoconfigure lo registra como listener
Configuracion multitienda con checkboxes "ajuste especifico"Heredar AbstractMultistoreConfiguration (3 servicios del core inyectados) + getParent() devolviendo MultistoreConfigurationType::class
#[AdminSecurity] y roles automaticosInfraestructura de seguridad Symfony; en legacy es Tab + tokens

Equivalencias legacy directas:

SymfonyLegacy
Grid propioModuleAdminController + $this->fields_list / renderList() (HelperList)
Ruta + accion AJAX del gridJS inyectado por actionAdminControllerSetMedia que hace $.post contra un ModuleAdminController con su token (Link::getAdminLink('AdminMiAccion'))
Core\Form\Handler + DataConfigurationgetContent() con Tools::isSubmit() -> guardar -> displayConfirmation()/displayError(); un unico HelperForm con pestanas
Configuration::set(..., ['html' => true])Configuration::updateValue($key, $value, true)
SqlLoader / DBALDb::getInstance()->execute()
Doctrine ORMObjectModel en classes/
bin/consoleModuleFrontController de tipo cron con token propio
Twig @Modules/...$this->display(__FILE__, 'views/templates/.../x.tpl')

4. Patrones de codigo reutilizables

4.1 Instalador separado + registerHook() con array

Funciona igual en legacy (classes/Installer.php con require_once) y en Symfony.

public function install()
{
    if (!parent::install()) { return false; }
    return (new Installer())->install($this);
}

private function registerHooks(Module $module): bool
{
    $hooks = [
        'actionProductFormBuilderModifier',
        'actionAfterUpdateProductFormHandler',
        'displayAdminProductsExtra',
    ];
    return (bool) $module->registerHook($hooks);
}

Cuidado: con $hooks = [], registerHook([]) devuelve falsy y el install fallaria (bug real en demooverrideobjectmodel/src/Install/Installer.php:60).

4.2 SQL de instalacion — dos variantes

// (a) Nucleo/Symfony: SqlLoader con placeholders (demoproductform/src/Install/Installer.php:37-101)
$allowed = ['utf8mb4_general_ci', 'utf8mb4_unicode_ci'];
$collation = \Db::getInstance()->getValue('SELECT @@collation_database');
$loader = new SqlLoader();
$loader->setMetaData([
    'PREFIX_'     => _DB_PREFIX_,
    'ENGINE_TYPE' => _MYSQL_ENGINE_,
    'COLLATION'   => (empty($collation) || !in_array($collation, $allowed)) ? '' : 'COLLATE ' . $collation,
]);
$loader->parseFile($filepath);

// (b) LEGACY puro (demooverrideobjectmodel/src/Install/Installer.php:76-87)
$sql = Tools::file_get_contents($module->getLocalPath() . 'sql/install.sql');
$sql = str_replace(['_DB_PREFIX_', '_MYSQL_ENGINE_'], [_DB_PREFIX_, _MYSQL_ENGINE_], $sql);
Db::getInstance()->execute($sql);

4.3 El servicio del modulo NO existe todavia durante install()

Trampa real de PS 9. Patron: try/catch + construccion manual con servicios del CORE.

private function getInstaller(): DBInstaller
{
    try { $installer = $this->get(DBInstaller::class); }
    catch (Exception) { $installer = null; }

    if (!$installer) {
        $installer = new DBInstaller(
            $this->get('doctrine.dbal.default_connection'),
            $this->getContainer()->getParameter('database_prefix')
        );
    }
    return $installer;
}

Evidencia: api_module.php:74-92; mismo problema resuelto con require_once incondicional del autoload en demovieworderhooks.php:42-43.

4.4 Pestana en una pagina Symfony del BO (contrato del id)

Dos hooks independientes; el core no correlaciona nada: si los ids no casan, la pestana aparece vacia.

public function hookDisplayAdminOrderTabLink(array $params)    { return $this->render('tracking_link.html.twig'); }
public function hookDisplayAdminOrderTabContent(array $params) { return $this->render('tracking.html.twig', [...]); }
{# cabecera #}
<li class="nav-item">
  <a class="nav-link" id="trackingTab" data-toggle="tab" href="#trackingTabContent"
     role="tab" aria-controls="trackingTabContent" aria-selected="false">
    <i class="material-icons">pin_drop</i> {{ 'Package tracking'|trans }}
  </a>
</li>

{# panel: MISMO id, aria-labelledby = id del enlace #}
<div class="tab-pane fade show active" id="trackingTabContent" role="tabpanel" aria-labelledby="trackingTab">

Quitar show active si no quieres robar el foco a la pestana por defecto. Evidencia: demovieworderhooks.php:142-166.

4.5 Hook action* que MUTA una coleccion (barra de botones)

No devuelve nada: se modifica el objeto recibido.

public function hookActionGetAdminOrderButtons(array $params)
{
    $order  = new Order($params['id_order']);
    $router = $this->get('router');
    /** @var \PrestaShop\PrestaShop\Core\Action\ActionsBarButtonsCollection $bar */
    $bar = $params['actions_bar_buttons_collection'];

    $bar->add(new \PrestaShop\PrestaShop\Core\Action\ActionsBarButton(
        'btn-secondary',
        ['href' => $router->generate('admin_customers_view', ['customerId' => (int) $order->id_customer])],
        'View customer'
    ));
}

Evidencia: demovieworderhooks.php:83-115.

4.6 Grid del core: columna toggle + filtro + JOIN

public function hookActionCustomerGridDefinitionModifier(array $params)
{
    $definition = $params['definition'];

    $definition->getColumns()->addAfter('optin',
        (new ToggleColumn('is_allowed_for_review'))
            ->setName($this->trans('Allowed for review', [], 'Modules.X.Admin'))
            ->setOptions([
                'field'            => 'is_allowed_for_review',
                'primary_field'    => 'id_customer',
                'route'            => 'ps_demo_toggle_is_allowed',   // <- ESTO exige routes.yml
                'route_param_name' => 'customerId',
            ])
    );

    $definition->getFilters()->add(
        (new Filter('is_allowed_for_review', YesAndNoChoiceType::class))
            ->setAssociatedColumn('is_allowed_for_review')
    );
}

public function hookActionCustomerGridQueryBuilderModifier(array $params)
{
    /** @var \Doctrine\DBAL\Query\QueryBuilder $qb */
    $qb = $params['search_query_builder'];
    $criteria = $params['search_criteria'];

    $qb->addSelect('IF(d.`is_allowed_for_review` IS NULL,0,d.`is_allowed_for_review`) AS `is_allowed_for_review`');
    $qb->leftJoin('c', '`' . pSQL(_DB_PREFIX_) . 'mi_tabla`', 'd', 'd.`id_customer` = c.`id_customer`');

    if ('is_allowed_for_review' === $criteria->getOrderBy()) {
        $qb->orderBy('d.`is_allowed_for_review`', $criteria->getOrderWay());
    }
    foreach ($criteria->getFilters() as $name => $value) {
        if ('is_allowed_for_review' === $name) {
            $qb->andWhere('d.`is_allowed_for_review` = :v')->setParameter('v', $value);
            if (!$value) { $qb->orWhere('d.`is_allowed_for_review` IS NULL'); }
        }
    }
}

Sin el QueryBuilderModifier la columna sale vacia. Localizar la columna actions para anadir acciones de fila:

foreach ($definition->getColumns() as $column) {
    if ('actions' === $column->getId()) { $actions = $column->getOptions()['actions']; break; }
}
$actions->add((new SubmitRowAction('mark_order'))->setName('Mark')->setIcon('push_pin')
    ->setOptions(['route' => 'x', 'route_param_name' => 'orderId', 'route_param_field' => 'id_order', 'use_inline_display' => true]));

Evidencia: demoextendsymfonyform1.php:119-182, demoextendgrid.php:84-122.

4.7 JS de accion de fila (delegacion + AJAX + growl)

$(() => {
  $(document).on('click', '.js-submit-row-action', (event) => {
    event.preventDefault();
    const $t = $(event.currentTarget);
    $.post($t.data('url')).then((response) => {
      $t.find('i').addClass('text-success');
      $.growl({ message: response });
    });
  });
});

Delegacion sobre document: sobrevive a los repintados del grid. data-url puede apuntar a una ruta Symfony o a un ModuleAdminController legacy con su token. Evidencia: demoextendgrid/views/js/orders-listing.js:18-27.

4.8 Componentes JS del back-office (imprescindible con form types "ricos")

Sin esto, TinyMCE no aparece, el arbol de categorias no se despliega y los checkboxes multitienda no habilitan nada.

window.prestashop.component.initComponents([
  'TranslatableField', 'TinyMCEEditor', 'TranslatableInput',
  'GeneratableInput', 'TextWithLengthCounter',
  'ChoiceTable', 'MultipleChoiceTable',
  'MultistoreConfigField', 'Grid', 'Router',
]);
window.prestashop.instance.generatableInput.attachOn('.js-generator-btn');
new window.prestashop.component.ChoiceTree('#form_category_choice_tree_type').enableAutoCheckChildren();

// Grid propio: el string es el GRID ID
const grid = new window.prestashop.component.Grid('mi_grid_id');
grid.addExtension(new window.prestashop.component.GridExtensions.SortingExtension());
grid.addExtension(new window.prestashop.component.GridExtensions.FiltersResetExtension());

Otras extensiones: BulkActionCheckboxExtension, SubmitBulkExtension, SubmitRowActionExtension, ExportToSqlManagerExtension, LinkRowActionExtension, ReloadListActionExtension, AsyncToggleColumnExtension.

Evidencia: demosymfonyform/views/js/form.js:20-35, demo_grid/views/demo_grid.js:20-24, demomultistoreform/views/js/form.js:19-28.

4.9 URLs amigables en el front (moduleRoutes)

Cuatro llaves obligatorias por ruta; params DEBE incluir fc y module.

public function install() { return parent::install() && $this->registerHook('moduleRoutes'); }

public function hookModuleRoutes()
{
    return [
      'module-mimodulo-show' => [
        'rule'     => 'mimodulo/show/{id}/{slug}',
        'keywords' => [
          'id'   => ['regexp' => '[0-9]*', 'param' => 'id'],
          'slug' => ['regexp' => '.*',     'param' => 'slug'],
        ],
        'controller' => 'show',                                    // controllers/front/show.php
        'params'     => ['fc' => 'module', 'module' => 'mimodulo'],
      ],
    ];
}
// Clase: <ClasePrincipal>ShowModuleFrontController extends ModuleFrontController
// Los keywords se leen con Tools::getValue('id'), NO como argumentos

Generar la URL: $this->context->link->getModuleLink('mimodulo', 'show', ['id' => 1, 'slug' => 'abc']) o {url entity='module' name='mimodulo' controller='show' params=['id'=>1]}. Solo funciona con Friendly URL activo. Evidencia: demomoduleroutes.php:57-88, controllers/front/show.php:7-22.

4.10 Webservice /api — recurso propio (100% legacy, 1.7.8+)

require_once _PS_MODULE_DIR_ . 'demowsextend/src/Entity/Article.php';

public function hookAddWebserviceResources($params)
{
    return [
        'articles' => [
            'description' => 'Blog articles',
            'class'       => 'Article',
            // 'forbidden_method' => ['DELETE'],
        ],
    ];
}

class Article extends ObjectModel   // SIN namespace
{
    public static $definition = ['table' => 'article', 'primary' => 'id_article', 'multilang' => true, 'fields' => [...]];

    protected $webserviceParameters = [
        'objectNodeName'  => 'article',
        'objectsNodeName' => 'articles',
        'fields' => ['title' => ['required' => true], 'content' => []],
    ];
}

$webserviceParameters['fields'] es el subconjunto EXPUESTO por la API. Evidencia: demowsextend.php:25, 74-83; src/Entity/Article.php:25, 55-64.

4.11 Override de plantillas Twig del BO — cero PHP

Replicar bajo views/PrestaShop/ la misma ruta relativa que el twig tiene en el core.

{# views/PrestaShop/Admin/Sell/Order/Order/index.html.twig #}
{% extends '@PrestaShopCore/Admin/Sell/Order/Order/index.html.twig' %}
{% block content %}
  {{ parent() }}
  <div class="text-success"><p>Contenido anadido</p></div>
{% endblock %}

Bloque que vive en una plantilla incluida: hay que re-embeberla pasando sus variables a mano.

{% block order_grid_row %}
  {% embed '@PrestaShop/Admin/Common/Grid/grid_panel.html.twig' with {'grid': orderGrid} %}
    {% block grid_panel_header %}<div><a href="#">Mi cabecera</a></div>{% endblock %}
  {% endembed %}
{% endblock %}

Alias: @PrestaShop/... respeta overrides; @!PrestaShop/... y @PrestaShopCore/... (desde PS 8.0) fuerzan el original del core. Evidencia: demoextendtemplates/views/PrestaShop/Admin/Sell/Order/Order/index.html.twig:1-36.

4.12 SEO desde un hook (actionFrontControllerSetVariables)

$params['templateVars'] se muta en sitio; el metodo no devuelve nada. Comprobar isset() de cada rama.

public function hookActionFrontControllerSetVariables($params)
{
    if ($this->context->controller->php_self === 'product') {
        if (isset($params['templateVars']['structured_data']['product'])) {
            $params['templateVars']['structured_data']['product']['aggregateRating'] = [
                '@type' => 'AggregateRating', 'ratingValue' => 4.8, 'reviewCount' => 27,
                'bestRating' => 5, 'worstRating' => 1,
            ];
        }
        if (isset($params['templateVars']['structured_data']['product']['offers'])) {
            $params['templateVars']['structured_data']['product']['offers']['availability'] = 'https://schema.org/LimitedAvailability';
        }
    }
    if ($this->context->controller->getPageName() === 'category') {
        $c = new Category(Tools::getValue('id_category'), $this->context->language->id, $this->context->shop->id);
        $params['templateVars']['page']['meta']['title'] = $c->name . ' | ' . $this->context->shop->name;
    }
}

Claves utiles: structured_data.product, .product.offers, .organization, page.meta.title. Evidencia: demoseo.php:51-114.

4.13 Temas y layouts de email

// Anadir un TEMA completo escaneando una carpeta
public function hookActionListMailThemes(array $hookParams)
{
    if (!isset($hookParams['mailThemes'])) { return; }
    $theme = (new FolderThemeScanner())->scan(_PS_MODULE_DIR_ . 'mimodulo/mails/themes/dark_modern');
    if (null !== $theme && $theme->getLayouts()->count() > 0) { $hookParams['mailThemes']->add($theme); }
}

// REEMPLAZAR un layout del core conservando su contenido
$orderConf = $theme->getLayouts()->getLayout('order_conf', '');  // '' = layouts del core
$idx = $theme->getLayouts()->indexOf($orderConf);
$theme->getLayouts()->offsetSet($idx, new Layout($orderConf->getName(),
    '@Modules/mimodulo/mails/layouts/extended_modern_order_conf_layout.html.twig', ''));
{% extends '@MailThemes/modern/core/order_conf.html.twig' %}
{% block content %}{{ parent() }} ... extra ... {% endblock %}

Transformacion del HTML final (DOM Crawler):

class MiTransformation extends AbstractTransformation
{
    public function __construct($c) { parent::__construct(MailTemplateInterface::HTML_TYPE); $this->c = $c; }
    public function apply($templateContent, array $templateVariables)
    {
        $crawler = new Crawler($templateContent);
        foreach ($crawler->filter('span[class="subtitle"]') as $span) {
            $span->setAttribute('style', sprintf('color: %s;', $this->c));
        }
        return $crawler->html();
    }
}

Filtrar siempre por templateType y por que el layout sea tuyo ($hookParams['mailLayout']->getModuleName() != $this->name) o transformas correos ajenos. Evidencia: example_module_mailtheme.php:145-276.

4.14 Tab de menu del BO — dos formas

// (a) DECLARATIVA, en el CONSTRUCTOR. 'name' indexado por LOCALE
$this->tabs = [[
    'route_name'        => 'ps_controller_tabs_configure',  // solo con routes.yml
    'class_name'        => 'AdminDemoControllerTabsConfigure',
    'visible'           => true,
    'name'              => $tabNames,   // [locale => texto]
    'icon'              => 'school',
    'parent_class_name' => 'IMPROVE',
]];

// (b) MANUAL en install(). 'name' indexado por id_lang
$tabId = (int) Tab::getIdFromClassName($className);
$tab = new Tab($tabId ?: null);
$tab->active = 1;
$tab->class_name = $className;
$tab->route_name = 'ps_controller_tabs_manual_tab';   // omitir en legacy
$tab->name = []; foreach (Language::getLanguages() as $l) { $tab->name[$l['id_lang']] = '...'; }
$tab->icon = 'build';
$tab->id_parent = (int) Tab::getIdFromClassName('IMPROVE');
$tab->module = $this->name;
return (bool) $tab->save();

El motivo real de crear la Tab no es solo el menu: es que se creen los roles de autorizacion. Evidencia: democontrollertabs.php:46-60, 80-102.

4.15 getContent() que redirige a una pagina Symfony

public function getContent()
{
    Tools::redirectAdmin($this->context->link->getAdminLink('AdminMiControlador'));
    // o: Tools::redirectAdmin($this->get('router')->generate('mi_ruta'));
    // o: Tools::redirectAdmin(SymfonyContainer::getInstance()->get('router')->generate('mi_ruta'));
}

Requiere is_configurable=1 en config.xml. Con _legacy_link en la ruta, getAdminLink() resuelve a la URL Symfony.

4.16 _legacy_controller vs _legacy_link

ParametroRol
_legacy_controllerNombre logico usado por el sistema de PERMISOS; al declararlo se crean los roles del controlador (permite controlador seguro sin tab visible)
_legacy_linkPermite que Link::getAdminLink('AdminXxx') genere la URL de esa ruta desde codigo legacy

Un controlador puede llevar los dos, uno o ninguno. Evidencia: democontrollertabs/config/routes.yml:2-27.

4.17 Comando de consola — registro minimo

# config/services.yml — esto es TODO
services:
    PrestaShop\Module\DemoConsoleCommand\Command\ListManufacturersCommand:
        tags: [ console.command ]
protected function configure() { $this->setName('demo:list-manufacturers')->setDescription('...'); }
protected function execute(InputInterface $input, OutputInterface $output)
{
    (new Table($output))->setHeaders(['id','name'])->setRows($rows)->render();
    return 0;
}

Se ejecuta con php bin/console demo:list-manufacturers desde la raiz de PrestaShop. La clase principal del modulo puede estar vacia. Evidencia: democonsolecommand/config/services.yml:1-3.

4.18 Filtrar modulos por hook (PS 8.2.1+)

# config/common.yml
services:
  Module\DemoFilterModules\Service\CustomModuleList:
    tags: [ 'core.hook_module_exec_filter' ]
# config/services.yml       -> imports: [{ resource: ./common.yml }]
# config/front/services.yml -> imports: [{ resource: ../common.yml }]
public function filterHookModuleExecList(array $modules, string $hookName): array
{
    if (defined('_PS_ADMIN_DIR_')) { return $modules; }   // no tocar el BO
    if ($hookName === 'displayFooter') {
        foreach ($modules as $i => $m) {
            if ($m['module'] === 'ps_linklist') { unset($modules[$i]); }
        }
    }
    return $modules;
}

Se ejecuta en cada ejecucion de hook: ser barato en CPU. Evidencia: demofiltermodules/src/Service/CustomModuleList.php:7-28.

4.19 Override de ObjectModel del core (antipatron, solo referencia)

// override/classes/Manufacturer.php
class Manufacturer extends ManufacturerCore
{
    public string $code;

    public function __construct(?int $id = null, ?int $idLang = null)
    {
        // el campo se inyecta ANTES del parent::__construct
        self::$definition['fields']['code'] = ['type' => self::TYPE_STRING, 'size' => 64];
        parent::__construct($id, $idLang);
    }
}
-- install.sql
ALTER TABLE _DB_PREFIX_manufacturer ADD `code` VARCHAR(64) NOT NULL DEFAULT '';
-- uninstall.sql
ALTER TABLE _DB_PREFIX_manufacturer DROP COLUMN `code`;

Si se inyecta DESPUES del parent::__construct, la carga del objeto ignora la columna. El README oficial lo desaconseja: solo un modulo puede overridear una clase a la vez.

4.20 Modulo "Symfony-light": Twig en el BO sin src/

dashexample renderiza Twig, usa el contenedor y no tiene src/, ni config/services.yml, ni bloque autoload en composer.json.

class DashExample extends Module      // namespace GLOBAL
{
    public function hookDisplayAdminDashboardZoneOne(array $params): string
    {
        return $this->render('zone_one.html.twig', [
            'dateFrom' => $params['date_from'] ?? null,
            'dateTo'   => $params['date_to'] ?? null,
        ]);
    }

    public function hookDisplayAdminDashboardToolbar(array $params): string
    {
        // CSS/JS del modulo emitidos desde la salida del hook, sin actionAdminControllerSetMedia
        return $this->render('toolbar.html.twig', ['moduleUri' => $this->getPathUri()]);
    }

    private function render(string $template, array $params = []): string
    {
        /** @var \Twig\Environment $twig */
        $twig = $this->get('twig');
        return $twig->render(sprintf('@Modules/%s/views/templates/admin/%s', $this->name, $template), $params);
    }
}

Evidencia: dashexample.php:39, 72-78, 133-149; views/templates/admin/toolbar.html.twig:11-14.


5. Errores y trampas conocidas

5.1 Versiones y documentacion

  1. Los README mienten. demoextendgrid/README.md:15 dice "1.7.7 to 8.1" pero el codigo es PS 9 (PrestaShopAdminController, icono push_pin). demomultistoreform/README.md:47 dice "1.7.8 a 8.1" pero declara min 9.0.0. demodoctrine/README.md:5 dice "1.7.7 and above" y la linea 13 del mismo fichero dice "9.0.0 and above". Fiarse solo de ps_versions_compliancy.
  2. config.xml casi nunca declara version de PS. La compliancy vive en el constructor. Y hay desincronizaciones internas: demoextendgrid/config.xml declara 1.1.0 y el .php 1.2.0; demodoctrine/config.xml 1.0.0 vs .php 2.0.0.
  3. PS 8 vs PS 9 en controladores: PS 9 usa PrestaShopBundle\Controller\Admin\PrestaShopAdminController + inyeccion por argumento con #[Autowire(service: 'id')]. PS 8 usaba FrameworkBundleAdminController + $this->get('id'). Este codigo NO es portable tal cual a 8.x.
  4. demoextrafield es SOLO 9.2.x. ExtraPropertyDefinition, registerExtraProperty(), etc. no existen en 8.x ni en 9.0/9.1: llamarlos rompe la instalacion. Para 8.x el sustituto es el trio FormBuilderModifier + FormDataProviderData + AfterCreate/UpdateFormHandler con tabla propia.
  5. demoseo exige 9.2.0 para los structured_data, aunque el hook exista desde 1.7.5.0.
  6. dashexample requiere ademas el feature flag dashboard activado en Parametros Avanzados > Nuevas funcionalidades experimentales.

5.2 Formularios

  1. $params['id'] es null en la pantalla de creacion. Comprobarlo siempre antes de cargar datos.
  2. setData() requiere el array COMPLETO. $formBuilder->setData($params['data']) tras escribir tu clave; si pasas solo el campo nuevo, pierdes el resto de datos del formulario.
  3. El FormBuilderModifier SOLO pinta el campo; no guarda nada. Hay que registrar ademas actionAfterCreate... y actionAfterUpdate....
  4. actionProductFormDataProviderDefaultData no se dispara en el alta de producto de PS 9.1 (el modal usa block prefix create_product). Ver 2.7.
  5. Solo data y options viajan por referencia en los hooks de FormDataProvider; id va por valor.
  6. Un formulario montado a mano con form.factory pierde los hooks. Los FormDataProvider* los dispara el FormBuilder de factoria del core.
  7. Hay DOS interfaces distintas llamadas FormDataProviderInterface:
    • PrestaShop\PrestaShop\Core\Form\FormDataProviderInterface — configuracion: getData(): array, setData(array): array (devuelve errores).
    • PrestaShop\PrestaShop\Core\Form\IdentifiableObject\DataProvider\FormDataProviderInterface — CRUD: getData($id), getDefaultData(); el guardado va en FormDataHandlerInterface aparte. Elegir la equivocada es error de compilacion del contenedor.
  8. HelperForm/Symfony: cada campo anadido en renderForm() DEBE tener valor en fields_value o Smarty lanza Undefined array key.
  9. block_prefix != entityName rompe la inyeccion automatica de extra properties. Caso documentado: ManufacturerAddressType (prefix manufacturer_address) frente a la entidad address — el campo solo puede ir al grid, no al formulario.
  10. GeoCoordinatesType se anade como 'coordinates' pero en $form->getData() aparece como latitude/longitude planos. Inspeccionar siempre la estructura real de getData() antes de escribir el DataConfiguration.
  11. Sin form_theme del UI Kit los campos salen rotos. Hay que ponerlo en configureOptions() y con {% form_theme %} en el Twig.
  12. Bug latente que NO hay que copiar (demoproductform): el handler comprueba null !== $command->getCustomerField() pero la propiedad es private string $customerField = '' — nunca es null, asi que la condicion es siempre true y setFieldsToUpdate() no filtra nada. Tipar ?string = null. Evidencia: UpdateCustomProductCommand.php:45, 59-62 vs UpdateCustomProductCommandHandler.php:57-60.
  13. Antipatron en demomultistoreform: sobrescribe validateConfiguration() devolviendo true a secas, anulando el OptionsResolver del padre. No copiarlo.
  14. Ruta de guardado multitienda: debe aceptar PATCH. La extension fuerza $builder->setMethod(Request::METHOD_PATCH) cuando hay checkboxes multitienda. Si la ruta solo declara POST -> 405 imposible de diagnosticar. Evidencia: MultistoreConfigurationTypeExtension.php:41-42.
  15. Varios formularios en una pagina: en las acciones de guardado se comprueba solo isSubmitted() (no isValid()), porque tras el redirect el usuario no veria los errores de constraint; la validacion se hace en el DataConfiguration devolviendo errores.

5.3 Grids

  1. Sin GridQueryBuilderModifier la columna nueva sale vacia. Y usar IF(x IS NULL, 0, x) o el toggle revienta en filas sin registro.
  2. Filtrar por "No" requiere orWhere(... IS NULL).
  3. GRID_ID unico. demo_grid usa 'product', que COLISIONA con el grid nativo (mismo filterId en la tabla de filtros del empleado y mismo nombre de hook actionProductGridDefinitionModifier). En modulo real usar ecom_misregistros.
  4. El Grid necesita DOS rutas con el mismo path: GET (index) y POST (searchAction -> buildSearchResponse). Sin la POST, el formulario de filtros da 405.
  5. SqlFilters con concatenacion insegura: demomultistoreform/src/Grid/Query/ContentBlockQueryBuilder.php:49,71 hace implode() de IDs directamente en el WHERE. Usar setParameter/createNamedParameter.
  6. GridFactory debe ser public: true para inyectarlo por id de servicio.

5.4 Instalacion / servicios

  1. Durante install() el contenedor del modulo aun no esta compilado: $this->get(MiServicio::class) lanza excepcion. Patron try/catch + construccion manual (ver 4.3).
  2. Durante install() las entidades Doctrine no estan mapeadas: crear tablas con SQL crudo, nunca con el EntityManager.
  3. require_once vendor/autoload.php: obligatorio si la clase principal referencia clases de src/ antes de que exista el contenedor (constantes TAB_CLASS_NAME, InstallerFactory). demoextendsymfonyform1 y 3 NO lo hacen y funcionan porque PrestaShop carga el autoloader del modulo; api_module lo hace con file_exists (defensivo); demovieworderhooks lo hace incondicional. Recomendacion: incluirlo.
  4. "config": {"prepend-autoloader": false} en composer.json: importante para que el autoloader del modulo no se anteponga al del nucleo y provoque conflictos de version de librerias.
  5. public: true es obligatorio en todo servicio que se consuma con $this->get('id') desde un hook.
  6. registerHook([]) con array vacio devuelve falsy y hace fallar el install.
  7. Tab::getIdFromClassName puede lanzar NonUniqueResult en PS 9 con tabs duplicadas. Usar Db::getValue para comprobar existencia.
  8. hookName generico en Core\Form\Handler: demomultistoreform pasa 'ConfigurationForm', generando actionConfigurationFormForm/Save — colisionables. Usar un nombre unico (EcomMiModuloConfiguration).

5.5 Plantillas y traducciones

  1. Override de views/PrestaShop/Admin/layout.html.twig es GLOBAL a todo el back-office y solo un modulo puede ganar por fichero. Dos modulos que sobrescriban el mismo twig colisionan. Redefinir la macro alert() cambia el HTML de TODAS las alertas del BO.
  2. {{ parent() }} es obligatorio al sobrescribir {% block javascripts %} / {% block stylesheets %}, o se pierden jQuery y los componentes del BO.
  3. Inconsistencia real de dominios de traduccion en el repo oficial: algunas plantillas Twig usan Module.<Studly>.Admin (singular) y el PHP usa Modules.<Studly>.Admin (plural). Verificar cual consume la instalacion.
  4. demoextrafield/README.md:95 remite a registerTranslationWordings(), metodo que NO existe en el codigo (fichero leido integro, 812 lineas). No copiar esa referencia.
  5. {displayPrice price=... currency=...} NO existe en PS 1.7/8/9 (era de 1.6) -> Fatal error. Formatear en PHP.
  6. demodoctrine/views/templates/front/home.tpl:30-31 imprime sin |escape. Viola las reglas de este proyecto.
  7. Los ejemplos usan {l s='...' mod='modulo'} (sistema LEGACY) porque no declaran isUsingNewTranslationSystem(). Si tu modulo lo declara true, mod= NO leera los .xlf.
  8. democontrollertabs/views/templates/admin/layout.html.twig:74,79 carga highlight.js desde un CDN externo. Evitar en produccion.

5.6 Rendimiento / seguridad

  1. demoextrafield escribe en BD dentro de un hook de FRONT (displayFooterProduct, demoextrafield.php:595-631): un UPDATE por cada visita de ficha. Util como demo, peligroso en produccion.
  2. actionAdminControllerSetMedia se dispara en TODOS los controladores del BO. Filtrar por $this->context->controller->controller_name y por Tools::getValue('action') (el mismo controlador sirve listado, detalle y alta). Nunca usar $controller::class.
  3. core.hook_module_exec_filter se ejecuta en cada ejecucion de hook: cortocircuitar el BO con defined('_PS_ADMIN_DIR_').
  4. Bug real en api_module: HorseProvider.php:56 usa $operation instanceof Patch pero el use de la linea 33 solo importa Put — el instanceof resuelve a una clase inexistente del namespace local y nunca coincide.
  5. demoextendsymfonyform2/config/routes.yml:6-7 declara requirements sobre categoryId cuando el parametro real es supplierId (copy/paste erroneo: el requirement no aplica). Y el mismo modulo usa dos dominios de traduccion distintos (Modules.DemoExtendSymfonyForm2.Admin en :55-56 vs Modules.DemoExtendSymfonyForm en :95).
  6. ProductFormModifier.php:111-122: la variable se llama $headerFormBuilder pero apunta a 'footer'. Ruido de copy/paste del repo oficial.
  7. El .sql partido por lineas (preg_split('/\r\n|\r|\n/')) solo funciona con UNA sentencia por linea. No parte por ;.

5.7 Multitienda

  1. $multistoreCompatibility (self::MULTISTORE_COMPATIBILITY_YES|_NO|_NOT_CONCERNED|_UNKNOWN) es una linea y evita el aviso de "compatibilidad desconocida". Funciona igual en legacy y Symfony.
  2. getShopConstraint() devuelve null en contexto "todas las tiendas" y el ShopConstraint concreto en contexto tienda/grupo.
  3. Borrado consciente del contexto: en contexto tienda, un elemento asociado a varias tiendas solo debe DESASOCIARSE del contexto actual y eliminarse cuando quede huerfano.

6. Chuleta de nombres de hook

# Formularios Symfony del BO (X = block prefix del FormType raiz, camelizado)
action{X}FormDataProviderDefaultData     -> valores por defecto (alta)
action{X}FormDataProviderData            -> valores al editar
action{X}FormBuilderModifier             -> anadir / quitar campos y pestanas
actionBefore{Create|Update}{X}FormHandler
actionAfter{Create|Update}{X}FormHandler -> persistir ($params['id'], $params['form_data'])

# Grids (X = getId() de la GridDefinitionFactory)
action{X}GridDefinitionModifier          -> columnas, filtros, row actions
action{X}GridQueryBuilderModifier        -> SQL del listado
action{X}GridDataModifier
action{X}GridFilterFormModifier
action{X}GridPresenterModifier

# Producto
actionProductFormBuilderModifier
actionCombinationFormFormBuilderModifier
actionAfterUpdateCombinationFormFormHandler
displayAdminProductsExtra                -> V1 y V2 (pestana "Modulos"), solo lectura
displayProductExtraContent               -> FRONT, devuelve ProductExtraContent[]
displayProductAdditionalInfo             -> FRONT
displayFooterProduct                     -> FRONT

# Pagina Ver pedido (BO)
displayAdminOrderTabLink / displayAdminOrderTabContent   -> PESTANA (ids deben casar)
displayAdminOrderMain / ...MainBottom / ...Side / ...SideBottom / ...Top / displayAdminOrder
displayAdminOrderCreateExtraButtons
displayOrderPreview                      -> $params['order_id'] (NO 'id_order')
actionGetAdminOrderButtons               -> muta $params['actions_bar_buttons_collection']

# Dashboard PS 9.2 (nuevo -> legacy)
displayAdminDashboardZoneOne/Two/Three   -> dashboardZoneOne/Two/Three
displayAdminDashboardTop                 -> displayDashboardTop
displayAdminDashboardToolbar             -> displayDashboardToolbarTopMenu
displayAdminDashboardBottom

# Email
actionListMailThemes / actionBuildMailLayoutVariables / actionGetMailLayoutTransformations

# Otros
moduleRoutes                             -> URLs amigables del FRONT (Friendly URL ON)
addWebserviceResources                   -> recurso en /api
actionFrontControllerSetVariables        -> structured_data + meta
actionAdminControllerSetMedia            -> CSS/JS en el BO (filtrar!)

# Tags de contenedor (NO son hooks; exigen services.yml)
core.product_command_builder     console.command
core.hook_module_exec_filter     api_platform.state_provider / .state_processor
form.type

7. Decision rapida

Necesito…Legacy?Como
Panel de solo lectura en la ficha de producto (V1 y V2)SIdisplayAdminProductsExtra + Smarty
Campo editable en una pestana existente del producto V2SIactionProductFormBuilderModifier + $this->get('form.form_builder_modifier')
Pestana nueva en el producto V2SIaddAfter sobre el builder RAIZ + AbstractType sin dependencias en classes/
Campo custom producto V2 + grid + API, en PS 9.2SIregisterExtraProperty()
Guardar ese campoSIactionAfterUpdateProductFormHandler + ObjectModel en classes/
Solo cambiar valores por defecto / precargadosSIaction<X>FormDataProvider*Data
Anadir columna/filtro/accion a un grid del coreSI (la accion, con ModuleAdminController+AJAX)action<X>GridDefinitionModifier + ...QueryBuilderModifier
Listado propio en el BOSIModuleAdminController + HelperList
CRUD Symfony con Grid + Form del coreNOsrc/ + composer.json + services.yml + routes.yml
Entidades Doctrine, CQRS propio, API Platform, comando bin/console, decorar un controlador, filtrar modulos por hookNOIdem
Modulo que debe funcionar en 8.x y 9.xObligatoriamente legacyNada de src/, services.yml, PrestaShopAdminController ni extra properties

8. Pestana propia en el producto V2 SIN src/, sin Composer y sin services.yml

Verificado en demoproductform (PS 9.x) y en las fuentes de 8.2.7 / 9.1.1.

Las tres piezas

1. Crear la pestana desde el hook, con el FormType de Symfony por FQCN (no hace falta clase propia):

public function hookActionProductFormBuilderModifier($params)
{
    if (empty($params['form_builder']) || (int) ($params['id'] ?? 0) <= 0) {
        return;
    }
    $params['form_builder']->add(
        'samestock',                                              // -> #product_samestock-tab
        'Symfony\Component\Form\Extension\Core\Type\FormType',
        array(
            'label' => 'Stock compartido',
            'mapped' => false,
            'required' => false,
            'form_theme' => '@Modules/samestock/views/templates/admin/FormTheme/tab.html.twig',
        )
    );
}

EditProductFormType::getParent() devuelve NavigationTabType, y navigation_tab_widget (prestashop_ui_kit_base.html.twig:1408) convierte todo hijo de la raiz en pestana. El block prefix de la raiz es product, asi que el id del panel es determinista: #product_samestock-tab.

2. El form theme del modulo. El namespace Twig @Modules esta disponible sin registrar nada (evidencia: demoproductform/src/Form/Type/CustomTabContentType.php:49). El nombre del bloque es <unique_block_prefix>_widget; para un hijo samestock de la raiz product es _product_samestock_widget:

{% extends '@PrestaShop/Admin/TwigTemplateForm/prestashop_ui_kit_base.html.twig' %}

{% block _product_samestock_widget %}
  {{ renderhook('displaySamestockProductTab', {'id_product': app.request.get('productId')}) }}
{% endblock %}

3. El contenido, en PHP. renderhook esta disponible en Twig, asi que el theme puede llamar a un hook PROPIO del modulo y el HTML se genera en PHP como siempre:

public function hookDisplaySamestockProductTab($params)
{
    return $this->renderProductsBlock((int) $params['id_product'])
         . $this->renderCombinationsBlock((int) $params['id_product']);
}

Registra displaySamestockProductTab como cualquier otro hook: Hook::registerHook() crea la fila si el nombre no existe.

Por que esto evita Symfony

Una clase FormType propia habria exigido config/services.yml con tags: [{ name: form.type }] y parent: 'form.type.translatable.aware' (demoproductform/config/services.yml). Usando el FormType generico de Symfony solo se consigue el contenedor de la pestana — sin mapeo ni validacion — pero eso basta si el modulo guarda por su cuenta desde actionProductUpdate leyendo el $_POST crudo (patron de "inyeccion directa").

Limitaciones

  • Sin FormType propio no hay mapeo de datos ni validacion de Symfony.
  • La pantalla de ALTA de producto no dispara el hook: CreateProductFormType usa el block prefix create_product, asi que el hook seria actionCreateProductFormBuilderModifier.
  • Si el theme o el hook fallan, la pestana sale vacia. Conviene que el modulo tambien pinte en displayAdminProductsExtra como respaldo, o retirar la pestana.

9. Deteccion fiable de pagina de producto V1 frente a V2

NO leer el flag product_page_v2 de la tabla feature_flag. Su columna type vale env,dotenv,db: el valor puede venir de una variable de entorno o de .env y anular la base de datos. Caso real: PS 8.2.0 sirviendo la V2 con la fila de la BD a 0.

La senal fiable es la ruta Symfony, que ademas PrestaShop incluye en los parametros del hook ('route' => 'admin_product_form'):

RutaPagina
admin_product_formclasica (V1)
admin_products_editnueva (V2), path /{productId}/edit
$route = (string) ($params['route'] ?? Tools::getValue('_route'));
if (strpos($route, 'admin_product_form') === 0) { /* V1 */ }
elseif (strpos($route, 'admin_products') === 0) { /* V2 */ }

Respaldos, por este orden: _PS_VERSION_ >= 9.0.0 implica siempre V2; < 8.1.0 implica siempre V1; y solo como ultimo recurso, el flag en BD.


10. REGLA DE ORO: el bloque en la ficha de producto va en UN SOLO SITIO

Verificado en produccion (PS 8.2.0). Costo 5 horas de depuracion.

El fallo

Un modulo pintaba su bloque en DOS sitios a la vez:

  • displayAdminProductsMainStepLeftColumnBottom (pagina principal, #step1)
  • displayAdminProductsExtra (pestana Modulos, #hooks)

Los dos usan los mismos name en los campos, asi que el POST llevaba todo repetido:

...&samestock_form_present=5423&samestock_add=5422&...   <- la seleccion del usuario
...&samestock_form_present=5423&samestock_add=0&...      <- la copia vacia

PHP se queda SIEMPRE con el ultimo valor de un nombre repetido. Llegaba 0 y no se guardaba nada. El guardado funcionaba perfectamente: guardaba un cero.

Peor todavia: displayAdminProductsExtra se renderiza antes que los paneles (product.html.twig:33 frente a essentials.html.twig:140), asi que si tambien pinta en V1, se queda el con el bloque y la pagina principal aparece vacia.

La regla

PaginaDonde pintarQue debe devolver vacio
V1 (PS 1.7, 8.0, y 8.1/8.2 con la V2 apagada)displayAdminProductsMainStepLeftColumnBottom (Ajustes basicos) y displayAdminProductsQuantitiesStepBottom (Cantidades)displayAdminProductsExtra
V2 (PS 8.1+ con la V2 activa, y unica en PS 9)displayAdminProductsExtra (pestana Modulos)los dos hooks de paneles

Ademas de excluir los hooks entre si con la deteccion de pagina, cada metodo de pintado debe llevar su propio guardian estatico:

protected static $products_rendered = false;

protected function renderProductsBlock($id_product)
{
    if (self::$products_rendered) {
        return '';
    }
    self::$products_rendered = true;
    // ...
}

Los hooks pueden dispararse mas veces de lo previsto (multitienda, AJAX parciales, otro modulo que reenvie el hook). El guardian es la red de seguridad.

Guardado en cada pagina

  • V1: los campos van dentro del <form> del producto y se leen con Tools::getValue() desde hookActionProductUpdate (patron de "inyeccion directa"). Funciona: los campos SI llegan al POST. No es cierto que el JavaScript de la ficha los descarte — esa teoria se comprobo falsa mirando el POST real.
  • V2: declarar los campos como campos REALES del formulario Symfony desde actionProductFormBuilderModifier (como demo_module_custom_field en demoproductform), y leerlos en actionAfterUpdateProductFormHandler, que PrestaShop despacha con los datos ya validados (src/Core/Form/IdentifiableObject/Handler/FormHandler.php:145: el nombre se compone como 'actionAfterUpdate' . camelize($form->getName()) . 'FormHandler', y el formulario de producto se llama product). Ningun services.yml necesario.

Primer paso ante un "no guarda"

Mirar el cuerpo del POST (pestana Red del navegador) y buscar si los campos del modulo aparecen repetidos. Antes de teorizar sobre hooks, tokens o JavaScript.


11. RECETA COMPLETA: pestana propia con TODO dentro en la pagina de producto V2

Funcionando en produccion (PS 8.2.0). Sin src/, sin Composer, sin services.yml, sin plantilla Twig propia y sin JavaScript.

Pieza 1 — crear la pestana y sus campos

public function hookActionProductFormBuilderModifier($params)
{
    if (empty($params['form_builder']) || (int) ($params['id'] ?? 0) <= 0) {
        return;   // la pantalla de ALTA no dispara este hook (prefijo create_product)
    }
    $formType   = 'Symfony\Component\Form\Extension\Core\Type\FormType';
    $choiceType = 'Symfony\Component\Form\Extension\Core\Type\ChoiceType';
    $builder = $params['form_builder'];

    // Hijo de la RAIZ => pestana automatica (#product_mitab-tab).
    $tab = $builder->create('mitab', $formType, [
        'label'    => 'Mi pestana',
        'required' => false,
        // OJO: NADA de 'mapped' => false.  Ver mas abajo.
    ]);

    $tab->add('keep', $choiceType, [
        'choices'  => $opciones,      // ['Etiqueta' => valor, ...]
        'multiple' => true,
        'expanded' => true,           // casillas
        'required' => false,
        'data'     => $seleccionadosActuales,
    ]);
    $tab->add('add', $choiceType, ['choices' => $lista, 'required' => false, 'data' => 0]);

    $builder->add($tab);
}

Funciona porque EditProductFormType::getParent() devuelve NavigationTabType y el bloque navigation_tab_widget convierte todo hijo de la raiz en pestana. El block prefix de la raiz es product, asi que el id del panel es determinista.

Los campos se pintan solos: al ser campos reales de Symfony los renderiza PrestaShop. No hace falta form theme — y menos aun con @Modules, que no existe en PS 8.x (solo en 9.x).

Pieza 2 — guardar

public function hookActionAfterUpdateProductFormHandler($params)
{
    $id   = (int) $params['id'];
    $data = $params['form_data'];
    $tab  = $data['mitab'] ?? null;   // <- aqui llegan los valores
    if (!is_array($tab)) { return; }
    // $tab['keep'], $tab['add'], ...
}

El nombre del hook sale de src/Core/Form/IdentifiableObject/Handler/FormHandler.php:145: 'actionAfterUpdate' . camelize($form->getName()) . 'FormHandler', y el formulario de producto se llama product. Es un hook normal: no necesita services.yml.

LA TRAMPA: 'mapped' => false ROMPE EL GUARDADO

Poner 'mapped' => false en los campos parece lo natural (son datos del modulo, no del producto) pero hace que Symfony NO incluya el valor en $form->getData(), que es justo de donde sale form_data. Resultado: el hook de guardado recibe null, sale antes de tocar nada, y la pantalla dice "Actualizado correctamente" sin haber guardado nada del modulo.

Sintoma exacto observado: se desmarcaba una casilla, se guardaba, salia el mensaje de exito... y al recargar la casilla volvia marcada.

Regla: NO uses mapped => false en campos cuyo valor necesites leer en actionAfterUpdate<Form>FormHandler. Los datos del formulario de producto son un array, asi que mapearlos es inofensivo: simplemente aparecen como $data['mitab'][...].

Reparto final entre V1 y V2

PaginaDonde va el bloqueQue devuelve vacio
V1displayAdminProductsMainStepLeftColumnBottom (pagina principal)displayAdminProductsExtra
V2pestana propia via actionProductFormBuilderModifierdisplayAdminProductsExtra

displayAdminProductsExtra (pestana Modulos) no se usa en ninguna de las dos: pintar en dos sitios duplica los name en el POST y PHP se queda con la copia vacia.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall