Biblioteka do obsługi API eLibri

Wprowadzenie

eLibri jest systemem stworzonym dla wydawnictw, które mogą za jego pośrednictwem udostępniać dane bibliograficzne wydawanych przez siebie książek. Niniejsza biblioteka jest implementacją API udokumentowanego tutaj.

Lista zmian:

19 stycznia 2020 roku

  • nowe kody dla form produktów: figurka (ZB), zabawka - pluszak (ZC), zabawka edukacyjna (ZD)

19 stycznia 2020 roku

  • parsowanie informacji związanych z grami planszowymi i puzzle: nowe pola doyczące ilości elementów, czasu gry oraz ilości graczy
  • nowy kod dla plików dołączanych do opisu produktu ($supporting_resources) - ElibriDictResourceContentType::RULES_OR_INSTRUCTIONS
  • pola table_of_contents, description, short_description, reviews, excerpts mogą zawierać tylko teksty, dla których ContentAudience jest UNRESTRICTED

9 sierpień 2019 roku

  • informacja o cenie okładkowej i stawce VAT pobierana z elementu Price
  • informacja o poglądzie książki drukowanej jest pobierana teraz z SupportingResource
  • informacje o fragmentach cyfrowych książek są pobierane teraz z SupportingResource
  • informacja o końcu licencji na produkty cyfrowe jest pobierana z PublishingDetail
  • w polu isbn13_with_hyphens jest teraz wartość isbn bez kresek, ponieważ pole <elibri:HyphenatedISBN> zostanie wkrótce usunięte

30 lipca 2019 roku

  • Naprawione parsowanie SupplyDetails (dzięki uprzejmości Sebastiana Tatarczucha)
  • Dodane pole $proximity_name (wartości 'EXACTLY' albo 'MORE_THAN' - informują o dokładności wartości w polu $on_hand
  • Dodane pole $thema_subjects, które jest listą kategorii Thema

Instalacja

Proszę instalować bibliotekę bezpośrednio ze źródeł z github-a.

Użycie biblioteki

Żeby używać API należy najpierw uzyskać login i hasło dostępowe. Proszę pisać w tym celu na adres konta.nosp@m.kt@e.nosp@m.libri.nosp@m..com.nosp@m..pl.

Ogólne założenia API są opisane tutaj. Proszę też spojrzeć na poniższe przykłady.

Przykłady użycia

Użycie biblioteki jest bardzo proste. W poniższych przykładach zakładamy, że login i hasło są przechowywane jako zmienne środowiskowe ELIBRI_API_LOGIN i ELIBRI_API_PASSWORD. Wszystkie przykłady można znaleźć w katalogu examples

Przykład 1

W poniższym przykładzie instancjujemy obiekt klasy ElibriAPI oraz pobieramy listę dostępnych kolejek wraz z informacją o ilości produktów znajdujących w każdej z kolejek. Podczas połączenia może wystąpić jeden z wyjątków

<?php
//korzystaj z lokalnej kopii, jeśli istnieje
if (file_exists(dirname(__FILE__) . '/../elibriPHP.php')) {
require_once(dirname(__FILE__) . '/../elibriPHP.php');
} else {
require_once('elibriPHP.php');
}
$login = getenv('ELIBRI_API_LOGIN');
$password = getenv('ELIBRI_API_PASSWORD');
$api = new ElibriAPI($login, $password);
$queues_list = $api->getQueues();
foreach ($queues_list as $queue) {
print "Kolejka {$queue->name} => {$queue->product_count} produktów\n";
}
?>

Przykład 2

Typowe użycie API eLibri to regularne pobieranie nowych danych - w kolejce meta znajdą się zarówno nowododane produkty, jak i te, których dane się zmieniły. Wiadomość otrzymana z serwera to instancja ElibriOnixMessage, która zawiera listę produktów - ElibriProduct. Po Twojej stronie jest wykrycie, które dane się zmieniły. Żeby jednak ułatwić to zadanie, udostępniamy przy linkach, tekstach oraz autorach ich wewnętrzne ID w bazie eLibri. Pozwala to łatwiej sprawdzić, które dane uległy zmianie.

<?php
//korzystaj z lokalnej kopii, jeśli istnieje
if (file_exists(dirname(__FILE__) . '/../elibriPHP.php')) {
require_once(dirname(__FILE__) . '/../elibriPHP.php');
} else {
require_once('elibriPHP.php');
}
function print_info($product, $label, $field) {
if ($product->$field) {
print "$label: {$product->$field}\n";
}
}
$login = getenv('ELIBRI_API_LOGIN');
$password = getenv('ELIBRI_API_PASSWORD');
$api = new ElibriAPI($login, $password);
//opcjonalnie - zapełnij kolejkę wszystkimi dostępnymi danymi
//$api->refillAll();
while ($message = $api->popQueue("meta", 2)) {
foreach ($message->products as $product) {
print "======================\n";
print_info($product, "Identyfikator rekordu", "record_reference");
print_info($product, "Forma produktu", 'product_form_name');
//tytuły
print_info($product, "Pełen tytuł", 'full_title');
print_info($product, "Tytuł kolekcji", 'collection_title');
print_info($product, "Numer w kolekcji", 'collection_part');
print_info($product, "Tytuł", 'title');
print_info($product, "Podtytuł", 'subtitle');
print_info($product, "Tytuł originału", 'original_title');
print_info($product, "ISBN-13", "isbn13");
print_info($product, "EAN", "ean");
print_info($product, "Status rekordu", "current_state");
foreach ($product->contributors as $contr) {
print strtolower($contr->role_name) . ": " . $contr->person_name . "\n";
}
$series_names = join(", ", $product->series_names);
if ($series_names) {
print "Serie: $series_names\n";
}
print_info($product, "Wydawnictwo", "publisher_name");
print_info($product, "ID wydawnictwa", "publisher_id");
print_info($product, "Nazwa imprintu", "imprint_name");
//produkt z liczbach
print_info($product, "Wysokość (w mm)", "height");
print_info($product, "Szerokość (w mm)", "width");
print_info($product, "Grubość (w mm)", 'thickness');
print_info($product, "Waga (w gr)", "weight");
print_info($product, "Ilość stron", "number_of_pages");
print_info($product, "Czas trwania nagrania (w min.)", "duration");
print_info($product, "Wielkość pliku (w mb)", "file_size");
print_info($product, "Wiek czytelnika od", "reading_age_from");
print_info($product, "Wiek czytelnika do", "reading_age_to");
print_info($product, "Stawka VAT", "vat");
print_info($product, "PKWiU", 'pkwiu');
print_info($product, "Cena okładkowa", "cover_price");
print_info($product, "Numer wydania", "edition_statement");
print_info($product, "Liczba ilustracji", "number_of_illustrations");
print_info($product, "Okładka", 'cover_type');
if ($product->description) {
print "Opis: " . $product->description->text . "\n\n\n";
}
print "Link do okładki: " . $product->front_cover->link . "\n";
print "Data publikacji: " . join("/", array_reverse($product->parsed_publishing_date)) . "\n";
if ($product->premiere) {
print "Premiera: " . $product->premiere->format('d.m.Y') . "\n";
}
foreach ($product->thema_subjects as $subject) {
print "Kategoria: {$subject->code} {$subject->heading_text}\n";
}
}
}
?>

Przykład 3

Poniżej pobieramy listę wszystkich wydawnictw dostępnych w systemie, po czym drukowana jest informacja o pierwszym wydawnictwie, i pobierane dane pierwszej książki tego wydawnictwa.

<?php
//korzystaj z lokalnej kopii, jeśli istnieje
if (file_exists(dirname(__FILE__) . '/../elibriPHP.php')) {
require_once(dirname(__FILE__) . '/../elibriPHP.php');
} else {
require_once('elibriPHP.php');
}
$login = getenv('ELIBRI_API_LOGIN');
$password = getenv('ELIBRI_API_PASSWORD');
$api = new ElibriAPI($login, $password);
$publisher_list = $api->getPublishersList();
print "W systemie eLibri znajduje się: " . count($publisher_list) . " wydawnictw\n\n";
print "Dane pierwszego wydawnictwa:\n";
//wyświetl dane pierwszego wydawnictwa
$p = $publisher_list[0];
print " ID: {$p->publisher_id}\n";
print " Nazwa wydawnictwa: {$p->name}\n";
print " Nazwa firmy: {$p->company_name}\n";
print " NIP: {$p->nip}\n";
print " Ulica: {$p->street}\n";
print " Miasto: {$p->city}\n";
print " Kod pocztowy: {$p->zip_code}\n";
print " Telefon (1): {$p->phone1}\n";
print " Telefon (2): {$p->phone2}\n";
print " www: {$p->www}\n";
print " E-mail: {$p->email}\n";
print " Liczba produktów: {$p->products_count}\n\n";
print "Lista produktów\n";
$products = $api->getPublisherProducts($p->publisher_id);
//$products to tablica instancji ElibriPublisherProduct
foreach ($products as $product) {
print " {$product->record_reference} - {$product->title}\n";
};
$first_product = $products[0];
$product_data = $api->getProduct($first_product->record_reference);
//$product_data to instancja ElibriOnixMessage
print "Zwrócony został produkt: {$product_data->products[0]->full_title}\n";
$product_data = $api->getProduct("ea5782b2b67263943052");
print "Zwrócony został produkt: {$product_data->products[0]->full_title}\n";
?>