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 许可证。

pionyr / pionyr-cz-client

维护者

详细信息