pionyr / pionyr-cz-client
Pionyr.cz 提供的 API 的 PHP API 客户端
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
例如,为了在省级组织网站上使用,pionyr.cz 提供了 API,通过它可以加载文章、活动、日期和单位(童子军小组、部队、俱乐部)列表。
此库提供了处理此 API 的工具。库需要 PHP 版本 7.3 及以上。
安装
通过 Composer 安装库。可以使用以下命令进行安装
$ composer require pionyr/pionyr-cz-client guzzlehttp/guzzle
这将安装使用 Guzzle 7 作为传输 HTTP 库的 API 客户端。
库使用 PSR-7、PSR-17 和 PSR-18 规范进行 HTTP 抽象。因此,它与特定的 HTTP 库无关。因此,根据需要,还可以使用其他 HTTP 库(例如,在应用中使用的 PHP 框架的 symfony/http-client
)。有关受支持的 HTTP 库的列表,请参阅 此处。
如果我们要使用 cURL 而不是 Guzzle 7 作为传输库,可以使用以下命令安装 API 客户端
$ composer require pionyr/pionyr-cz-client php-http/curl-client guzzlehttp/psr7
使用
为了使用,我们需要知道由童子军总部分配的 API token。Token 同时标识用户并确定访问范围(例如,使用针对一个省份发布的 token 无法访问另一个省份的活动列表等)。
Token 也绑定到 API 域(实例) - 如果使用测试实例 API,也需要使用针对该实例发布的 token("生产"实例的 token 将不会工作)。
在开始使用 API 之前,首先需要创建 PionyrCz
对象的实例,并将其 API token 传递给它
$pionyrCz = new PionyrCz('my-api-token');
如果我们要使用 pionyr.cz 上的非“生产”实例 API,可以设置 API 的基础 URL
use Pionyr\PionyrCz\PionyrCz; $pionyrCz = new PionyrCz('my-api-test-token'); $pionyrCz->setBaseUrl('http://staging.pionyr.cz/api/');
后续示例中使用此对象 $pionyrCz
。
缓存响应
API 的响应适合进行缓存。可以在 examples/caching.php 文件中找到使用 PSR-6 设置缓存的示例。
文章
加载文章列表
仅返回具有相应 token 权限的已发布文章,这些文章目前正在显示。
列表按每页 30 项分页,可以按文章类别进行筛选。
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) }
加载单个文章的详细信息
文章的详细信息包含列表中单个文章的相同条目,并添加了其他数据。
$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(); }
活动
加载活动列表
仅返回具有相应 token 权限的活动。
列表按每页 30 项分页,可以按活动类别和活动日期进行筛选(默认情况下,加载今天或未来日期开始的活动)。
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? }
加载单个活动的详细信息
活动的详细信息包含列表中单个活动的相同条目,并添加了其他数据。
$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(); }
单位
童子军小组
仅返回具有相应 token 权限的小组(省份的子单位)。
列表按每页 50 项分页。
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Č }
部队
尚未实现。
俱乐部
尚未实现。
异常和错误处理
API 客户端在处理请求/响应时发生的异常实现了 Pionyr\PionyrCz\Exception\PionyrCzExceptionInterface
接口。
异常树
如果在使用自定义的HTTP客户端实例(即调用 $pionyrCz->setHttpClient()
)的情况下,需要确保在HTTP错误(400和500)发生时,客户端不会自动抛出异常。例如,在使用Guzzle 6客户端时,这意味着需要将设置 http_errors
设置为 false
。
变更日志 - 变更列表
要查看变更列表,请参阅文件 CHANGELOG.md。我们遵循 语义化版本控制。
许可证
该库作为开源软件发布,遵循 MIT 许可证。