Skip to content

findologic/libflexport

Repository files navigation

FINDOLOGIC export toolkit

Github Actions Latest Stable Version Code Climate Codecov

Table of Contents

  1. Synopsis
  2. Export recommendation
  3. Limitations
  4. Basic usage
    1. Setup
    2. XML Export
    3. CSV Export
  5. Examples
  6. Compatibility
  7. Contributors

Synopsis

This project provides an export library for XML and CSV generation according to the FINDOLOGIC export patterns.

Export recommendation

Using the XML export is recommended by FINDOLOGIC. The XML is easier to read and has some advantages over the CSV export like:

  • No encoding issues as the encoding attribute is provided in the XML response <?xml version="1.0" encoding="UTF-8"?>.
  • Validation is more reliable.
  • Simple escaping of content using the <![CDATA[...]]>-tag.
  • Standardized structure.
  • Dynamically extract the products from the database via start and count parameter in the url.
  • No limited file size for XML because of pagination.
  • Using multiple groups per product.

The key advantage for CSV is that it is possible to use way more groups than for XML. On the other hand:

  • Groups only regulate visibility - it's not possible to show different values per group.
  • The format is prone to encoding issues if non-UTF-8 data is fed into it.
  • Total export size is limited by file size, while XML pagination theoretically allows exports of arbitrary size.

Limitations

Currently, only input text encoded in UTF-8 is supported. To use this library with other types of encoding, one of the following is necessary:

  • Convert all text to UTF-8 prior to passing it to libflexport.
  • Use the XML exporter and modify the library to change the XML header to contain the required encoding.
    • FINDOLOGIC is capable of handling most encodings, but only with XML.

Basic usage

Setup

  1. Include as composer dependency using composer require findologic/libflexport
  2. Load ./vendor/autoload.php into the project

XML export

require_once './vendor/autoload.php';

use FINDOLOGIC\Export\Exporter;

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

$item = $exporter->createItem('123');

$item->addName('Test');
$item->addUrl('http://example.org/test.html');
$item->addPrice(13.37);
// Alternative long form:
// $name = new Name();
// $name->setValue('Test');
// $item->setName($name);
// $url = new Url();
// $url->setValue('http://example.org/test.html');
// $item->setUrl($url);
// $price = new Price();
// $price->setValue(13.37);
// $item->setPrice($price);

$xmlOutput = $exporter->serializeItems([$item], 0, 1, 1);

CSV export

require_once './vendor/autoload.php';

use FINDOLOGIC\Export\Exporter;

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

$item = $exporter->createItem('123');

$item->addPrice(13.37);
$item->addName('Test');
$item->addUrl('http://example.org/test.html');
// Alternative long form:
// $name = new Name();
// $name->setValue('Test');
// $item->setName($name);
// $url = new Url();
// $url->setValue('http://example.org/test.html');
// $item->setUrl($url);
// $price = new Price();
// $price->setValue(13.37);
// $item->setPrice($price);

// Date is mandatory for CSV.
$item->addDateAdded(new \DateTime());

$csvOutput = $exporter->serializeItems([$item], 0, 1, 1);

Examples

For more specific examples, please have a look at the examples directory.

Compatibility

The status of the major versions of libflexport is outlined below. Version numbers generally follow semantic versioning principles.

Version Branch PHP support Receives bug fixes Receives enhancements End of life
3.X develop >=8.1 ✔️ ✔️ Not in the foreseeable future
2.X 2.x >=7.1 ✔️ Not in the foreseeable future
1.X 1.x 5.6 - 7.3 ✔️ TBD
0.X 5.6 - 7.0 2017-11-24

All versions will most likely remain available for as long as the infrastructure to do so exists.

Contributors

See contribution guide.