Skip to content

Home

Jump to bottom
Markus Machatschek edited this page Apr 4, 2018 · 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.

The CSV-Export is experimental and not intended to be used in production!

Naming conventions

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;

Initializing the exporter with a specific type

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

XML

<?php

use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(Exporter::TYPE_XML);

CSV

<?php

use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(Exporter::TYPE_CSV);

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\Exporter;

$exporter = Exporter::create(Exporter::TYPE_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\Exporter;
use FINDOLOGIC\Export\Data\Ordernumber;

$exporter = Exporter::create(Exporter::TYPE_XML);

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

use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(Exporter::TYPE_XML);

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

use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(Exporter::TYPE_XML);

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

use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(Exporter::TYPE_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\Exporter;

$exporter = Exporter::create(Exporter::TYPE_XML);

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

The added URL must include the https:// or http:// protocol.

<?php

use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(Exporter::TYPE_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.

<?php

use FINDOLOGIC\Export\Exporter;
use FINDOLOGIC\Export\Data\Image;

$exporter = Exporter::create(Exporter::TYPE_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', Image::TYPE_THUMBNAIL));
Keyword
<?php

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

$exporter = Exporter::create(Exporter::TYPE_XML);

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

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

$exporter = Exporter::create(Exporter::TYPE_XML);

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

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

<?php

use FINDOLOGIC\Export\Exporter;

$exporter = Exporter::create(Exporter::TYPE_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\Exporter;

$exporter = Exporter::create(Exporter::TYPE_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\Exporter;

$exporter = Exporter::create(Exporter::TYPE_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\Exporter;

$exporter = Exporter::create(Exporter::TYPE_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\Exporter;
use FINDOLOGIC\Export\Data\Attribute;

$exporter = Exporter::create(Exporter::TYPE_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\Exporter;

use FINDOLOGIC\Export\Data\Property;

$exporter = Exporter::create(Exporter::TYPE_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););

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\Exporter;

$exporter = Exporter::create(Exporter::TYPE_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 This will be thrown if there are more items added to the exporter object than set via the count parameter.
ImagesWithoutUsergroupMissingException This will be thrown if only images with usergroups are added to the item.
BaseImageMissingException This will be thrown when there are no base images (\Image of type default) 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 This happens if the added value of an element is not numeric (e.g. \Price element).
ValueIsNotUrlException This will occure if 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 This happens if the added value ist not an integer.
ValueIsNotPositiveIntegerException This happens if the added value is not a positive integer.
DuplicateValueForUsergroupException This happens if the same key and usergroup are added to a property element.
PropertyKeyNotAllowedException This happens if the key of a element has one of the following schema: /image\d+/, /thumbnail\d+/ or /ordernumber/
Clone this wiki locally