ecomyseo/prestashop_skills / prestashop-example-modules
prestashop-example-modules
VerifiedConocimiento 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
| Demo | Para que sirve | Hooks | Version PS | Legacy puro? |
|---|---|---|---|---|
| demoproductform | Campos y PESTANAS nuevas en el formulario de producto V2 + formulario de combinacion; guardado por CQRS y por hook | actionProductFormBuilderModifier, actionCombinationFormFormBuilderModifier, actionAfterUpdateCombinationFormFormHandler, displayAdminProductsExtra | 9.0.0–9.99.99 (demoproductform.php:45) | NO (src/, composer, services.yml) |
| demoproductextracontent | Pestanas de contenido extra en la ficha de producto del FRONT | displayProductExtraContent | 1.7.0–9.99.99 (demoproductextracontent.php:34) | SI |
| demoextrafield | API 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 CMS | displayProductAdditionalInfo, displayFooterProduct, displayCartExtraProductInfo, displayHeaderCategory, displayCustomerAccountTop, actionCmsPageFormBuilderModifier, actionCmsPageFormDataProviderData, actionAfterCreate/UpdateCmsPageFormHandler, displayCMSDisputeInformation | 9.2.0–9.9.99 (demoextrafield.php:52) | SI |
| demoseo | Structured data JSON-LD + meta title/description desde un solo hook | actionFrontControllerSetVariables | >=9.2.0 (demoseo.php:36); el hook existe desde 1.7.5, los structured_data desde 9.2 | SI (ni config.xml trae) |
| demosymfonyform | Catalogo vivo de TODOS los form types de PrestaShop, 3 paginas BO, multiples formularios por pagina | Ninguno registrado; indirectos via Core\Form\Handler con hookName DemoConfiguration | 9.0.0+ (demosymfonyform.php:44) | NO |
| demosymfonyformsimple | Esqueleto minimo de pagina de configuracion Symfony (6 ficheros) con validacion y errores | Ninguno | 9.0.0+ (demosymfonyformsimple.php:26) | NO |
| demoextendsymfonyform1 | Campo booleano en el form de Cliente + columna toggle y filtro en el grid; ObjectModel + repositorio DBAL | actionCustomerGridDefinitionModifier, actionCustomerGridQueryBuilderModifier, actionCustomerFormBuilderModifier, actionAfterCreate/UpdateCustomerFormHandler | 9.0.0–9.99.99 (demoextendsymfonyform1.php:63-66) | NO |
| demoextendsymfonyform2 | Subida de imagen en el form de Proveedor + bloque HTML custom; Doctrine ORM | actionSupplierFormBuilderModifier, actionAfterCreate/UpdateSupplierFormHandler | 9.0.0–9.99.99 (demoextendsymfonyform2.php:51) | NO |
| demoextendsymfonyform3 | Igual que #1 pero con CQRS propio (#[AsCommandHandler] / #[AsQueryHandler]) | Los 5 de Customer | 9.0.0–9.99.99 (demoextendsymfonyform3.php:65-68) | NO |
| demoformdataproviders | Modificar los DATOS del formulario de producto V2 desde un modulo legacy puro | actionProductFormDataProviderData, actionProductFormDataProviderDefaultData | 8.0.0–9.99.99 (demoformdataproviders.php:34) | SI |
| demomultistoreform | CRUD 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 OBSOLETO | NO |
| demoextendtemplates | 5 vias de extender plantillas Twig del BO sin tocar el core + decorador de controlador + EventSubscriber | Ninguno | 9.1.0+ (demoextendtemplates.php:34) | Overrides Twig si; decorador/subscriber no |
| democontrollertabs | 5 escenarios de controlador Symfony + Tab de menu ($this->tabs vs Tab manual) + permisos | Ninguno | 9.0.0+ (democontrollertabs.php:39) | NO |
| demo_grid | Grid propio completo desde cero | Ninguno; su grid EMITE action<GridId>Grid*Modifier | 9.0.0+ (demo_grid.php:34) | NO |
| demoextendgrid | Anadir accion de fila al grid de Pedidos + JS AJAX | actionOrderGridDefinitionModifier, actionAdminControllerSetMedia | 9.0.0+ real (demoextendgrid.php:42); README dice 1.7.7-8.1 OBSOLETO | Hook si; la ruta de la accion no |
| demofiltermodules | Filtrar que modulos se ejecutan en un hook del front | Ninguno; tag core.hook_module_exec_filter | 8.2.1+ (demofiltermodules.php:79) | NO |
| demomoduleroutes | URLs amigables propias en el FRONT | moduleRoutes | 8.0.0–9.99.99 (demomoduleroutes.php:30) | SI |
| demojsrouting | Componente JS Router del BO para generar URLs Symfony desde JS | Ninguno; usa $tabs | 9.0.0+ (demojsrouting.php:47) | NO (pero el Router SI es usable en legacy) |
| democonsolecommand | Comando bin/console propio | Ninguno; tag console.command | 9.0.0+ (democonsolecommand.php:34) | NO |
| demodoctrine | CRUD completo con Doctrine ORM + entidad lang + grid + form identifiable object | displayHome | 9.0.0+ (demodoctrine.php:40) | NO |
| demooverrideobjectmodel | Anadir un campo a Manufacturer por override + ALTER TABLE. El propio README lo marca como antipatron | Ninguno (Installer.php:60 array vacio) | 9.0.0+ (demooverrideobjectmodel.php:38); el mecanismo es identico en 1.7/8/9 | Practicamente si |
| api_module | Exponer recursos propios en la nueva API (API Platform) | Ninguno; atributos #[ApiResource] + tags de servicio | 9.0.0–9.99.99 (api_module.php:42) | NO |
| dashexample | Integracion con el Dashboard Symfony de PS 9.2. Modulo "Symfony-light": renderiza Twig sin src/ ni services.yml | displayAdminDashboardZoneOne/Two/Three, ...Top, ...Bottom, ...Toolbar | 9.2.0+ (dashexample.php:46) + feature flag dashboard | SI |
| demovieworderhooks | Catalogo de hooks de la pagina "Ver pedido": PESTANA (TabLink+TabContent), zonas, botones de la barra de acciones, preview del listado | displayAdminOrderTabLink, displayAdminOrderTabContent, displayAdminOrderMain, ...MainBottom, ...Side, ...SideBottom, displayAdminOrder, displayAdminOrderTop, displayAdminOrderCreateExtraButtons, displayOrderPreview, actionGetAdminOrderButtons | 9.0.0–9.99.99 (demovieworderhooks.php:54) | Los hooks si; Doctrine/servicios no |
| demowsextend | Recurso propio en el Webservice clasico /api | addWebserviceResources | 1.7.8+ (README; no declara compliancy) | SI |
| example_module_mailtheme | Temas de email: anadir tema, anadir/reemplazar layouts, inyectar variables, transformar el HTML final | actionListMailThemes, actionBuildMailLayoutVariables, actionGetMailLayoutTransformations | 9.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 esdisplayAdminProductsExtra. - V2 (nueva): formulario Symfony (
EditProductFormType), PS 8.1+ y 9.x. Aqui vivenactionProductFormBuilderModifier,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']—FormBuilderInterfaceraiz 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 raiz | block prefix | Hooks |
|---|---|---|
EditProductFormType | product | actionProductFormDataProviderData, actionProductFormBuilderModifier |
CreateProductFormType (modal de alta) | create_product | actionCreateProductFormDataProviderDefaultData |
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.formTypeacepta cualquier FormType de Symfony o dePrestaShopBundlepor FQCN: por eso NO hace faltaservices.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).
| Capacidad | Como | Evidencia |
|---|---|---|
| Modificar VALORES de cualquier formulario Symfony del BO | action<BlockPrefix>FormDataProviderData / ...DefaultData | demoformdataproviders.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 formulario | action<Entidad>FormDataProviderData ($params['data'] llega por referencia) | demoextrafield.php:731-750 |
| PERSISTIR tras guardar | actionAfterCreate<Entidad>FormHandler / actionAfterUpdate<Entidad>FormHandler ($params['id'], $params['form_data']) | demoextendsymfonyform1.php:215-263 |
| FormType propio SIN dependencias de constructor | class X extends \Symfony\Component\Form\AbstractType en classes/ con require_once | services.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 Module | dashexample.php:143-149 (modulo SIN src/) |
| PESTANA en una pagina Symfony del BO | Par display...TabLink + display...TabContent devolviendo HTML plano | demovieworderhooks/views/templates/admin/tracking_link.html.twig:12-25 |
| Columnas, filtros y acciones en grids del core | action<GridId>GridDefinitionModifier, ...GridQueryBuilderModifier, ...GridDataModifier, ...GridFilterFormModifier, ...GridPresenterModifier | demoextendgrid.php:84-122 |
| Inyectar CSS/JS en el BO | actionAdminControllerSetMedia (+ 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 FRONT | hookModuleRoutes | demomoduleroutes.php:57-88 |
Recurso en el Webservice /api | addWebserviceResources + $webserviceParameters | demowsextend.php:74-83 |
| SEO: JSON-LD y meta title/description | actionFrontControllerSetVariables mutando $params['templateVars'] | demoseo.php:51-114 |
| Pestanas extra en la ficha de producto del FRONT | displayProductExtraContent | demoproductextracontent.php:54-63 |
| Temas / layouts / transformaciones de email | actionListMailThemes, actionBuildMailLayoutVariables, actionGetMailLayoutTransformations | example_module_mailtheme.php:145-276 |
| Override de plantillas Twig del BO | Convencion de ruta: views/PrestaShop/<misma ruta que el core>/x.html.twig — cero PHP | demoextendtemplates 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 BO | window.prestashop.instance.router.generate('ruta_del_core') — disponible en cualquier pagina del BO | demojsrouting/views/js/demo-page.js:19 |
3.2 EXIGE OBLIGATORIAMENTE src/ + composer.json (PSR-4) + config/services.yml (y a veces routes.yml)
| Capacidad | Por que |
|---|---|
| Crear un GRID propio | El 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 propias | Todo 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 inyectadas | TranslatorAwareType exige parent: 'form.type.translatable.aware' + tags: [{name: form.type}]. demosymfonyformsimple/config/services.yml:11-15 |
Core\Form\Handler + DataConfiguration/FormDataProvider | Es un servicio; su 5o argumento es el hookName que genera action<X>Form / action<X>Save |
FormBuilder/FormHandler de IdentifiableObject | Se 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 consola | Unicamente el tag console.command. No hay API legacy |
| Filtrar modulos por hook | Tag 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 KernelEvents | autoconfigure lo registra como listener |
| Configuracion multitienda con checkboxes "ajuste especifico" | Heredar AbstractMultistoreConfiguration (3 servicios del core inyectados) + getParent() devolviendo MultistoreConfigurationType::class |
#[AdminSecurity] y roles automaticos | Infraestructura de seguridad Symfony; en legacy es Tab + tokens |
Equivalencias legacy directas:
| Symfony | Legacy |
|---|---|
| Grid propio | ModuleAdminController + $this->fields_list / renderList() (HelperList) |
| Ruta + accion AJAX del grid | JS inyectado por actionAdminControllerSetMedia que hace $.post contra un ModuleAdminController con su token (Link::getAdminLink('AdminMiAccion')) |
Core\Form\Handler + DataConfiguration | getContent() con Tools::isSubmit() -> guardar -> displayConfirmation()/displayError(); un unico HelperForm con pestanas |
Configuration::set(..., ['html' => true]) | Configuration::updateValue($key, $value, true) |
SqlLoader / DBAL | Db::getInstance()->execute() |
| Doctrine ORM | ObjectModel en classes/ |
bin/console | ModuleFrontController 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
| Parametro | Rol |
|---|---|
_legacy_controller | Nombre logico usado por el sistema de PERMISOS; al declararlo se crean los roles del controlador (permite controlador seguro sin tab visible) |
_legacy_link | Permite 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
- Los README mienten.
demoextendgrid/README.md:15dice "1.7.7 to 8.1" pero el codigo es PS 9 (PrestaShopAdminController, iconopush_pin).demomultistoreform/README.md:47dice "1.7.8 a 8.1" pero declaramin 9.0.0.demodoctrine/README.md:5dice "1.7.7 and above" y la linea 13 del mismo fichero dice "9.0.0 and above". Fiarse solo deps_versions_compliancy. config.xmlcasi nunca declara version de PS. La compliancy vive en el constructor. Y hay desincronizaciones internas:demoextendgrid/config.xmldeclara 1.1.0 y el.php1.2.0;demodoctrine/config.xml1.0.0 vs.php2.0.0.- PS 8 vs PS 9 en controladores: PS 9 usa
PrestaShopBundle\Controller\Admin\PrestaShopAdminController+ inyeccion por argumento con#[Autowire(service: 'id')]. PS 8 usabaFrameworkBundleAdminController+$this->get('id'). Este codigo NO es portable tal cual a 8.x. demoextrafieldes 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 trioFormBuilderModifier+FormDataProviderData+AfterCreate/UpdateFormHandlercon tabla propia.demoseoexige 9.2.0 para losstructured_data, aunque el hook exista desde 1.7.5.0.dashexamplerequiere ademas el feature flagdashboardactivado en Parametros Avanzados > Nuevas funcionalidades experimentales.
5.2 Formularios
$params['id']esnullen la pantalla de creacion. Comprobarlo siempre antes de cargar datos.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.- El
FormBuilderModifierSOLO pinta el campo; no guarda nada. Hay que registrar ademasactionAfterCreate...yactionAfterUpdate.... actionProductFormDataProviderDefaultDatano se dispara en el alta de producto de PS 9.1 (el modal usa block prefixcreate_product). Ver 2.7.- Solo
datayoptionsviajan por referencia en los hooks de FormDataProvider;idva por valor. - Un formulario montado a mano con
form.factorypierde los hooks. LosFormDataProvider*los dispara elFormBuilderde factoria del core. - 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 enFormDataHandlerInterfaceaparte. Elegir la equivocada es error de compilacion del contenedor.
- HelperForm/Symfony: cada campo anadido en
renderForm()DEBE tener valor enfields_valueo Smarty lanzaUndefined array key. block_prefix != entityNamerompe la inyeccion automatica de extra properties. Caso documentado:ManufacturerAddressType(prefixmanufacturer_address) frente a la entidadaddress— el campo solo puede ir al grid, no al formulario.GeoCoordinatesTypese anade como'coordinates'pero en$form->getData()aparece comolatitude/longitudeplanos. Inspeccionar siempre la estructura real degetData()antes de escribir el DataConfiguration.- Sin
form_themedel UI Kit los campos salen rotos. Hay que ponerlo enconfigureOptions()y con{% form_theme %}en el Twig. - Bug latente que NO hay que copiar (
demoproductform): el handler compruebanull !== $command->getCustomerField()pero la propiedad esprivate string $customerField = ''— nunca es null, asi que la condicion es siempre true ysetFieldsToUpdate()no filtra nada. Tipar?string = null. Evidencia:UpdateCustomProductCommand.php:45, 59-62vsUpdateCustomProductCommandHandler.php:57-60. - Antipatron en
demomultistoreform: sobrescribevalidateConfiguration()devolviendotruea secas, anulando elOptionsResolverdel padre. No copiarlo. - Ruta de guardado multitienda: debe aceptar
PATCH. La extension fuerza$builder->setMethod(Request::METHOD_PATCH)cuando hay checkboxes multitienda. Si la ruta solo declaraPOST-> 405 imposible de diagnosticar. Evidencia:MultistoreConfigurationTypeExtension.php:41-42. - Varios formularios en una pagina: en las acciones de guardado se comprueba solo
isSubmitted()(noisValid()), porque tras el redirect el usuario no veria los errores de constraint; la validacion se hace en el DataConfiguration devolviendo errores.
5.3 Grids
- Sin
GridQueryBuilderModifierla columna nueva sale vacia. Y usarIF(x IS NULL, 0, x)o el toggle revienta en filas sin registro. - Filtrar por "No" requiere
orWhere(... IS NULL). GRID_IDunico.demo_gridusa'product', que COLISIONA con el grid nativo (mismofilterIden la tabla de filtros del empleado y mismo nombre de hookactionProductGridDefinitionModifier). En modulo real usarecom_misregistros.- El Grid necesita DOS rutas con el mismo path: GET (index) y POST (
searchAction->buildSearchResponse). Sin la POST, el formulario de filtros da 405. SqlFilterscon concatenacion insegura:demomultistoreform/src/Grid/Query/ContentBlockQueryBuilder.php:49,71haceimplode()de IDs directamente en el WHERE. UsarsetParameter/createNamedParameter.GridFactorydebe serpublic: truepara inyectarlo por id de servicio.
5.4 Instalacion / servicios
- Durante
install()el contenedor del modulo aun no esta compilado:$this->get(MiServicio::class)lanza excepcion. Patron try/catch + construccion manual (ver 4.3). - Durante
install()las entidades Doctrine no estan mapeadas: crear tablas con SQL crudo, nunca con elEntityManager. require_once vendor/autoload.php: obligatorio si la clase principal referencia clases desrc/antes de que exista el contenedor (constantesTAB_CLASS_NAME,InstallerFactory).demoextendsymfonyform1y3NO lo hacen y funcionan porque PrestaShop carga el autoloader del modulo;api_modulelo hace confile_exists(defensivo);demovieworderhookslo hace incondicional. Recomendacion: incluirlo."config": {"prepend-autoloader": false}encomposer.json: importante para que el autoloader del modulo no se anteponga al del nucleo y provoque conflictos de version de librerias.public: truees obligatorio en todo servicio que se consuma con$this->get('id')desde un hook.registerHook([])con array vacio devuelve falsy y hace fallar el install.Tab::getIdFromClassNamepuede lanzarNonUniqueResulten PS 9 con tabs duplicadas. UsarDb::getValuepara comprobar existencia.hookNamegenerico enCore\Form\Handler:demomultistoreformpasa'ConfigurationForm', generandoactionConfigurationFormForm/Save— colisionables. Usar un nombre unico (EcomMiModuloConfiguration).
5.5 Plantillas y traducciones
- Override de
views/PrestaShop/Admin/layout.html.twiges GLOBAL a todo el back-office y solo un modulo puede ganar por fichero. Dos modulos que sobrescriban el mismo twig colisionan. Redefinir la macroalert()cambia el HTML de TODAS las alertas del BO. {{ parent() }}es obligatorio al sobrescribir{% block javascripts %}/{% block stylesheets %}, o se pierden jQuery y los componentes del BO.- Inconsistencia real de dominios de traduccion en el repo oficial: algunas plantillas Twig usan
Module.<Studly>.Admin(singular) y el PHP usaModules.<Studly>.Admin(plural). Verificar cual consume la instalacion. demoextrafield/README.md:95remite aregisterTranslationWordings(), metodo que NO existe en el codigo (fichero leido integro, 812 lineas). No copiar esa referencia.{displayPrice price=... currency=...}NO existe en PS 1.7/8/9 (era de 1.6) -> Fatal error. Formatear en PHP.demodoctrine/views/templates/front/home.tpl:30-31imprime sin|escape. Viola las reglas de este proyecto.- Los ejemplos usan
{l s='...' mod='modulo'}(sistema LEGACY) porque no declaranisUsingNewTranslationSystem(). Si tu modulo lo declaratrue,mod=NO leera los.xlf. democontrollertabs/views/templates/admin/layout.html.twig:74,79carga highlight.js desde un CDN externo. Evitar en produccion.
5.6 Rendimiento / seguridad
demoextrafieldescribe en BD dentro de un hook de FRONT (displayFooterProduct,demoextrafield.php:595-631): unUPDATEpor cada visita de ficha. Util como demo, peligroso en produccion.actionAdminControllerSetMediase dispara en TODOS los controladores del BO. Filtrar por$this->context->controller->controller_namey porTools::getValue('action')(el mismo controlador sirve listado, detalle y alta). Nunca usar$controller::class.core.hook_module_exec_filterse ejecuta en cada ejecucion de hook: cortocircuitar el BO condefined('_PS_ADMIN_DIR_').- Bug real en
api_module:HorseProvider.php:56usa$operation instanceof Patchpero elusede la linea 33 solo importaPut— elinstanceofresuelve a una clase inexistente del namespace local y nunca coincide. demoextendsymfonyform2/config/routes.yml:6-7declararequirementssobrecategoryIdcuando el parametro real essupplierId(copy/paste erroneo: el requirement no aplica). Y el mismo modulo usa dos dominios de traduccion distintos (Modules.DemoExtendSymfonyForm2.Adminen :55-56 vsModules.DemoExtendSymfonyFormen :95).ProductFormModifier.php:111-122: la variable se llama$headerFormBuilderpero apunta a'footer'. Ruido de copy/paste del repo oficial.- El
.sqlpartido por lineas (preg_split('/\r\n|\r|\n/')) solo funciona con UNA sentencia por linea. No parte por;.
5.7 Multitienda
$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.getShopConstraint()devuelvenullen contexto "todas las tiendas" y elShopConstraintconcreto en contexto tienda/grupo.- 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) | SI | displayAdminProductsExtra + Smarty |
| Campo editable en una pestana existente del producto V2 | SI | actionProductFormBuilderModifier + $this->get('form.form_builder_modifier') |
| Pestana nueva en el producto V2 | SI | addAfter sobre el builder RAIZ + AbstractType sin dependencias en classes/ |
| Campo custom producto V2 + grid + API, en PS 9.2 | SI | registerExtraProperty() |
| Guardar ese campo | SI | actionAfterUpdateProductFormHandler + ObjectModel en classes/ |
| Solo cambiar valores por defecto / precargados | SI | action<X>FormDataProvider*Data |
| Anadir columna/filtro/accion a un grid del core | SI (la accion, con ModuleAdminController+AJAX) | action<X>GridDefinitionModifier + ...QueryBuilderModifier |
| Listado propio en el BO | SI | ModuleAdminController + HelperList |
| CRUD Symfony con Grid + Form del core | NO | src/ + composer.json + services.yml + routes.yml |
Entidades Doctrine, CQRS propio, API Platform, comando bin/console, decorar un controlador, filtrar modulos por hook | NO | Idem |
| Modulo que debe funcionar en 8.x y 9.x | Obligatoriamente legacy | Nada 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:
CreateProductFormTypeusa el block prefixcreate_product, asi que el hook seriaactionCreateProductFormBuilderModifier. - Si el theme o el hook fallan, la pestana sale vacia. Conviene que el modulo
tambien pinte en
displayAdminProductsExtracomo 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'):
| Ruta | Pagina |
|---|---|
admin_product_form | clasica (V1) |
admin_products_edit | nueva (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
| Pagina | Donde pintar | Que 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 conTools::getValue()desdehookActionProductUpdate(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(comodemo_module_custom_fieldendemoproductform), y leerlos enactionAfterUpdateProductFormHandler, 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 llamaproduct). Ningunservices.ymlnecesario.
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
| Pagina | Donde va el bloque | Que devuelve vacio |
|---|---|---|
| V1 | displayAdminProductsMainStepLeftColumnBottom (pagina principal) | displayAdminProductsExtra |
| V2 | pestana propia via actionProductFormBuilderModifier | displayAdminProductsExtra |
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |