README

为BIR1（REGON 1互联网数据库）API（https://wyszukiwarkaregon.stat.gov.pl/appBIR/index.aspx）提供PHP绑定。

API文档

安装

API客户端可以通过Composer进行安装。

在你的composer.json文件中

{
    "require": {
        "freshmindpl/wyszukiwarkaregon": "~3.0"
    }
}

创建composer.json文件后，你可以运行composer install进行初始包安装，以及composer update更新到API客户端的最新版本。

基本用法

请记住在您的应用程序中包含Composer自动加载器

<?php
require_once 'vendor/autoload.php';

// Application code...
?>

在创建客户端时配置您的访问凭证

<?php
use WyszukiwarkaRegon\Client;
use WyszukiwarkaRegon\Exception\RegonException;
use WyszukiwarkaRegon\Exception\SearchException;

$client = new Client([
   'key' => 'aaaabbbbccccdddd' //Optional api key - required for full reports,
   'session' => 'abcdefghijklmnopqrstuvwxyz' //Session id if already logged in
]);
?>

本地测试

从项目根目录运行phpunit以启动所有测试。

示例

登录

<?php
// Login and obtain session id (sid)
try {
    $session_id = $client->login();
} catch (RegonException $e) {
    echo "There was an error.\n";
}

if(empty($session_id)) {
    // Empty session means that api key is invalid
    
    throw new \Exception('Invalid api key');
}

登出

<?php
// Login and obtain session id (sid)
try {
    $client->login();
} catch (RegonException $e) {
    echo "There was an error.\n";
}

....

// Invalidate current session
$client->logout();

获取值

请参见API文档中可用的参数列表（第2.5节）

<?php

try {
    $value = $client->getValue('StatusSesji');
} catch (RegonException $e) {
    echo "There was an error.\n";
}

?>

搜索

<?php

$params = [
    'Regon' => 142396858, // 9 or 14 digits
    'Krs' => null, // 10 digits
    'Nip' => null, // 10 digits
    'Regony9zn' => null, // Multiple 9 digits Regon's seperated by any non digit char (max 100)
    'Regony14zn' => null, // Multiple 14 digits Regon's seperated by any non digit char (max 100)
    'Krsy' => null, // Multiple 10 digits Krs seperated by any non digit char (max 100)
    'Nipy' => null, // Multiple 10 digits Nip seperated by any non digit char (max 100)
];

try {
    $data = $client->search($params);
    
} catch (SearchException $e) {
    switch($e->getCode()) {
        case GetValue::SEARCH_ERROR_CAPTCHA: //Captcha resolve needed
            // Some code
            break;
        case GetValue::SEARCH_ERROR_INVALIDARGUMENT: //Wrong search params
            // Some code
            break;
        case GetValue::SEARCH_ERROR_NOTFOUND: //Empty result - no data found matching search params
            // Some code
            break;
        case GetValue::SEARCH_ERROR_SESSION: //Wrong session id or expired session
            // Some code
            break;
    }
} catch (RegonException $e) {
    echo "There was an error.\n";
}

报告

请参见API文档中可用的报告列表（第2.6节）

<?php

$regon = '1234567890';

try {
    $report = $client->report($regon, 'PublDaneRaportFizycznaOsoba'); 
    
} catch (SearchException $e) {
    switch($e->getCode()) {
        case GetValue::SEARCH_ERROR_CAPTCHA: //Captcha resolve needed
            // Some code
            break;
        case GetValue::SEARCH_ERROR_INVALIDARGUMENT: //Wrong search params
            // Some code
            break;
        case GetValue::SEARCH_ERROR_NOTFOUND: //Empty result - no data found matching search params
            // Some code
            break;
        case GetValue::SEARCH_ERROR_NOTAUTHORIZED: //Not authorized for this raport
            // Some code
            break;
        case GetValue::SEARCH_ERROR_SESSION: //Wrong session id or expired session
            // Some code
            break;
    }
} catch (RegonException $e) {
    echo "There was an error.\n";
}

完整示例

这是一个使用GUS客户端查询数据的示例

<?php

$client = new Client([
    'key' => YOUR_API_KEY
]);

//Enable sandbox mode for development environment
if (defined('DEVELOPMENT') && DEVELOPMENT) {
    $client->sandbox();
}

//Check if we have saved session id
$session_id = $memcache->get('gus_session_id');

if (!$session_id) {
    try {
        $session_id = $client->login();
    } catch (RegonException $e) {
        echo "There was an error.\n";
        exit;
    }
    
    //Save session_id for later use
    $memcache->save('gus_session_id', $session_id); 
} else {

    //Set current session
    $client->setSession($session_id);
}

//Try to get data
try {
    
    //Get basic data
    $data = $client->search(['Nip' => '1234567890']);
    
    //Get full comapny report
    switch($data[0]['Typ']) {
        case 'P':
        case 'LP':
            $full = $client->report($data[0]['Regon'], 'PublDaneRaportPrawna');
        break;
    
        case 'F':
        case 'LF':
            $full = $client->report($data[0]['Regon'], 'PublDaneRaportDzialalnoscFizycznejCeidg');
        break;
    }
} catch (SearchException $e) {
    switch($e->getCode()) {
        case GetValue::SEARCH_ERROR_CAPTCHA: //Captcha resolve needed
            // You need to get catpcha and show it to the user
            break;
        case GetValue::SEARCH_ERROR_INVALIDARGUMENT: //Wrong search params
            // Invalid argument passed to search/report method
            break;
        case GetValue::SEARCH_ERROR_NOTFOUND: //Empty result - no data found matching search params
            // No records where found
            $data = null;
            $full = null;
            break;
        case GetValue::SEARCH_ERROR_NOTAUTHORIZED: //Not authorized for this raport
            // You are not authorized to generate this report
            break;
        case GetValue::SEARCH_ERROR_SESSION: //Wrong session id or expired session
            // Your session has expired - You need to login again
            break;
    }
} catch (RegonException $e) {
    echo "There was an error.\n";
    exit;
}

许可

MIT许可。请参阅LICENSE文件以获取更多详细信息。