Add the Extra Properties component documentation

[jolelievre]

Questions	Answers
Branch?	9.x
Description?	Adds the developer documentation of the Extra Properties component introduced in PrestaShop 9.2, and links it from the 9.2 core updates page.
Fixed ticket?	Fixes PrestaShop/PrestaShop#41429
Sponsor company	PrestaShop SA

New section development/components/extra-properties/:

• Index: generic behaviour of the component. Covers the concept, column-based storage and scopes, supported types, where values surface (ObjectModel, Front Office Smarty, Back Office forms and grids, Admin API), validation, default values, multistore, supported entities and limitations.
• Register extra properties from a module: registration in install() with every ExtraPropertyDefinition argument, error handling, uninstall with or without dropping data, conflicts, re-registration on upgrade, reading and writing values, migrating from a custom extra table. Examples come from the demoextraproperty example module.
• Manage extra properties from the Back Office: the Advanced Parameters > Extra Properties page (grid, form cards, module-owned definitions), the related grid hooks and the /extra-property-definitions Admin API endpoints.

The notice in modules/core-updates/9.2.md now links to the new section, and the example module link points to its new name demoextraproperty.

[mattgoud]

Thorough page. I checked it against 9.2.x and ps_apiresources dev. The argument table, enums, registry codes, placement grammar, constraint allowlist, BO page, grid hooks and the definitions endpoints all match. Five points to fix, three of them reproduced on a 9.2.x shop with demoextraproperty installed.

Should fix

1. register-from-module.md:100: registerExtraProperty() does not always return false, the constructor exceptions listed at :92 can come out of it too. Module::registerExtraProperty() calls withModuleName() before its try (classes/module/Module.php:1255 vs :1261). The "domain must belong to the module" check only runs once the module name is set, so a definition built without moduleName (the documented pattern) and a foreign labelDomain makes it throw. Reproduced: labelDomain: 'Modules.Othermodule.Admin' throws InvalidExtraPropertyDefinitionException ("labelDomain … of a module-owned definition must belong to the module"). The catch (ExtraPropertyRegistryException) sample at :108-114 does not catch it either. I opened PrestaShop/PrestaShop#43017 to fix it in the core (move the injection inside the try, unregisterExtraProperty() has the same shape). Until it lands, the page should not promise false for that case.
2. register-from-module.md:160 lists "Scope change" under DESTRUCTIVE_SCHEMA_CHANGE. The scope is checked first and refused with SCOPE_CONFLICT (ExtraPropertyRegistry.php:133). Reproduced: re-registering a common property as shop returns false with "already registered with scope "common", cannot also register with scope "shop"". The codes table at :120 is right.
3. _index.md:111: {$customer->extra_properties…} is the one variable name that fails on the Front Office. The $customer global is a presented array. Rendered with Smarty against a presented customer: {$customer->extra_properties.demoextraproperty.qa_note} raises "Attempt to read property "extra_properties" on array", while {$customer.extra_properties…} and {$customerObjectModel->extra_properties…} both render the value. Suggestion: use another variable name in the raw ObjectModel example, and add the $customer global to the list at :104, since ObjectPresenter adds extra_properties to it too. On the same line, "Order detail" exposes the order's properties (OrderDetailLazyArray uses Order::class), so "Order (also on the order detail page)" is more accurate.
4. _index.md:100: "only the Front Office filters on displayFront" misses what Context::isFrontOfficeContext() counts as Front Office: everything that is not a BO/API controller or CLI, so the legacy webservice and HTTP-run crons or scripts too (classes/Context.php:313-342). It is worth one sentence here and in the displayFront row (register-from-module.md:75).
5. register-from-back-office.md:112: a <!-- TODO screenshot: … --> is left.

Nits (optional)

• _index.md:189: "an INT must be numeric", but it must be an integer (^-?\d+$), "1.5" is refused.
• _index.md:255: a table without an ObjectModel works too, the table falls back to the entity name.
• The warning that required adds no server-side check appears three times. One place plus links would be enough.

[jolelievre]

Thanks for the review, all points applied in ddb4cbe except these:

1. registerExtraProperty() returning false: the fix of [Extra Properties] Module::registerExtraProperty() throws instead of returning false on an invalid label or description domain PrestaShop#43017 is included in Complete the extra property tests and clean the ExtraProperty AI context PrestaShop#43014 (the module name injection moved inside the try, in both registerExtraProperty() and unregisterExtraProperty(), with an integration test). The page documents the fixed behaviour, so it keeps promising false. The direct registry sample still only catches ExtraPropertyRegistryException: an InvalidExtraPropertyDefinitionException there is a definition to fix in the code, not a reason to handle at runtime.
2. The TODO screenshot is still there, it will be taken on a multistore shop before merging.

About point 3, the Front Office templates section is rewritten: presented arrays (lazy array presenters and ObjectPresenter, which covers $customer, CMS pages and categories, carriers, order addresses...) use the dot syntax, a raw ObjectModel uses -> for the first level only, and a hand-built array has no extra_properties key.

[jolelievre]

Point 5 is done in dc9a659: the TODO comment is gone, replaced with a screenshot of the View page of a module-owned property taken on a multistore shop (img/extra-properties-view-module-owned.png). It shows the read-only banner, a disabled card and the editable Store association field.