fundevogel/php-pcbis

Simple PHP wrapper for Zeitfracht's webservice API, written in PHP

4.0.0 2022-08-05 23:51 UTC

Requires

• php: ^8.0
• ext-dom: *
• ext-mbstring: *
• guzzlehttp/guzzle: ^7.4

Requires (Dev)

• laravel/pint: ^0.2
• mikey179/vfsstream: ^1.6
• phpunit/phpunit: ^9.0
• vimeo/psalm: ^4.26

Suggests

• nicebooks/isbn: Provides ISBN functionality such as validation & formatting

GPL-3.0

• Kinder- und Jugendbuchhandlung Fundevogel
• Martin Folkers

• api
• webservice
• pcbis
• knv
• zeitfracht

README

What

This small library may be used to gather information about books by utilizing the JSON API powering pcbis.de, developed by Zeitfracht, a german wholesale book distributor. The official API documentation can be found here.

Why

It powers our book recommendations & downloads cover images from the German National Library.

How

It's available for Composer:

composer require fundevogel/php-pcbis

Basic workflow

Getting started is pretty straight-forward:

<?php

require_once('vendor/autoload.php');

use Fundevogel\Pcbis\Pcbis;

# Create object, passing credentials as first parameter (for caching, see below)
$object = new Pcbis([/* ... */]);

try {
    # After loading a book, you might want to ..
    $book = $object->load('978-3-522-20255-8');

    # (1) .. export its bibliographic data
    $data = $book->export();

    # (2) .. access specific information
    echo $book->title();

    # (3) .. download its cover
    if ($book->downloadCover()) {
        echo 'Cover downloaded!';
    }

    # (4) .. query its OLA status
    if ($book->isAvailable()) {
        # ...
    }

} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage(), "\n";
}

Note: While using this library during development, please consider using the API testing endpoint like so:

# Initialize API wrapper
$api = new Webservice($credentials);

# Use 'testing' URL 
$api->url = 'https://wstest.pcbis.de/ws30';

If you want to load several EANs/ISBNs, use loadAll(array $identifiers) which returns a Products object.

Note: Starting with v3, ISBN validation is no longer enabled by default. If you want formatted (= hyphenated) ISBNs when calling isbn() (if available), php-pcbis takes care of this for you if nicebooks/isbn is installed.

Caching

By default, php-pcbis doesn't implement any caching mechanism. If you want to store data - and you probably should - this could be achieved something like this:

require_once('vendor/autoload.php');

use Fundevogel\Pcbis\Pcbis;

$obj = new Pcbis([/* ... */]);
$ean = 'identifier';

if ($myCache->has($ean)) {
    $data = $myCache->get($ean);
    $product = $obj->load($data);
}

else {
    $product = $obj->load($ean);
    $myCache->set($ean, $product->data);
}

Credits

Most of the helper functions were taken from Kirby's excellent toolkit package by Bastian Allgeier (who's just awesome, btw).

Happy coding!

©️ Fundevogel Kinder- und Jugendbuchhandlung