From d465e4348b32cec77c1002b80d61164d88b2d965 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Thu, 24 Oct 2024 14:56:19 +0200 Subject: [PATCH 1/3] Symbol attribute type described --- docs/pim/symbol_attribute_type.md | 190 ++++++++++++++++++ .../product_search_criteria.md | 1 + .../symbolattribute_criterion.md | 22 ++ mkdocs.yml | 1 + 4 files changed, 214 insertions(+) create mode 100644 docs/pim/symbol_attribute_type.md create mode 100644 docs/search/criteria_reference/symbolattribute_criterion.md diff --git a/docs/pim/symbol_attribute_type.md b/docs/pim/symbol_attribute_type.md new file mode 100644 index 0000000000..0224697e93 --- /dev/null +++ b/docs/pim/symbol_attribute_type.md @@ -0,0 +1,190 @@ +--- +description: Create a symbol attribute type that enables for the efficient representation of string-based values while enforcing their format in product specifications. +--- + +# Symbol attribute type + +In product specifications, the symbol attribute type enables the efficient representation of string-based data and enforces their format. + +## Installation + +### Download the bundle + +To get the most recent stable version of this bundle, open a command terminal, navigate to your project directory, and run the following command: + +``` bash +ibexa/product-catalog-symbol-attribute +``` + +!!! caution + + To use this command requires you need to first install the Composer locally. + For more information about Composer installation process, see [documentation](install_ibexa_dxp.md#get-composer). + +### Enable the bundle + +Flex enables and configures the `IbexaProductCatalogSymbolAttributeBundle` automatically. +If you don't use it, you can manually enable Flex by adding the line below to the Kernel of your project: + +``` php +// config/bundles.php + +return [ + // ... + Ibexa\Bundle\ProductCatalogSymbolAttribute\IbexaProductCatalogSymbolAttributeBundle => ['all' => true], + // ... +]; +``` + +### Update database schema + +To store symbol attribute values, the `IbexaProductCatalogSymbolAttributeBundle` needs an extra table. +The following SQL query can be used to build the required database structure: + +``` bash +create table ibexa_product_specification_attribute_symbol ( + id int not null primary key, + value varchar(255) null, + constraint ibexa_product_specification_attribute_symbol_fk + foreign key (id) references ibexa_product_specification_attribute (id) + on update cascade on delete cascade +) collate = utf8mb4_unicode_520_ci; + +create index ibexa_product_specification_attribute_symbol_value_idx + on ibexa_product_specification_attribute_symbol (value); +``` + +### Create symbol attribute definition (optional) + +Now, you're able to define symbol attributes at this point. + +To create symbol attribute definition, in the back office, go to **Product catalog** -> **Attributes**, and click **Create**. +Then, choose **Symbol** attribute type. + +## Build-in symbol attribute formats + +The built-in symbol attribute formats in `ibexa/product-catalog-symbol-attribute` are listed below: + +| Name | Description | Example | +|-----------------|-----------------|-----------------| +| Generic | Accepts any string value | #FR1.2 | +| Generic (alphabetic characters only) | Accepts any string value that contais only letters | ABCD | +| Generic (digits only) | Accepts any string value that contais only digits | 123456 | +| Generic (alphanumeric characters only) | Accepts any string value that contains only letters or digits | 2N6405G | +| Generic (hexadecimal digits only) | Accepts any string value that contains only hexadecimal digits (digits or A-F characters) | DEADBEEF | +| EAN-8 | European Article Number (8 characters) | 29033706 | +| EAN-13 | European Article Number (13 characters) | 5023920187205 | +| EAN-14 | European Article Number (14 characters) | 50239201872050 | +| ISBN-10 | International Standard Book Number (10 characters) | 0-19-852663-6 | +| ISBN-13 | International Standard Book Number (13 characters) | 978-1-86197-876-9 | + +!!! caution + + Maximum length of the symbol value is 160 characters. + +## Create custom symbol attribute format + +Under the `ibexa_product_catalog_symbol_attribute.formats` key, you can use configuration to create your own symbol format. + +See the example below: + +``` yaml +ibexa_product_catalog_symbol_attribute: + formats: + manufacturer_part_number: + name: 'Manufacturer Part Number' + pattern: '/^[A-Z]{3}-\d{5}$/' + examples: + - 'RPI-14645' + - 'MSS-24827' + - 'SEE-15444' +``` + +The following example specifies the format for a "Manufacturer Part Number." + +According to the pattern option, the value: + +- must be a string +- uses a regular expression +- begins with three capital letters +- ends with five numbers + +Certain formats, such as the International Standard Book Number (ISBN-10) and the European Article Number (EAN-13), contain checksum digits and are self-validating. + +To validate checksum of symbol: + +1\. Implement `\Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface`: + +``` php +getDigits($value); + + $count = count($digits); + $total = 0; + for ($i = $count - 2; $i >= 0; $i -= 2) { + $digit = $digits[$i]; + if ($i % 2 === 0) { + $digit *= 2; + } + + $total += $digit > 9 ? $digit - 9 : $digit; + } + + $checksum = $digits[$count - 1]; + + return $total + $checksum === 0; + } + + /** + * Returns an array of digits from the given value (skipping any formatting characters). + * + * @return int[] + */ + private function getDigits(string $value): array + { + $chars = array_filter( + str_split($value), + static fn (string $char): bool => $char !== '-' + ); + + return array_map('intval', array_values($chars)); + } +} +``` + +## Search for products with given symbol attribute + +You can use `SymbolAttribute` Search Criterion to find products by symbol attribute: + +For more information, see [SymbolAttribute Criterion](symbolattribute_criterion.md). \ No newline at end of file diff --git a/docs/search/criteria_reference/product_search_criteria.md b/docs/search/criteria_reference/product_search_criteria.md index bf977135fe..c92a0c3efa 100644 --- a/docs/search/criteria_reference/product_search_criteria.md +++ b/docs/search/criteria_reference/product_search_criteria.md @@ -36,6 +36,7 @@ Search Criterion let you filter product by specific attributes, for example: col |[ProductName](productname_criterion.md)|Product's name| |[RangeMeasurementAttributeMinimum](rangemeasurementattributeminimum_criterion.md)|Minimum value of product's measurement attribute| |[RangeMeasurementAttributeMaximum](rangemeasurementattributemaximum_criterion.md)|Maximum value of product's measurement attribute| +|[SymbolAttribute](symbolattribute_criterion.md)|Value of product's symbol attribute| |[SimpleMeasurementAttribute](simplemeasurementattribute_criterion.md)|Value of product's measurement attribute| |[BasePrice](baseprice_criterion.md)|Product's base price| |[CustomPrice](customprice_criterion.md)|Product's custom price| diff --git a/docs/search/criteria_reference/symbolattribute_criterion.md b/docs/search/criteria_reference/symbolattribute_criterion.md new file mode 100644 index 0000000000..d7ca5d4bbb --- /dev/null +++ b/docs/search/criteria_reference/symbolattribute_criterion.md @@ -0,0 +1,22 @@ +--- +description: SymbolAttribute Criterion +--- + +# SymbolAttributeCriterion + +The `SymbolAttribute` Search Criterion searches for products by symbol attribute. + +## Arguments + +- `value` - string representing the attribute value + +## Example + +### PHP + +``` php +$query = new ProductQuery(); +$query->setFilter(new SymbolAttribute('ean', '5023920187205')); +// ... +$results = $productService->findProducts($query); +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index a4396ef833..78e7ce939c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -338,6 +338,7 @@ nav: - Create product code generator: pim/create_product_code_generator.md - Create custom catalog filter: pim/create_custom_catalog_filter.md - Create custom name schema: pim/create_custom_name_schema_strategy.md + - Use symbol attribute type: pim/symbol_attribute_type.md - Add remote PIM support: pim/add_remote_pim_support.md - Commerce: - Commerce: commerce/commerce.md From b2e93eb7812fd0d257990d14e0b59301c4965b34 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Fri, 25 Oct 2024 12:39:47 +0200 Subject: [PATCH 2/3] Fixes after review --- .../Symbol/Format/Checksum/LuhnChecksum.php | 46 ++++++++ docs/pim/symbol_attribute_type.md | 102 +++++------------- .../symbolattribute_criterion.md | 14 ++- 3 files changed, 81 insertions(+), 81 deletions(-) create mode 100644 code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php diff --git a/code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php b/code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php new file mode 100644 index 0000000000..3e7e405774 --- /dev/null +++ b/code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php @@ -0,0 +1,46 @@ +getDigits($value); + + $count = count($digits); + $total = 0; + for ($i = $count - 2; $i >= 0; $i -= 2) { + $digit = $digits[$i]; + if ($i % 2 === 0) { + $digit *= 2; + } + + $total += $digit > 9 ? $digit - 9 : $digit; + } + + $checksum = $digits[$count - 1]; + + return $total + $checksum === 0; + } + + /** + * Returns an array of digits from the given value (skipping any formatting characters). + * + * @return int[] + */ + private function getDigits(string $value): array + { + $chars = array_filter( + str_split($value), + static fn (string $char): bool => $char !== '-' + ); + + return array_map('intval', array_values($chars)); + } +} \ No newline at end of file diff --git a/docs/pim/symbol_attribute_type.md b/docs/pim/symbol_attribute_type.md index 0224697e93..17baf14196 100644 --- a/docs/pim/symbol_attribute_type.md +++ b/docs/pim/symbol_attribute_type.md @@ -6,6 +6,8 @@ description: Create a symbol attribute type that enables for the efficient repre In product specifications, the symbol attribute type enables the efficient representation of string-based data and enforces their format. +This feature allows you to store standard product identifiers (such as EAN or ISBN) in the [Product Information Management](pim_guide.md) system. + ## Installation ### Download the bundle @@ -13,25 +15,20 @@ In product specifications, the symbol attribute type enables the efficient repre To get the most recent stable version of this bundle, open a command terminal, navigate to your project directory, and run the following command: ``` bash -ibexa/product-catalog-symbol-attribute +composer require ibexa/product-catalog-symbol-attribute ``` -!!! caution - - To use this command requires you need to first install the Composer locally. - For more information about Composer installation process, see [documentation](install_ibexa_dxp.md#get-composer). - ### Enable the bundle -Flex enables and configures the `IbexaProductCatalogSymbolAttributeBundle` automatically. -If you don't use it, you can manually enable Flex by adding the line below to the Kernel of your project: +Symfony Flex enables and configures the `IbexaProductCatalogSymbolAttributeBundle` automatically. +If you don't use it, you can manually enable this bundle by adding the line below to the Kernel of your project: ``` php // config/bundles.php return [ // ... - Ibexa\Bundle\ProductCatalogSymbolAttribute\IbexaProductCatalogSymbolAttributeBundle => ['all' => true], + Ibexa\Bundle\ProductCatalogSymbolAttribute\IbexaProductCatalogSymbolAttributeBundle::class => ['all' => true], // ... ]; ``` @@ -41,7 +38,7 @@ return [ To store symbol attribute values, the `IbexaProductCatalogSymbolAttributeBundle` needs an extra table. The following SQL query can be used to build the required database structure: -``` bash +``` sql create table ibexa_product_specification_attribute_symbol ( id int not null primary key, value varchar(255) null, @@ -100,88 +97,39 @@ ibexa_product_catalog_symbol_attribute: - 'SEE-15444' ``` -The following example specifies the format for a "Manufacturer Part Number." +This following example specifies the format for a "Manufacturer Part Number", defined with the `manufacturer_part_number` identifier. -According to the pattern option, the value: +The pattern is specified using a regular expression. +According to the pattern option, the attribute value: - must be a string -- uses a regular expression -- begins with three capital letters -- ends with five numbers +- begins with three capital letters (A-Z), followed by a hyphen ("-") +- ends with five numbers (0-9), with no other characters before or after Certain formats, such as the International Standard Book Number (ISBN-10) and the European Article Number (EAN-13), contain checksum digits and are self-validating. To validate checksum of symbol: -1\. Implement `\Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface`: - -``` php -getDigits($value); - - $count = count($digits); - $total = 0; - for ($i = $count - 2; $i >= 0; $i -= 2) { - $digit = $digits[$i]; - if ($i % 2 === 0) { - $digit *= 2; - } - - $total += $digit > 9 ? $digit - 9 : $digit; - } - - $checksum = $digits[$count - 1]; - - return $total + $checksum === 0; - } - - /** - * Returns an array of digits from the given value (skipping any formatting characters). - * - * @return int[] - */ - private function getDigits(string $value): array - { - $chars = array_filter( - str_split($value), - static fn (string $char): bool => $char !== '-' - ); - - return array_map('intval', array_values($chars)); - } -} +``` yaml +services: + App\PIM\Symbol\Format\Checksum\LuhnChecksum: + tags: + - name: ibexa.product_catalog.attribute.symbol.checksum + format: my_format ``` +The format attribute (`my_format`) is the identifier used under the `ibexa_product_catalog_symbol_attribute.formats` key. ## Search for products with given symbol attribute diff --git a/docs/search/criteria_reference/symbolattribute_criterion.md b/docs/search/criteria_reference/symbolattribute_criterion.md index d7ca5d4bbb..70bcfc9982 100644 --- a/docs/search/criteria_reference/symbolattribute_criterion.md +++ b/docs/search/criteria_reference/symbolattribute_criterion.md @@ -4,19 +4,25 @@ description: SymbolAttribute Criterion # SymbolAttributeCriterion -The `SymbolAttribute` Search Criterion searches for products by symbol attribute. +The `SymbolAttribute` Search Criterion searches for products by [symbol attribute](symbol_attribute_type.md). ## Arguments -- `value` - string representing the attribute value +- `identifier` - identifier of the format +- `value` - array with the values to search for ## Example ### PHP ``` php +setFilter(new SymbolAttribute('ean', '5023920187205')); -// ... +$query->setFilter(new SymbolAttribute('ean', ['5023920187205'])); +/** @var \Ibexa\Contracts\ProductCatalog\ProductServiceInterface $productService*/ $results = $productService->findProducts($query); ``` \ No newline at end of file From 2bc62c61fdda87bd6a32d5761c1f94349ce51bef Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Fri, 25 Oct 2024 10:43:47 +0000 Subject: [PATCH 3/3] PHP CS Fixes --- code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php b/code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php index 3e7e405774..2860f9aec9 100644 --- a/code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php +++ b/code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php @@ -43,4 +43,4 @@ private function getDigits(string $value): array return array_map('intval', array_values($chars)); } -} \ No newline at end of file +}