pionyr / pionyr-cz-client
PHP API Client for API provided by Pionyr.cz
Requires
- php: ^7.3 || ^8.0
- ext-json: *
- ext-mbstring: *
- beberlei/assert: ^3.0
- fig/http-message-util: ^1.1
- myclabs/php-enum: ^1.6
- pascaldevink/shortuuid: ^3.0
- php-http/client-common: ^2.3
- php-http/discovery: ^1.4
- php-http/httplug: ^2.2
- php-http/message: ^1.11
- php-http/message-factory: ^1.0
- php-http/promise: ^1.1
- psr/http-message: ^1.0
- ramsey/uuid: ^4.1
Requires (Dev)
- ergebnis/composer-normalize: ^2.13
- lmc/coding-standard: ^3.0
- php-coveralls/php-coveralls: ^2.0
- php-http/guzzle6-adapter: ^2.0
- php-http/mock-client: ^1.1
- php-mock/php-mock-phpunit: ^2.1
- php-parallel-lint/php-parallel-lint: ^1.2
- phpstan/phpstan: ^0.12.16
- phpstan/phpstan-phpunit: ^0.12.0
- phpunit/phpunit: ^9.5
- symfony/var-dumper: ^4.0 || ^5.0
README
Pro využití například na webech krajských organizací poskytuje web pionyr.cz API, skrze které se dají načítat články, akce, termíny a seznamy jednotek (pionýrských skupin, oddílů, klubů).
Tato knihovna poskytuje nástroje pro snadnou práci s tímto API. Knihovna vyžaduje PHP verze 7.3 a novější.
Instalace
Instalace knihovny se provede skrze Composer. Instalaci je možno spustit tímto příkazem:
$ composer require pionyr/pionyr-cz-client guzzlehttp/guzzle
Čímž se nainstaluje API klient, který bude používat jako transportní HTTP knihovnu Guzzle 7.
Knihovna používá pro HTTP abstrakci za využití specifikací PSR-7, PSR-17 a PSR-18. Není tak svázána s konkrétní
HTTP knihovnou. Díky tomu je dle potřeby možné použít i jinou HTTP knihovnu (např. takovou, kterou již využívá PHP framework,
ve kterém máme aplikaci, např. symfony/http-client
).
Viz seznam podporovaných HTTP knihoven.
Pokud bychom chtěli použít jako transportní knihovnu místo Guzzle 7 například cURL, nainstalujeme API klienta tímto příkazem:
$ composer require pionyr/pionyr-cz-client php-http/curl-client guzzlehttp/psr7
Použití
Pro použití potřebujeme znát API token, který přidělí Ústředí Pionýra. Tokenem je zároveň identifikován uživatel a je tím stanoven i rozsah přístupů (např. tokenem vystaveným pro jeden kraj nemůžeme přistupovat k seznamu akcí jiného kraje apod.).
Token se také váže na doménu (instanci) API - v případě použití testovací instance API je třeba rovněž použít token, vystavený právě pro tuto instanci (token pro "produkční" instanci zde nebude fungovat).
Na začátku práce s API je třeba nejprve vytvořit instanci objektu PionyrCz
a předat mu API token:
$pionyrCz = new PionyrCz('my-api-token');
Pokud chceme pracovat s jinou instancí API než "produkční" na pionyr.cz, můžeme nastavit tzv. base URL API:
use Pionyr\PionyrCz\PionyrCz; $pionyrCz = new PionyrCz('my-api-test-token'); $pionyrCz->setBaseUrl('http://staging.pionyr.cz/api/');
V dalších ukázkách se pracuje s tímto objektem $pionyrCz
.
Cachování odpovědí
Odpovědi z API je vhodné cachovat. Ukázku nastavení cachování pomocí PSR-6 je možné najít v souboru examples/caching.php.
Články
Načtení seznamu článků
Vracejí se pouze publikované články odpovídající právům daného tokenu, které se mají momentálně zobrazovat.
Seznam je stránkovaný po 30 položkách na stránku a je možné jej filtrovat dle kategorie článku.
use Pionyr\PionyrCz\Constants\ArticleCategory; $response = $pionyrCz->request() ->articles() ->setPage(3) // volitelné, není-li nastaveno, načte se první strana výpisu ->setCategory(ArticleCategory::UVODNI_NOVINKY) // volitelné filtrování dle ID kategorie, není-li nastaveno, načtou se články ve všech kategoriích ->onlyRegional() // volitelné filtrování pouze krajských článků, není-li nastaveno, zobrazují se i "celostátání" články ->send(); echo $response->getPageCount(); // vypíše celkový počet stránek které daný seznam obsahuje echo $response->getItemTotalCount(); // vypíše celkový počet položek (na všech stránkách) které daný seznam obsahuje foreach ($response->getData() as $article) { echo $article->getUuid(); // jedinečné ID článku (UUID) echo $article->getShortUuid(); // zkrácené jedinečné ID článku - pro použití například v URL echo $article->getTitle(); // název článku echo $article->getDatePublished() ->format('j. n. Y H:i:s'); // datum publikování echo $article->getCategory(); // kategorie článku echo $article->getCategoryId(); // ID kategorie článku echo $article->getAuthorName(); // jméno a příjmení autora článku echo $article->getPerex(); // text perexu - krátký úvod článku echo $article->getPerexPhotoUrl(); // URL úvodní fotky k článku (může být null) }
Načtení detailu jednoho článku
Detail článku obsahuje stejné položky, jako jeden článek v seznamu, a k tomu je doplněn o další údaje.
$response = $pionyrCz->request() ->article('article-uuid') // je třeba předat UUID nebo Short UUID článku ->send(); $article = $response->getData(); echo $article->getUuid(); // jedinečné ID článku (UUID) echo $article->getShortUuid(); // zkrácené jedinečné ID článku - pro použití například v URL echo $article->getTitle(); // název článku echo $article->getDatePublished() ->format('j. n. Y H:i:s'); // datum publikování echo $article->getCategory(); // kategorie článku echo $article->getCategoryId(); // ID kategorie článku echo $article->getAuthorName(); // jméno a příjmení autora článku echo $article->getPerex(); // text perexu - krátký úvod článku echo $article->getPerexPhotoUrl(); // URL fotky k článku (může být null) echo $article->getText(); // HTML text článku echo $article->getTextPhotoUrl(); // URL fotky k textu článku (může být null) echo $article->getDateShowFrom() ->format('j. n. Y H:i:s'); // zobrazit článek jako aktualitu od (může být null) echo $article->getDateShowTo() ->format('j. n. Y H:i:s'); // zobrazit článek jako aktualitu do (může být null) echo $article->isNews(); // je článek aktualita na www.pionyr.cz? echo $article->isNewsForMembersPublic(); // je článek veřejná aktualita pro členy? echo $article->isNewsForMembersPrivate(); // je článek aktualita pro členy po přihlášení? echo $article->isMyRegion(); // můj krajský web (?) echo $article->isMozaika(); // odeslat do Mozaiky Pionýra? echo $article->isOfferedToOtherRegions(); // je článek nabídnut dalším krajům? foreach ($article->getRegions() as $region) { // pole se seznamem KOP, ve kterých se má článek zobrazovat echo $region; } foreach ($article->getPhotos() as $photo) { // pole fotografií článku echo $photo->getUrl(); echo $photo->getTitle(); } foreach ($article->getLinks() as $link) { // pole odkazů u článku echo $link->getUrl(); echo $link->getTitle(); }
Akce
Načtení seznamu akcí
Vracejí se pouze akce odpovídající právům daného tokenu.
Seznam je stránkovaný po 30 položkách na stránku a je možné jej filtrovat dle kategorie akce a dle termínu akce (jako výchozí se načítají akce, mající datum začátku dnes nebo v budoucnu).
use Pionyr\PionyrCz\Constants\EventCategory; use Pionyr\PionyrCz\Constants\EventLocalization; $response = $pionyrCz->request() ->events() ->setPage(3) // volitelné, není-li nastaveno, načte se první strana výpisu ->setCategory(EventCategory::TABOR()) // volitelné filtrování dle kategorie, není-li nastaveno, načtou se akce ve všech kategoriích ->onlyByUnitAndSubunits() // volitelné filtrování - je-li zapnuto, načtou se pouze akce, které organizuje aktuální jednotka které patří token (např. kraj) a její podjednotky (např. pionýrské skupiny a oddíly) ->setLocalization(EventLocalization::NATIONWIDE()) // volitelné filtrování dle lokalizace akce - je-li zapnuto, načtou se pouze akce se zadanou lokalizací, a to buďto regionální nebo pouze celorepublikové ->setDateFrom(new \DateTime('2018-01-01')) // volitelné filtrování dle data - je-li nastaveno, načtou se pouze akce konající se po tomto datu, jinak se načtou akce konající se ode dnešního dne ->setDateTo(new \DateTime('2018-08-31')) // volitelné filtrování dle data - je-li nastaveno, načtou se pouze akce konající se před tímto datem ->send(); echo $response->getPageCount(); // vypíše celkový počet stránek které daný seznam obsahuje echo $response->getItemTotalCount(); // vypíše celkový počet položek (na všech stránkách) které daný seznam obsahuje foreach ($response->getData() as $event) { echo $event->getUuid(); // jedinečné ID akce (UUID) echo $event->getShortUuid(); // zkrácené jedinečné ID akce - pro použití například v URL echo $event->getTitle(); // název akce echo $event->getDescription(); // popis akce echo $event->getCategory(); // kategorie akce (může být null) echo $event->getPhotoUrl(); // URL fotky (loga) akce (může být null) echo $event->getOrganizer(); // pořadatel echo $event->getDateFrom() ->format('j. n. Y H:i'); // datum a čas začátku akce echo $event->getDateTo() ->format('j. n. Y H:i'); // datum a čas konce akce echo $event->isImportant(); // jedná se o důležitý termín? echo $event->getPlace(); // Místo konání akce echo $event->getRegion(); // Kraj místa konání akce echo $event->getWebsiteUrl(); // Webové stránky akce echo $event->getPriceForMembers(); // cena standardní pro členy (může být null) echo $event->getPriceForMembersDiscounted(); // cena zvýhodněná pro členy (může být null) echo $event->getPriceForPublic(); // cena standardní pro veřejnost (může být null) echo $event->getPriceForPublicDiscounted(); // cena zvýhodněná pro veřejnost (může být null) echo $event->getDatePublishFrom() ->format('j. n. Y'); // datum od kdy akci zveřejnit (může být null) echo $event->getDatePublishTo() ->format('j. n. Y'); // datum do kdy akci zveřejnit (může být null) echo $event->getLocalization(); // lokalizace akce (může být null) echo $event->isShownInCalendar(); // zobrazit v kalendáriu? echo $event->isOpenEvent(); // jedná se o otevřenou akci? echo $event->getOpenEventType(); // typ otevřené akce (může být null, pokud se nejedná o otevřenou akci) echo $event->isForKids(); // je akce určena pro děti? echo $event->isForLeaders(); // je akce určena pro instruktory a vedoucí? echo $event->isForPublic(); // je akce určena pro veřejnost? }
Načtení detailu jedné akce
Detail akce obsahuje stejné položky, jako jedna akce v seznamu, a k tomu je doplněn o další údaje.
$response = $pionyrCz->request() ->event('event-uuid') // je třeba předat UUID nebo Short UUID akce ->send(); $event = $response->getData(); echo $event->getTitle(); // název akce echo $event->getDescription(); // popis akce // ... a všechny položky, jako ve výpisu seznamů akcí, a navíc: echo $event->getAgeFrom(); // doporučený věk od (může být null) echo $event->getAgeTo(); // doporučený věk do (může být null) echo $event->getExpectedNumberOfParticipants(); // předpokládaný počet účastníků (může být null) echo $event->getTransportation(); // informace k dopravě (může být null) echo $event->getAccommodation(); // informace k ubytování (může být null) echo $event->getFood(); // informace k zajištění stavy (může být null) echo $event->getRequiredEquipment(); // požadované vybavení foreach ($event->getPhotos() as $photo) { // pole fotografií akce echo $photo->getUrl(); echo $photo->getTitle(); } foreach ($event->getFiles() as $file) { // pole souborů akce echo $file->getUrl(); echo $file->getTitle(); echo $file->isPublic(); // má se soubor zobrazovat veřejně? } foreach ($event->getLinks() as $link) { // pole odkazů u akce echo $link->getUrl(); echo $link->getTitle(); }
Jednotky
Pionýrské skupiny
Vracejí se pouze skupiny odpovídající právům daného tokenu (podjednotky kraje).
Seznam je stránkovaný po 50 položkách na stránku.
use Pionyr\PionyrCz\Constants\EventCategory; $response = $pionyrCz->request() ->groups() ->setPage(3) // volitelné, není-li nastaveno, načte se první strana výpisu ->send(); echo $response->getPageCount(); // vypíše celkový počet stránek které daný seznam obsahuje echo $response->getItemTotalCount(); // vypíše celkový počet položek (na všech stránkách) které daný seznam obsahuje foreach ($response->getData() as $group) { echo $group->getName(); // název jednotky echo $group->getWebsiteUrl(); // Webové stránky jednotky echo $group->getPhone(); // Kontaktní telefon jednotky echo $group->getEmail(); // E-mail jednotky echo $group->getLeaderName(); // Jméno vedoucího jednotky echo $group->getIco(); // IČO jednotky // Adresa sídla PS echo $group->getAddressOfficial()->getCity()); // Město echo $group->getAddressOfficial()->getStreet()); // Ulice echo $group->getAddressOfficial()->getPostcode()); // PSČ // Adresa Kde nás najdete echo $group->getAddressWhereToFindUs()->getCity()); // Město echo $group->getAddressWhereToFindUs()->getStreet()); // Ulice echo $group->getAddressWhereToFindUs()->getPostcode()); // PSČ }
Oddíly
Zatím neimplementováno.
Kluby
Zatím neimplementováno.
Výjimky a zpracování chyb
Výjimky, ke kterým dojde v API klientovi při zpracování požadavků/odpovědí, implementují rozhraní Pionyr\PionyrCz\Exception\PionyrCzExceptionInterface
.
Strom výjimek:
V případě použití vlastní instance HTTP klienta (tedy pokud voláme $pionyrCz->setHttpClient()
) je třeba zajistit,
aby byl nastaven tak, že v případě HTTP chyb (400 a 500) nevyhazuje sám výjimky. Například při použití Guzzle 6 klienta
to znamená že nastavení http_errors
musí být false
.
Changelog - seznam změn
Pro seznam změn viz soubor CHANGELOG.md. Dodržujeme sémantické verzování.
Licence
Knihovna je zveřejněna jako open-source pod licencí MIT.