Skip to content

Commit 82dbe35

Browse files
julitafalconduszajulitafalcondusza
authored
IBX-9147: Symbol attribute type described in Developer Documentation - v5.0 (#2826)
* Symbol attribute added * updates * symbol attribute type - v5 * PHP & JS CS Fixes * symbol_attribute_type.md moved to Attributes folder * fix in mkdocs * fix in symbolattribute_criterion.md * composer requirement added --------- Co-authored-by: julitafalcondusza <[email protected]>
1 parent 7c32194 commit 82dbe35

File tree

7 files changed

+167
-2
lines changed

7 files changed

+167
-2
lines changed

‎code_samples/back_office/search/src/Query/SymbolAttributeTypeQuery.php‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?php declare(strict_types=1);
2+
3+
use Ibexa\Contracts\ProductCatalog\Values\Product\ProductQuery;
4+
use Ibexa\Contracts\ProductCatalogSymbolAttribute\Search\Criterion\SymbolAttribute;
5+
6+
$query = new ProductQuery();
7+
$query->setFilter(new SymbolAttribute('ean', ['5023920187205']));
8+
/** @var \Ibexa\Contracts\ProductCatalog\ProductServiceInterface $productService */
9+
$results = $productService->findProducts($query);

‎code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace App\PIM\Symbol\Format\Checksum;
6+
7+
use Ibexa\Contracts\ProductCatalog\Values\AttributeDefinitionInterface;
8+
use Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface;
9+
10+
final class LuhnChecksum implements ChecksumInterface
11+
{
12+
public function validate(AttributeDefinitionInterface $attributeDefinition, string $value): bool
13+
{
14+
$digits = $this->getDigits($value);
15+
16+
$count = count($digits);
17+
$total = 0;
18+
for ($i = $count - 2; $i >= 0; $i -= 2) {
19+
$digit = $digits[$i];
20+
if ($i % 2 === 0) {
21+
$digit *= 2;
22+
}
23+
24+
$total += $digit > 9 ? $digit - 9 : $digit;
25+
}
26+
27+
$checksum = $digits[$count - 1];
28+
29+
return $total + $checksum === 0;
30+
}
31+
32+
/**
33+
* Returns an array of digits from the given value (skipping any formatting characters).
34+
*
35+
* @return int[]
36+
*/
37+
private function getDigits(string $value): array
38+
{
39+
$chars = array_filter(
40+
str_split($value),
41+
static fn (string $char): bool => $char !== '-'
42+
);
43+
44+
return array_map('intval', array_values($chars));
45+
}
46+
}

‎composer.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,8 @@
7070
"ibexa/tree-builder": "~5.0.x-dev",
7171
"ibexa/discounts": "~5.0.x-dev",
7272
"ibexa/discounts-codes": "~5.0.x-dev",
73-
"ibexa/core-search": "~5.0.x-dev"
73+
"ibexa/core-search": "~5.0.x-dev",
74+
"ibexa/product-catalog-symbol-attribute": "~5.0.x-dev"
7475
},
7576
"scripts": {
7677
"fix-cs": "php-cs-fixer fix --config=.php-cs-fixer.php -v --show-progress=dots",

‎docs/pim/attributes/symbol_attribute_type.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
description: Create a symbol attribute type that enables for the efficient representation of string-based values while enforcing their format in product specifications.
3+
---
4+
5+
# Symbol attribute type
6+
7+
In product specifications, the symbol attribute type enables the efficient representation of string-based data and enforces their format.
8+
9+
This feature allows you to store standard product identifiers (such as EAN or ISBN) in the [Product Information Management](pim_guide.md) system.
10+
11+
## Build-in symbol attribute formats
12+
13+
The built-in symbol attribute formats in `ibexa/product-catalog-symbol-attribute` are listed below:
14+
15+
| Name | Description | Example |
16+
|-----------------|-----------------|-----------------|
17+
| Generic | Accepts any string value | #FR1.2 |
18+
| Generic (alphabetic characters only) | Accepts any string value that contais only letters | ABCD |
19+
| Generic (digits only) | Accepts any string value that contais only digits | 123456 |
20+
| Generic (alphanumeric characters only) | Accepts any string value that contains only letters or digits | 2N6405G |
21+
| Generic (hexadecimal digits only) | Accepts any string value that contains only hexadecimal digits (digits or A-F characters) | DEADBEEF |
22+
| EAN-8 | European Article Number (8 characters) | 96385074 |
23+
| EAN-13 | European Article Number (13 characters) | 5023920187205 |
24+
| EAN-14 | European Article Number (14 characters) | 12345678901231 |
25+
| ISBN-10 | International Standard Book Number (10 characters) | 0-19-852663-6 |
26+
| ISBN-13 | International Standard Book Number (13 characters) | 978-1-86197-876-9 |
27+
28+
!!! caution
29+
30+
Maximum length of the symbol value is 160 characters.
31+
32+
## Create custom symbol attribute format
33+
34+
Under the `ibexa_product_catalog_symbol_attribute.formats` key, you can use configuration to create your own symbol format.
35+
36+
See the example below:
37+
38+
``` yaml
39+
ibexa_product_catalog_symbol_attribute:
40+
formats:
41+
manufacturer_part_number:
42+
name: 'Manufacturer Part Number'
43+
pattern: '/^[A-Z]{3}-\d{5}$/'
44+
examples:
45+
- 'RPI-14645'
46+
- 'MSS-24827'
47+
- 'SEE-15444'
48+
```
49+
This following example specifies the format for a "Manufacturer Part Number", defined with the `manufacturer_part_number` identifier.
50+
51+
The pattern is specified using a regular expression.
52+
According to the pattern option, the attribute value:
53+
54+
- must be a string
55+
- begins with three capital letters (A-Z), followed by a hyphen ("-")
56+
- ends with five digits (0-9), with no other characters before or after
57+
58+
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.
59+
60+
To validate checksum of symbol:
61+
62+
1\. Create a class implementing the `\Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface` interface.
63+
64+
2\. Register the class as a service using the `ibexa.product_catalog.attribute.symbol.checksum` tag and specify the format identifier using the `format` attribute.
65+
66+
See below the example implementation of checksum validation using Luhn formula:
67+
68+
``` php
69+
[[= include_file('code_samples/pim/Symbol/Format/Checksum/LuhnChecksum.php') =]]
70+
```
71+
72+
Example service definition:
73+
74+
``` yaml
75+
services:
76+
App\PIM\Symbol\Format\Checksum\LuhnChecksum:
77+
tags:
78+
- name: ibexa.product_catalog.attribute.symbol.checksum
79+
format: my_format
80+
```
81+
The format attribute (`my_format`) is the identifier used under the `ibexa_product_catalog_symbol_attribute.formats` key.
82+
83+
## Search for products with given symbol attribute
84+
85+
You can use `SymbolAttribute` Search Criterion to find products by symbol attribute:
86+
87+
For more information, see [SymbolAttribute Criterion](symbolattribute_criterion.md).

‎docs/search/criteria_reference/product_search_criteria.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,4 +42,4 @@ Search Criterion let you filter product by specific attributes, for example, col
4242
|[RangeMeasurementAttributeMinimum](rangemeasurementattributeminimum_criterion.md)|Minimum value of product's measurement attribute|
4343
|[SelectionAttribute](selectionattribute_criterion.md)|Value of product's selection attribute|
4444
|[SimpleMeasurementAttribute](simplemeasurementattribute_criterion.md)|Value of product's measurement attribute|
45-
45+
|[SymbolAttribute](symbolattribute_criterion.md)|Value of product's symbol attribute|

‎docs/search/criteria_reference/symbolattribute_criterion.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
description: SymbolAttribute Criterion
3+
---
4+
5+
# SymbolAttributeCriterion
6+
7+
The `SymbolAttribute` Search Criterion searches for products by [symbol attribute](symbol_attribute_type.md).
8+
9+
## Arguments
10+
11+
- `identifier` - identifier of the format
12+
- `value` - array with the values to search for
13+
14+
## Example
15+
16+
### PHP
17+
18+
``` php
19+
[[= include_file('code_samples/back_office/search/src/Query/SymbolAttributeTypeQuery.php') =]]
20+
```

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -346,6 +346,7 @@ nav:
346346
- Products: pim/products.md
347347
- Attributes:
348348
- Date and Time attribute: pim/attributes/date_and_time.md
349+
- Symbol attribute type: pim/attributes/symbol_attribute_type.md
349350
- Product API: pim/product_api.md
350351
- Catalogs: pim/catalogs.md
351352
- Catalog API: pim/catalog_api.md
@@ -589,6 +590,7 @@ nav:
589590
- RangeMeasurementAttributeMaximum: search/criteria_reference/rangemeasurementattributemaximum_criterion.md
590591
- SimpleMeasurementAttribute: search/criteria_reference/simplemeasurementattribute_criterion.md
591592
- SelectionAttribute: search/criteria_reference/selectionattribute_criterion.md
593+
- SymbolAttribute: search/criteria_reference/symbolattribute_criterion.md
592594
- Order Search Criteria:
593595
- Order Search Criteria: search/criteria_reference/order_search_criteria.md
594596
- CompanyName: search/criteria_reference/order_company_name_criterion.md

0 commit comments

Comments
 (0)