Extra Properties (Custom Fields)
Relevant source files
The following files were used as context for generating this wiki page:
- src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php
- admin-dev/themes/new-theme/js/pages/extra-property-definition/form/index.ts
- tests/Integration/PrestaShopBundle/ApiPlatform/CQRSOpenApiFactoryTest.php
- README.md
- tests/UI/package.json
- src/Core/ExtraProperty/ExtraPropertyRegistry.php
- src/Core/Domain/ExtraProperty/ValueObject/ExtraPropertyDefinitionId.php
Extra Properties allow modules to declare and manage custom data fields for existing entities within the PrestaShop ecosystem. These properties extend the base data structures of entities like products or categories without modifying the core database schema directly. The system supports various data types, multi-language scopes, and automatic documentation through the API.
Sources: src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:23-28, tests/Integration/PrestaShopBundle/ApiPlatform/CQRSOpenApiFactoryTest.php:571-576
Architecture and Components
The Extra Properties system consists of a registry for definitions, a persistence layer, and adapters that integrate these properties into the Back Office (BO) forms and the OpenAPI documentation.
Core Data Structures
Extra Properties are defined by several key attributes:
- Definition: Contains the entity name, property name, and technical module name.
- Type: Defines the data format (e.g., INT, BOOL, FLOAT, DATE, JSON, CHOICE, STRING).
- Scope: Determines if the value is common to all languages or localized (LANG scope).
- Shop Association: Restricts properties to specific shop contexts in multishop environments.
Sources: src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:127-140, tests/Integration/PrestaShopBundle/ApiPlatform/CQRSOpenApiFactoryTest.php:578-608
Component Diagram
The following diagram illustrates the relationship between the definition repository, the API schema adapter, and the entity resources.
The ExtraPropertyDefinitionRepository provides the definitions used by the ExtraPropertiesSchemaAdapter to inject custom fields into the synthetic extraProperties sub-object of the API.
Sources: src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:48-52, tests/Integration/PrestaShopBundle/ApiPlatform/CQRSOpenApiFactoryTest.php:572-574
API Integration
The system injects a synthetic extraProperties property into the OpenAPI schema for relevant resources. Documentation only appears on an endpoint if the definition's associatedApis matches the endpoint's URI template.
Data Organization in API
The extraProperties sub-object follows a hierarchical grouping:
- Module Technical Name: Properties are grouped by the module that declared them.
- Property Name: The snake_case name of the custom field.
- Localized Values: Fields with
LANGscope are documented as locale-indexed objects (e.g.,{"en-US": "value"}).
Sources: src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:23-28, src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:121-125
API Schema Adaptation Flow
The adapter filters definitions based on the URI template and HTTP method (POST, PUT, PATCH for write operations) before appending them to the resource schema.
Sources: src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:60-104
User Interface (Back Office) Integration
The Back Office form for Extra Property Definitions uses progressive enhancement. If JavaScript is disabled, the system renders plain Symfony collection entries. When enabled, a TypeScript-based engine enhances the form with specialized widgets.
Key UI Features
- Placement Lists: Manages where the custom field appears in forms, grids, or APIs.
- Constraint Builder: Allows developers to define validation rules for the custom fields.
- API Method Chips: Provides a visual interface for selecting HTTP methods for API endpoints.
- Anchor Tree: Enhances form placement selection with tree-based navigation.
- Shop Association Trees: Handles multishop visibility using a
ChoiceTreecomponent.
Sources: admin-dev/themes/new-theme/js/pages/extra-property-definition/form/index.ts:33-75
Data Types and Schema Mapping
| Property Type | OpenAPI Type | Notes |
|---|---|---|
INT | integer | |
BOOL | boolean | |
FLOAT | number | |
DATE | string | Format: date-time |
JSON | object | Defaults are decoded from strings |
CHOICE | string | Includes enum values |
STRING | string | Default fallback |
LANG Scope | object | Locale-indexed, e.g., {"en-US": "..."} |
Sources: src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:143-162, tests/Integration/PrestaShopBundle/ApiPlatform/CQRSOpenApiFactoryTest.php:635-645
Development and Testing
Developers can persist definitions directly for testing purposes using the ExtraPropertyDefinitionWriterInterface. The definitions are documented in the generated OpenAPI schema even if the module is not fully installed, provided they are in the repository.
Configuration and Setup
Properties can be flagged as required, which adds them to the required array in the OpenAPI module object. Default values are included in the API contract, and JSON defaults are decoded so the documentation matches the object shape returned by the API.
Sources: src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:111-118, tests/Integration/PrestaShopBundle/ApiPlatform/CQRSOpenApiFactoryTest.php:572-576
Testing Commands
The UI tests for these features are managed via Playwright and Mocha.
# Run sanity tests including Extra Property UI components
npm run test:sanity
Sources: tests/UI/package.json:28
The Extra Properties system provides a robust mechanism for extending PrestaShop entities. By separating property definitions from core logic and providing automatic API documentation, it ensures that module-driven extensions remain discoverable and standardized across the platform.
Sources: src/PrestaShopBundle/ApiPlatform/OpenApi/Adapter/ExtraPropertiesSchemaAdapter.php:23-40, tests/Integration/PrestaShopBundle/ApiPlatform/CQRSOpenApiFactoryTest.php:571-578