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.

Instalacja

Najprościej zainstalować bibliotekę za pomocą Composera:

composer require elibri/elibri_onix_client

Można też pobrać źródła z github-a i dołączyć plik elibriPHP.php:

require_once 'elibriPHP.php';

Biblioteka wymaga PHP 7.4 lub nowszego z rozszerzeniami curl, dom, simplexml i xmlreader.

Lista zmian:

19 października 2026 roku (wersje 0.9.1, 0.10.0, 0.10.1 i 0.11.0)

Wersja 0.11.0 - obsługa nowych elementów ONIX-a (szczegóły w testach w katalogu tests):

Wersje 0.10.0 i 0.10.1:

Wersja 0.9.1:

  • włączona weryfikacja certyfikatu TLS przy połączeniu z serwerem elibri.
  • parametr $testing w ElibriAPI::popQueue() jest teraz poprawnie przekazywany do serwera - wcześniej dane były usuwane z kolejki nawet przy $testing = true.
  • poprawione odczytywanie nagłówków odpowiedzi zawierających dwukropek.

12 listopada 2024 roku

  • dodanie obsługi danych podmiotu odpowiedzialnego oraz ostrzeżeń o bezpieczeństwie produktów. Szczegóły w testach ElibriOnixTest::test_publisher_safety_contact oraz ElibriOnixTest::test_product_safety_features.

23 września 2024 roku

  • dodanie obsługi dwóch statusów: cancelled - gdy produkt zostaje usunięty z planu wydawniczego, oraz indefinitely_postponed - gdy publikacja została odłożona na bliżej nieokreśloną przyszłość.

20 sierpnia 2024 roku

20 września 2023 roku

  • usunięcie reszty kodu obsługującego dodatkowe tagi, spoza ONIX-a.

27 sierpnia 2023 roku

5 luty 2023 roku

  • dodanie języka śląskiego do listy języków

26 luty 2022 roku

  • dodanie informacji o zapowiedzianych zmianach cen: $currrent_price_until, $future_cover_price, $future_price_from

16 kwiecień 2020 roku

  • dodane pole $keywords zawierające listę słów kluczowych (tagów) dodanych przez wydawce.

29 stycznia 2020 roku

  • dodany kod A06 dla kompozytora (ContributorRole)

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

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";
}
ElibriAPI
ElibriAPI abstrahuje wykorzystanie API udostępniane przez Elibri.
Definition: elibriAPI.php:106

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";
Wygenerowano przez   doxygen 1.9.1