kompakt/b3d

Berlin3 'Details' API Wrapper

Kompakt\B3d

Berlin3 Details API Wrapper, _(*1)

Description

Get data from "Details" endpoints, optionally cache results, load full graph per "Details" schema, build canonical product representation and serialize result to xml files., _(*2)

Installation

Through Composer:, _(*3)

• composer require kompakt/b3d

Introduction

The Berlin3 Details software for music businesses provides data access in the form of full table dumps. It's up to the user to construct the graph and assemble a data model for further usage. The following entities are available: releases, products, artists, labels, prices, product-tracks, tracks and stock. These entities build up the following structure:, _(*4)

+ release (1)
    + label (1)
        + artist (N)
    + product (N)
        + price (N)
        + stock (1)
            + account (N)
        + product-track (N)
            + track (N)

Library Features

• Data fetchers
• Data mappers
• Raw data caching
• In-memory graph loader
• Canonical product builder
• Canonical product serializer
• Extendable event-based architecture

Internally the data is mapped to temporary entity objects. These entities are then wired up by the graphloader. From there the graph is converted to a product-based datastructure in the from of canonical products. This draws a logical border to avoid "Details" interna to leak into your domain., _(*5)

+ product (contains release-, artist- and labeldata)
    + price (N)
    + track (N)

Fetching

use GuzzleHttp\Client;
use Kompakt\B3d\Details\Endpoint\Resource\Artist\Endpoint;

$artistEndpoint = new Endpoint(
    new Client(),
    '<artist-endpoint-url>',
    '<api-key>'
);

$rawArtistData = $artistEndpoint->fetchAll();

Caching

use Kompakt\B3d\Details\Endpoint\Cache\PhpFile\Serializer;
use Kompakt\B3d\Util\File\Writer;

$artistSerializer = new Serializer(
    new Writer(),
    'path/to/artist/data/file'
);

$artistSerializer->serialize($rawArtistData);

Populating Entity Repository

Populating from cache:, _(*6)

use Kompakt\B3d\Details\Endpoint\Resource\Artist\Mapper;
use Kompakt\B3d\Details\Entity\Artist;
use Kompakt\B3d\Details\Repository\ArtistRepository;
use Kompakt\B3d\Util\File\Reader;
use Kompakt\B3d\Details\Populator\Cache\PhpFile\Populator;

$artistPopulator = new Populator(
    new ArtistMapper(new Artist()),
    new ArtistRepository(),
    new Reader(),
    'path/to/artist/data/file'
);

$artistRepository = $artistPopulator->populate();
$artists = $artistRepository->getAll();

The individual parts can also be wired up to directly fetch and populate:, _(*7)

use Kompakt\B3d\Details\Endpoint\Resource\Artist\Mapper;
use Kompakt\B3d\Details\Entity\Artist;
use Kompakt\B3d\Details\Repository\ArtistRepository;
use Kompakt\B3d\Details\Populator\Endpoint\Populator;

$artistPopulator = new Populator(
    new ArtistMapper(new Artist()),
    new ArtistRepository(),
    $artistEndpoint
);

Loading the Graph

use Kompakt\B3d\Details\Graph\Loader as GraphLoader;

$graphLoader = new GraphLoader(
    $artistPopulator,
    $labelPopulator,
    $pricePopulator,
    $productPopulator,
    $productTrackPopulator,
    $releasePopulator,
    $trackPopulator
);

$releaseRepository = $graphLoader->load();

Building and Serializing Canonical Products

use Kompakt\B3d\Canonical\Dom\Product\Builder as CanonicalProductDomBuilder;
use Kompakt\B3d\Canonical\Entity\Price as CanonicalPrice;
use Kompakt\B3d\Canonical\Entity\Product as CanonicalProduct;
use Kompakt\B3d\Canonical\Entity\Track as CanonicalTrack;
use Kompakt\B3d\Canonical\Converter\Details\ConverterRunner;
use Kompakt\B3d\Canonical\Converter\Details\Product as CanonicalProductConverter;
use Kompakt\B3d\Canonical\Converter\Details\Subscriber\XmlSerializer as XmlSerializerSubscriber;
use Kompakt\B3d\Util\File\Writer;
use Kompakt\CollectionRunner\EventNames;
use Kompakt\CollectionRunner\Runner as CollectionRunner;
use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();
$eventNames = new EventNames();
$collectionRunner = new CollectionRunner($dispatcher, $eventNames);

$canonicalProductConverter = new CanonicalProductConverter(
    new CanonicalProduct(),
    new CanonicalTrack(),
    new CanonicalPrice()
);

$canonicalProductXmlSerializer = new CanonicalProductXmlSerializer(
    new CanonicalProductDomBuilder(),
    new Writer(),
    'path/to/xml/output/dir'
);

$serializerSubscriber = new XmlSerializerSubscriber(
    $dispatcher,
    $eventNames,
    $canonicalProductXmlSerializer
);

$converterRunner = new ConverterRunner(
    $collectionRunner,
    $graphLoader,
    $canonicalProductConverter
);

$serializerSubscriber->activate();
$converterRunner->load();
$converterRunner->run();

Of course, you don't necessarily need to serialize the canonical products. You could omit XmlSerializerSubscriber and write your own event listener to directly save the data into a database, _(*8)

Populating Canonical Product Repository from serialized XML

use Kompakt\B3d\Canonical\Dom\Product\Mapper as DomProductMapper;
use Kompakt\B3d\Canonical\Entity\Price;
use Kompakt\B3d\Canonical\Entity\Product;
use Kompakt\B3d\Canonical\Entity\Track;
use Kompakt\B3d\Canonical\Populator\Xml\Subscriber\Product as Populator;
use Kompakt\B3d\Canonical\Repository\ProductRepository;
use Kompakt\B3d\Canonical\Unserializer\Xml\Product as Unserializer;
use Kompakt\B3d\Util\Dom\Loader as DomLoader;
use Kompakt\B3d\Util\File\Reader;
use Kompakt\DirectoryRunner\Runner;
use Kompakt\DirectoryRunner\EventNames;
use Kompakt\DirectoryRunner\Subscriber\Debugger;
use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();
$eventNames = new EventNames();
$fileReader = new Reader();
$domLoader = new DomLoader();

$runner = new Runner(
    $dispatcher,
    $eventNames,
    $canonicalProductDirPathname
);

$price = new Price();
$product = new Product();
$track = new Track();
$domMapper = new DomProductMapper($product, $track, $price);
$repository = new ProductRepository();

$unserializer = new Unserializer(
    $fileReader,
    $domLoader,
    $domMapper
);

$populator = new Populator(
    $dispatcher,
    $eventNames,
    $unserializer,
    $repository
);

$populator->activate();
$runner->run();

foreach ($repository->getAll() as $product)
{
    echo sprintf("%s\n", $product->getReleaseTitle());

    foreach ($product->getTracks() as $track)
    {
        echo sprintf(">> %s\n", $track->getTitle());
    }
}

Fetching Stock

Once you have your products in place, you can fetch stocklevels. Be aware that the API returns a maximum of 200 stock items per request:, _(*9)

use GuzzleHttp\Client;
use Kompakt\B3d\Details\Endpoint\Resource\Stock\Endpoint as StockEndpoint;
use Kompakt\B3d\Details\Endpoint\Cache\PhpFile\Serializer as PhpFileSerializer;
use Kompakt\B3d\Util\File\Writer;
use Symfony\Component\Stopwatch\Stopwatch;

$stockEndpoint = new StockEndpoint(
    new Client(),
    '<stock-endpoint-url>',
    '<api-key>'
);

$stockEndpoint->fetch(['uuid-1', 'uuid-2']);

Passing Orders To Details

use GuzzleHttp\Client;
use Kompakt\B3d\Details\Endpoint\Resource\Order\Endpoint;

$orderEndpoint = new Endpoint(
    new Client(),
    '<stock-endpoint-url>',
    '<api-key>'
);

$orderData = [
    ...
];

$itemData = [
    ...
];

$orderEndpoint->create($orderData, $itemData);

Working Examples

• cp example/config.php.dist config.php
• Adjust config.php as needed

License

kompakt/b3d is licensed under the MIT license - see the LICENSE file for details, _(*10)