Skip to content

Home

Jump to bottom
Tobias Graml edited this page Apr 20, 2023 · 13 revisions

TOC

General information

This project is officially maintained by FINDOLOGIC. It provides a export library written in PHP which generates a XML or CSV according to the FINDOLOGIC export patterns. Before using this library you should understand how a export file should look like. See https://docs.findologic.com for further information.

Terminology

Term Meaning
item An item represents a product in the feed.
elements Elements in the following context are blocks in the feed which are added to the item such as an attribute or property.
attributes Attributes are better known as filters which are configurable via the FINDOLOGIC customer account.
properties Properties are used to display additional information of the product.

Basic Usage

Loading the library into the project

Composer

It is recommended to use composer to install the library in the project as most shopsystems come with composer support upfront. If you don't know how to use composer open https://getcomposer.org/doc/01-basic-usage.md.

$ composer require findologic/libflexport

After installing via composer, you can use the library by including the namespaces of the objects needed. In the examples below we assume that the library is loaded and accessible in the whole project.

With globally autoloaded composer packages
<?php

use FINDOLOGIC\Export\Exporter;
With manually included autoload file
<?php

require_once __DIR__ . '/vendor/autoload.php';

use FINDOLOGIC\Export\Exporter;

Existing examples

The repository already includes some examples for CSV and XML: https://github.com/findologic/libflexport/tree/develop/examples

Initializing the exporter with a specific type

Calling the method Exporter::create() with a type is required.

XML

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

CSV

<?php

use FINDOLOGIC\Export\CSV\CSVConfig;
use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::CSV);

// Information about properties, attributes and images added has to be provided when initializing the CSV-Exporter
$csvConfig = new CSVConfig(
    availableProperties: [ 'sale','anotherproperty' ],
    availableAttributes: [ 'cat', 'vendor'],
    imageCount: 3,
);
$exporter = Exporter::create(ExporterType::CSV, 20, $csvConfig);

Creating an item with the exporter instance

Please have in mind, that the item has to have at least a price set.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addPrice(44.8);

Adding elements

Basic

The following code is for demonstration purposes only!

For most of the elements there is a easy way to add an element to the item by calling the following schema.

<?php

/**
 * Replace the placeholder <Elementtype> with the element you want to add.
 * Usergroup is supported by most of the elements. See XML export patterns for
 * more information.
 */
$item->addElementtype('value', 'usergroup');

More complex element types are added by providing an object via the parameter.

<?php

// Replace the placeholder <Elementtype> with the element you want to add
$elementtype = new Elementtype();
$elementtype->doStuff();
$item->addElementtype($element);

// Shorter way
$item->addElementtype(new Elementtype('doStuff'));

Adding mutliple elements at once is also possible for most types.

<?php

// Replace the placeholder <Elementtype> with the element you want to add
$arrayOfElements = [];

// First
$arrayOfElements[] = new Elementtype('dostuff');
// Secound
$arrayOfElements[] = new Elementtype('dostuffagain');

$item->setAllElementtypes($arrayOfElements);

Data elements

NOTE! The examples show the shortest way to add an element to the item.

Ordernumber
<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;
use FINDOLOGIC\Export\Data\Ordernumber;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addOrdernumber(new Ordernumber('13132452'));
Name
<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addName('Productname');
Summary
<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addSummary('A short description of the product!');
Description
<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addDescription('Here should be the detailed description of the product!');
Price

The price may not be empty and must be a numeric value like an integer or float.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addPrice(44.8);
OverriddenPrice

The overridden price may not be empty and must be a numeric value like an integer or float.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addOverriddenPrice(55.8);
Url

The added URL must include the https:// or http:// protocol. For the CSV export, it is allowed to add relative url links.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addUrl('https://www.store.com/produkt/detail/link.html');
Image

The URL of the images must include the https:// or http:// protocol. For the CSV export, it is allowed to add relative url links.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Enums\ImageType;
use FINDOLOGIC\Export\Exporter;
use FINDOLOGIC\Export\Data\Image;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addImage(new Image('https://www.store.com/link/to/image.jpg'));

// Adding a additonal thumbnail image
$item->addImage(new Image('https://www.store.com/link/to/image/thumbnail.jpg', ImageType::THUMBNAIL));
Keyword
<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;
use FINDOLOGIC\Export\Data\Keyword;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addKeyword(new Keyword('Keyword'));
Group
<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;
use FINDOLOGIC\Export\Data\Usergroup;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addGroup(new Usergroup('group1'));
Bonus

The bonus value may not be empty and must be a numeric value like an integer or float.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addBonus(3);
Salesfrequency

The salesfrequency element may not be empty and must be a non negative integer.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addSalesFrequency(5);
DateAdded

The value of the date added element must be a \DateTime-object.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addDateAdded(new \DateTime());
Sort

The sort element may not be empty and must be an integer.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addSort(5);
Attributes

The added attribute values must not be empty and have to be collected in an array.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;
use FINDOLOGIC\Export\Data\Attribute;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$attributeValues = [
  'value 1',
  'value 2',
  'value 3'
];
$item->addAttribute(new Attribute('attributename', $attributeValues));
Properties

Properties are the most complex element types. Please have a look at the following examples to get a clue on how to use them.

It is recommended to use the first example (via setter method) if there are no usergroups needed.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

use FINDOLOGIC\Export\Data\Property;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');

// Adding values via setter method
$propertyElement = new Property('propertyname');
$propertyElement->addValue('propertyvalue1');
$propertyElement->addValue('propertyvalue2', 'partner');
$item->addProperty($propertyElement);

/**
 * Alternative usage
 * The array key of each entry in the array is the usergroup and the assigne value is the property value 
 */
$propertValues = [
'' => 'propertyvalue for general usergroup',
'partner' => 'propertyvalue for usergroup partner'
];
$item->addProperty(new Property('propertyname', $propertValues));
Variants

The variants of the product. When using variants, usergroups are not allowed within any other data element.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$itemId = '01120c948ad41a2284ad9f0402fbc7d';
$variantId = '5444bb0aa92841858ac47ef71c9cbab9';

$item = $exporter->createItem($itemId);
$variant = $exporter->createVariant($variantId, $itemId);

...
$variant->addName('Variant 1')
...

$item->addVariant($variant);
Visibility

Define if a product should be visible or hidden.

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addVisibility(true, 'usergroup1');
$item->addVisibility(false, 'usergroup2');

Finish exporting

The parameters of the exporters serializeItems-method should depend on the exported items. The docblock gives more detailed information.

If all items are exported at once, the start should be 0, the count and total parameter should reflect the number of products exported (count of $itemsCollection).

<?php

use FINDOLOGIC\Export\Enums\ExporterType;
use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(ExporterType::XML);

$itemsCollection = [];

$item = $exporter->createItem('01120c948ad41a2284ad9f0402fbc7d');
$item->addPrice(44.8);

$itemsCollection[] = $item;

// Output the generated FINDOLOGIC xml e.g. via echo
echo $exporter->serializeItems($itemsCollection, 0, 1, 1);

// Save the generated FINDOLOGIC xml as a file to the current directory
echo $exporter->serializeItemsToFile('.', $itemsCollection, 0, 1, 1);

Exceptions

Here is a list of the possible errors that could occure while using the library:

Exception Meaning
ItemsExceedCountValueException More items were added to the \Exporter-object via the $count-parameter.
ImagesWithoutUsergroupMissingException There were only images with usergroups added to the item.
BaseImageMissingException No base image (\Image of type default) was added to the item.
EmptyValueNotAllowedException This happens if you try to add empty values (like a string ->addValue("")) to an element of the item.
ValueIsNotNumericException The added value of element is not numeric (e.g. \Price element).
ValueIsNotUrlException The added value to an \Url or \Image element is not a valid URL. The protocol of the link has to be https:// or http://.
ValueIsNotIntegerException The added value ist not an integer.
ValueIsNotPositiveIntegerException The added value is not a positive integer.
DuplicateValueForUsergroupException There were multiple entries with the same key and usergroup added to the property element.
PropertyKeyNotAllowedException The key of the property element is reserverd and has one of the following patterns: /image\d+/, /thumbnail\d+/ or /ordernumber/
InvalidUrlException The value is not a valid url.
UnsupportedValueException The value added to the item is not supported for the XML export.
BadPropertyKeyException The property key must not exist of tabs and line feed characters.
Clone this wiki locally