Technical architecture

#Products

#Common structure

Product contain inner fields and product values that are linked to attributes. All products have the same fields (identifier, label, family, groups, variant groups, categories, associations, status, dates of creation and update) while product values are flexible among products.

Let’s consider a bar product, without any product value, except its identifier sku. This product also contains:

  • an identifier

  • a family

  • several groups

  • a variant group

  • several categories

  • several associations related to groups, products and/or product models

  • several quantified associations related to products and/or product models

Its standard format would be the following:

array:10 [
  "identifier" => "bar"
  "family" => "familyA"
  "groups" => array:2 [
    0 => "groupA"
    1 => "groupB"
  ]
  "categories" => array:2 [
    0 => "categoryA"
    1 => "categoryB"
  ]
  "enabled" => false
  "values" => array:1 [
    "sku" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "bar"
      ]
    ]
  ]
  "created" => "2016-06-23T11:24:44+02:00"
  "updated" => "2016-06-23T11:24:44+02:00"
  "associations" => array:3 [
    "PACK" => array:3 [
      "groups" => array:0 []
      "products" => array:2 [
        0 => "foo"
        1 => "baz"
      ]
      "product_models" => array:0 []
    ]
    "UPSELL" => array:3 [
      "groups" => array:1 [
        0 => "groupA"
      ]
      "product_models" => array:0 []
      "products" => array:0 []
    ]
    "X_SELL" => array:3 [
      "groups" => array:1 [
        0 => "groupB"
      ]
      "product_models" => array:1 [
        0 => "productModelA"
      ]
      "products" => array:1 [
        0 => "foo"
      ]
    ]
  ]
  "quantified_associations" => array:1 [
    "PRODUCT_SET" => array:2 [
      "products" => array:1 [
        0 => array:2 [
          "identifier" => "productA"
          "quantity" => 3
        ]
      ]
      "product_models" => array:1 [
        0 => array:2 [
          "identifier" => "productModelA"
          "quantity" => 3
        ]
      ]
    ]
  ]
]

type

data structure

data example

notes

identifier

string

"bar"

it’s the identifier of the product

family

string

"familyA"

it represents the code of the
Akeneo\Pim\Structure\Component\Model\FamilyInterface

groups

array

[0 => "groupA", 1 => "groupB"]

it represents the code of the
Akeneo\Pim\Enrichment\Component\Category\Model\GroupInterface

variant_group

string

"variantA"

it represents the code of the
Akeneo\Pim\Enrichment\Component\Category\Model\GroupInterface

categories

array

[0 => "categoryA", 1 => "categoryB"]

it represents the code of the object
Akeneo\Tool\Component\Classification\Model\CategoryInterface

enabled

boolean

true

values

array

see below

created

string

"2016-06-13T00:00:00+02:00"

formatted to ISO-8601 (see above)

updated

array

"2016-06-13T00:00:00+02:00"

formatted to ISO-8601 (see above)

associations

array

["X_SELL" => ["groups" => [0 => "groupA"],"products" => [0 => "foo"],"product_models" => [0 => "productModelA"]]]

see below

quantified_associations

array

["PRODUCT_SET" => ["products" => [["identifier" => "productA", "quantity"=> 1]],"product_models" => [["identifier" => "productModelA", "quantity"=> 1]]]

see below

#Associations

The structure of the array is composed as below:

"associations" => array:1 [
  "X_SELL" => array:3 [
    "groups" => array:1 [
      0 => "groupB"
    ]
    "product_models" => array:0 []
    "products" => array:1 [
      0 => "foo"
    ]
  ]
]

“X_SELL” represents the code of the Akeneo\Pim\Structure\Component\Model\AssociationTypeInterface.

Each element in the array “groups” represents the code of the Akeneo\Pim\Enrichment\Component\Category\Model\GroupInterface.

Each element in the array “products” represents the identifier of the Akeneo\Pim\Enrichment\Component\Product\Model\ProductInterface.

Each element in the array “product_models” represents the code of the Akeneo\Pim\Enrichment\Component\Product\Model\ProductModelInterface.

#Quantified associations

"quantified_associations" => array:1 [
  "PRODUCT_SET" => array:2 [
    "products" => array:1 [
      0 => array:2 [
        "identifier" => "productA"
        "quantity" => 3
      ]
    ]
    "product_models" => array:1 [
      0 => array:2 [
        "identifier" => "productModelA"
        "quantity" => 2
      ]
    ]
  ]
]

“PRODUCT_SET” represents the code of the Akeneo\Pim\Structure\Component\Model\AssociationTypeInterface.

Each identifier in the array “products” represents the identifier of the Akeneo\Pim\Enrichment\Component\Product\Model\ProductInterface.

Each identifier in the array “product_models” represents the code of the Akeneo\Pim\Enrichment\Component\Product\Model\ProductModelInterface.

#Product values

Let’s now consider a catalog with all attribute types possible and a foo product, that contains:

  • all the attributes of the catalog

  • an identifier

  • a family

  • several groups

  • several categories

  • several associations related to groups, products and/or product models

  • several quantified associations related to products and/or product models

Its standard format would be the following:

array:10 [
  "identifier" => "foo"
  "family" => "familyA"
  "groups" => array:2 [
    0 => "groupA"
    1 => "groupB"
  ]
  "categories" => array:2 [
    0 => "categoryA1"
    1 => "categoryB"
  ]
  "enabled" => true
  "values" => array:19 [
    "sku" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "foo"
      ]
    ]
    "a_file" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "f/2/e/6/f2e6674e076ad6fafa12012e8fd026acdc70f814_fileA.txt"
      ]
    ]
    "an_image" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "f/4/d/1/f4d12ffbdbe628ba8e0b932c27f425130cc23535_imageA.jpg"
      ]
    ]
    "a_date" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "2016-06-13T00:00:00+02:00"
      ]
    ]
    "a_multi_select" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => array:2 [
          0 => "optionA"
          1 => "optionB"
        ]
      ]
    ]
    "a_number_float" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "12.5678"
      ]
    ]
    "a_number_float_negative" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "-99.8732"
      ]
    ]
    "a_number_integer" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => 42
      ]
    ]
    "a_number_integer_negative" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => -5
      ]
    ]
    "a_ref_data_multi_select" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => array:2 [
          0 => "fabricA"
          1 => "fabricB"
        ]
      ]
    ]
    "a_ref_data_simple_select" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "colorB"
      ]
    ]
    "a_simple_select" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "optionB"
      ]
    ]
    "a_text" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "this is a text"
      ]
    ]
    "a_text_area" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => "this is a very very very very very long text"
      ]
    ]
    "a_yes_no" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => true
      ]
    ]
    "a_localizable_image" => array:2 [
      0 => array:3 [
        "locale" => "en_US"
        "scope" => null
        "data" => "2/b/6/b/2b6b451334ee1a9aa83b5755590dae72ba254d8b_imageB_en_US.jpg"
      ]
      1 => array:3 [
        "locale" => "fr_FR"
        "scope" => null
        "data" => "d/e/3/f/de3f2a0af94d8b10ccc2c37bf4f945fd262d568e_imageB_fr_FR.jpg"
      ]
    ]
    "a_localized_and_scopable_text_area" => array:3 [
      0 => array:3 [
        "locale" => "en_US"
        "scope" => "ecommerce"
        "data" => "a text area for ecommerce in English"
      ]
      1 => array:3 [
        "locale" => "en_US"
        "scope" => "tablet"
        "data" => "a text area for tablets in English"
      ]
      2 => array:3 [
        "locale" => "fr_FR"
        "scope" => "tablet"
        "data" => "une zone de texte pour les tablettes en français"
      ]
    ]
    "a_metric" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => array:2 [
          "amount" => "987654321987.123456789123"
          "unit" => "KILOWATT"
        ]
      ]
    ]
    "a_metric_without_decimal" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => array:2 [
          "amount" => 200
          "unit" => "GRAM"
        ]
      ]
    ]
    "a_metric_negative" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => array:2 [
          "amount" => "-20.000000000000"
          "unit" => "CELSIUS"
        ]
      ]
    ]
    "a_metric_negative_without_decimal" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => array:2 [
          "amount" => -100
          "unit" => "CELSIUS"
        ]
      ]
    ]
    "a_price" => array:1 [
      0 => array:3 [
        "locale" => null
        "scope" => null
        "data" => array:2 [
          0 => array:2 [
            "amount" => "45.00"
            "currency" => "USD"
          ]
          1 => array:2 [
            "amount" => "-56.53"
            "currency" => "EUR"
          ]
        ]
      ]
    ]
    "a_scopable_price_without_decimal" => array:2 [
      0 => array:3 [
        "locale" => null
        "scope" => "ecommerce"
        "data" => array:2 [
          0 => array:2 [
            "amount" => 15
            "currency" => "EUR"
          ]
          1 => array:2 [
            "amount" => -20
            "currency" => "USD"
          ]
        ]
      ]
      1 => array:3 [
        "locale" => null
        "scope" => "tablet"
        "data" => array:2 [
          0 => array:2 [
            "amount" => 17
            "currency" => "EUR"
          ]
          1 => array:2 [
            "amount" => 24
            "currency" => "USD"
          ]
        ]
      ]
    ]
  ]
  "created" => "2016-06-23T11:24:44+02:00"
  "updated" => "2016-06-23T11:24:44+02:00"
  "associations" => array:3 [
    "PACK" => array:3 [
      "groups" => array:0 []
      "products" => array:2 [
        0 => "bar"
        1 => "baz"
      ]
      "product_models" => array:0 []
    ]
    "UPSELL" => array:3 [
      "groups" => array:1 [
        0 => "groupA"
      ]
      "products" => array:0 []
      "product_models" => array:1 [
        0 => "productModelA"
      ]
    ]
    "X_SELL" => array:3 [
      "groups" => array:1 [
        0 => "groupB"
      ]
      "products" => array:1 [
        0 => "bar"
      ]
      "product_models" => array:1 [
        0 => "productModelA"
      ]
    ]
  ]
  "quantified_associations" => array:1 [
    "PRODUCT_SET" => array:2 [
      "products" => array:2 [
        0 => array:2 [
          "identifier" => "productA"
          "quantity" => 3
        ]
        1 => array:2 [
          "identifier" => "productB"
          "quantity" => 1
        ]
      ]
      "product_models" => array:2 [
        0 => array:2 [
          "identifier" => "productModelA"
          "quantity" => 2
        ]
        1 => array:2 [
          "identifier" => "productModelB"
          "quantity" => 4
        ]
      ]
    ]
  ]
]

The product values are provided via the key values.

Product values can be localizable and/or scopable:

  • localizable means its value depends on the locale

  • scopable means its value depends on the scope (also called channel)

  • localizable and scopable means its value depends on the locale and the scope (also called channel)

That’s why product values always respect the following structure:

array:3 [
  "locale" => "a locale code"
  "scope" => "a scope code"
  "data" => "the value for the given locale and scope"
]

And that’s why, for the same attribute, you can have multiple product values:

"a_localizable_attribute" => array:2 [
  0 => array:3 [
    "locale" => "en_US"
    "scope" => null
    "data" => "the data in English"
  ]
  1 => array:3 [
    "locale" => "fr_FR"
    "scope" => null
    "data" => "la donnée en français"
  ]
]

Depending on the type of the product value, the data key can have different structure:

attribute type

data structure

data example

notes

identifier

string

"foo"

file

string

"f/2/e/6/f2e6674e076ad6fafa12012e8fd026acdc70f814_fileA.txt"

it represents the key of the object
Akeneo\Tool\Component\FileStorage\Model\FileInfoInterface

image

string

"f/4/d/1/f4d12ffbdbe628ba8e0b932c27f425130cc23535_imageA.jpg"

it represents the key of the object
Akeneo\Tool\Component\FileStorage\Model\FileInfoInterface

date

string

"2016-06-13T00:00:00+02:00"

formatted to ISO-8601 (see above)

multi select

string[]

[0 => "optionA", 1 => "optionB"]

each element of the array represents the code of the
Akeneo\Pim\Structure\Component\Model\AttributeOptionInterface

number

string

"-99.8732"

formatted as a string to avoid the floating point precision
problem of PHP (see above)

reference data multi select

string[]

[0 => "fabricA",1 => "fabricB"]

each element of the array represents the code of the
Akeneo\Pim\Enrichment\Component\Product\Model\ReferenceDataInterface

simple select

string

"optionB"

it represents the code of the
Akeneo\Pim\Structure\Component\Model\AttributeOptionInterface

reference data simple select

string

"colorB"

it represents the code of the
Akeneo\Pim\Enrichment\Component\Product\Model\ReferenceDataInterface

text

string

"this is a text"

text area

string

"this is a very very very very very long text"

yes/no

boolean

true

metric

array

["amount" => "987654321987.123456789123","unit" => "KILOWATT"]

amount and unit keys are expected unit should be a known unit
depending of the metric family of the attribute

price collection

array

[0 => ["amount" => "45.00","currency" => "USD"], 1 => ["amount" => "56.53","currency" => "EUR"] ]

amount and currency keys are expected for each price
currency should be a known currency

The following product values data, that represents decimal values are represented with strings (when the decimal_allowed attribute property is set to false) in the standard format:

  • metric (class AkeneoPimEnrichmentComponentProductModelMetric)

  • price (class AkeneoPimEnrichmentComponentProductModelProductPriceInterface)

  • number (class AkeneoPimEnrichmentComponentProductModelProductValueInterface, property getDecimal)

When the decimal_allowed attribute property is set to true, they are represented with integers in the standard format.


Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!