Skip to content

Commit d465e43

Browse files
julitafalconduszajulitafalcondusza
committedOct 29, 2024
Symbol attribute type described
1 parent 7ab238a commit d465e43

File tree

4 files changed

+214
-0
lines changed

4 files changed

+214
-0
lines changed
 

‎docs/pim/symbol_attribute_type.md

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
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+
## Installation
10+
11+
### Download the bundle
12+
13+
To get the most recent stable version of this bundle, open a command terminal, navigate to your project directory, and run the following command:
14+
15+
``` bash
16+
ibexa/product-catalog-symbol-attribute
17+
```
18+
19+
!!! caution
20+
21+
To use this command requires you need to first install the Composer locally.
22+
For more information about Composer installation process, see [documentation](install_ibexa_dxp.md#get-composer).
23+
24+
### Enable the bundle
25+
26+
Flex enables and configures the `IbexaProductCatalogSymbolAttributeBundle` automatically.
27+
If you don't use it, you can manually enable Flex by adding the line below to the Kernel of your project:
28+
29+
``` php
30+
// config/bundles.php
31+
32+
return [
33+
// ...
34+
Ibexa\Bundle\ProductCatalogSymbolAttribute\IbexaProductCatalogSymbolAttributeBundle => ['all' => true],
35+
// ...
36+
];
37+
```
38+
39+
### Update database schema
40+
41+
To store symbol attribute values, the `IbexaProductCatalogSymbolAttributeBundle` needs an extra table.
42+
The following SQL query can be used to build the required database structure:
43+
44+
``` bash
45+
create table ibexa_product_specification_attribute_symbol (
46+
id int not null primary key,
47+
value varchar(255) null,
48+
constraint ibexa_product_specification_attribute_symbol_fk
49+
foreign key (id) references ibexa_product_specification_attribute (id)
50+
on update cascade on delete cascade
51+
) collate = utf8mb4_unicode_520_ci;
52+
53+
create index ibexa_product_specification_attribute_symbol_value_idx
54+
on ibexa_product_specification_attribute_symbol (value);
55+
```
56+
57+
### Create symbol attribute definition (optional)
58+
59+
Now, you're able to define symbol attributes at this point.
60+
61+
To create symbol attribute definition, in the back office, go to **Product catalog** -> **Attributes**, and click **Create**.
62+
Then, choose **Symbol** attribute type.
63+
64+
## Build-in symbol attribute formats
65+
66+
The built-in symbol attribute formats in `ibexa/product-catalog-symbol-attribute` are listed below:
67+
68+
| Name | Description | Example |
69+
|-----------------|-----------------|-----------------|
70+
| Generic | Accepts any string value | #FR1.2 |
71+
| Generic (alphabetic characters only) | Accepts any string value that contais only letters | ABCD |
72+
| Generic (digits only) | Accepts any string value that contais only digits | 123456 |
73+
| Generic (alphanumeric characters only) | Accepts any string value that contains only letters or digits | 2N6405G |
74+
| Generic (hexadecimal digits only) | Accepts any string value that contains only hexadecimal digits (digits or A-F characters) | DEADBEEF |
75+
| EAN-8 | European Article Number (8 characters) | 29033706 |
76+
| EAN-13 | European Article Number (13 characters) | 5023920187205 |
77+
| EAN-14 | European Article Number (14 characters) | 50239201872050 |
78+
| ISBN-10 | International Standard Book Number (10 characters) | 0-19-852663-6 |
79+
| ISBN-13 | International Standard Book Number (13 characters) | 978-1-86197-876-9 |
80+
81+
!!! caution
82+
83+
Maximum length of the symbol value is 160 characters.
84+
85+
## Create custom symbol attribute format
86+
87+
Under the `ibexa_product_catalog_symbol_attribute.formats` key, you can use configuration to create your own symbol format.
88+
89+
See the example below:
90+
91+
``` yaml
92+
ibexa_product_catalog_symbol_attribute:
93+
formats:
94+
manufacturer_part_number:
95+
name: 'Manufacturer Part Number'
96+
pattern: '/^[A-Z]{3}-\d{5}$/'
97+
examples:
98+
- 'RPI-14645'
99+
- 'MSS-24827'
100+
- 'SEE-15444'
101+
```
102+
103+
The following example specifies the format for a "Manufacturer Part Number."
104+
105+
According to the pattern option, the value:
106+
107+
- must be a string
108+
- uses a regular expression
109+
- begins with three capital letters
110+
- ends with five numbers
111+
112+
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.
113+
114+
To validate checksum of symbol:
115+
116+
1\. Implement `\Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface`:
117+
118+
``` php
119+
<?php
120+
121+
declare(strict_types=1);
122+
123+
namespace Ibexa\Contracts\ProductCatalogSymbolAttribute\Value;
124+
125+
use Ibexa\Contracts\ProductCatalog\Values\AttributeDefinitionInterface;
126+
127+
interface ChecksumInterface
128+
{
129+
public function validate(AttributeDefinitionInterface $attributeDefinition, string $value): bool;
130+
}
131+
```
132+
133+
2\. Register service with `ibexa.product_catalog.attribute.symbol.checksum` tag and format attribute.
134+
135+
See below the example implementation of checksum validation using Luhn formula:
136+
137+
``` php
138+
<?php
139+
140+
declare(strict_types=1);
141+
142+
namespace App\PIM\Symbol\Format\Checksum;
143+
144+
use Ibexa\Contracts\ProductCatalog\Values\AttributeDefinitionInterface;
145+
use Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface;
146+
147+
final class LuhnChecksum implements ChecksumInterface
148+
{
149+
public function validate(AttributeDefinitionInterface $attributeDefinition, string $value): bool
150+
{
151+
$digits = $this->getDigits($value);
152+
153+
$count = count($digits);
154+
$total = 0;
155+
for ($i = $count - 2; $i >= 0; $i -= 2) {
156+
$digit = $digits[$i];
157+
if ($i % 2 === 0) {
158+
$digit *= 2;
159+
}
160+
161+
$total += $digit > 9 ? $digit - 9 : $digit;
162+
}
163+
164+
$checksum = $digits[$count - 1];
165+
166+
return $total + $checksum === 0;
167+
}
168+
169+
/**
170+
* Returns an array of digits from the given value (skipping any formatting characters).
171+
*
172+
* @return int[]
173+
*/
174+
private function getDigits(string $value): array
175+
{
176+
$chars = array_filter(
177+
str_split($value),
178+
static fn (string $char): bool => $char !== '-'
179+
);
180+
181+
return array_map('intval', array_values($chars));
182+
}
183+
}
184+
```
185+
186+
## Search for products with given symbol attribute
187+
188+
You can use `SymbolAttribute` Search Criterion to find products by symbol attribute:
189+
190+
For more information, see [SymbolAttribute Criterion](symbolattribute_criterion.md).

‎docs/search/criteria_reference/product_search_criteria.md

+1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ Search Criterion let you filter product by specific attributes, for example: col
3636
|[ProductName](productname_criterion.md)|Product's name|
3737
|[RangeMeasurementAttributeMinimum](rangemeasurementattributeminimum_criterion.md)|Minimum value of product's measurement attribute|
3838
|[RangeMeasurementAttributeMaximum](rangemeasurementattributemaximum_criterion.md)|Maximum value of product's measurement attribute|
39+
|[SymbolAttribute](symbolattribute_criterion.md)|Value of product's symbol attribute|
3940
|[SimpleMeasurementAttribute](simplemeasurementattribute_criterion.md)|Value of product's measurement attribute|
4041
|[BasePrice](baseprice_criterion.md)|Product's base price|
4142
|[CustomPrice](customprice_criterion.md)|Product's custom price|

‎docs/search/criteria_reference/symbolattribute_criterion.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
description: SymbolAttribute Criterion
3+
---
4+
5+
# SymbolAttributeCriterion
6+
7+
The `SymbolAttribute` Search Criterion searches for products by symbol attribute.
8+
9+
## Arguments
10+
11+
- `value` - string representing the attribute value
12+
13+
## Example
14+
15+
### PHP
16+
17+
``` php
18+
$query = new ProductQuery();
19+
$query->setFilter(new SymbolAttribute('ean', '5023920187205'));
20+
// ...
21+
$results = $productService->findProducts($query);
22+
```

‎mkdocs.yml

+1
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,7 @@ nav:
338338
- Create product code generator: pim/create_product_code_generator.md
339339
- Create custom catalog filter: pim/create_custom_catalog_filter.md
340340
- Create custom name schema: pim/create_custom_name_schema_strategy.md
341+
- Use symbol attribute type: pim/symbol_attribute_type.md
341342
- Add remote PIM support: pim/add_remote_pim_support.md
342343
- Commerce:
343344
- Commerce: commerce/commerce.md

0 commit comments

Comments
 (0)
Please sign in to comment.