README

这是一个用于处理World API的PHP库。

要求

PHP 8.1及更高版本。

Packagist

使用packagist安装

composer require weblabormx/world

别忘了包含绑定

require_once __DIR__ . '/vendor/autoload.php';

初始化凭据

您可以选择使用以下方式通过World静态类与库一起工作

use WeblaborMx\World\World;

// World::setApiBase("https://world.weblabor/api"); # Optionally set an alternative base
World::init(apiKey: "YOUR_API_KEY");

$client = World::getClient();

// Do stuff...

或者通过实例化客户端对象

use WeblaborMx\World\Client;

$client = new Client(
    apiKey: 'YOUR_API_KEY',
    // apiBase: 'https://world.weblabor/api',
);

// Do stuff...

静态方式是推荐的。

划分

API通过获取世界不同级别的划分来工作。您可能通常将它们称为国家、州和城市，但其他国家有不同的称呼，并且有超过3个级别。

因此，世界根据每个不同的主权国家以不同的方式划分。

我们通常称主权国家为最高级别的划分，即国家。国家的子级为州。这些州的子级为城市。这是API的使用方式，通过遍历不同级别的划分。一个划分有children()和parent()方法，除非它是最高级或最低级的划分。

属性

所有来自划分端点的调用，返回一个WeblaborMx\World\Entities\Division对象或数组。

您可以通过检查类构造函数来检查属性

public function __construct(
    public int $id,
    public ?string $name = null,
    public ?string $country = null,
    public ?string $a1code = null,
    public ?string $level = null,
    public ?int $population = null,
    public ?float $lat = null,
    public ?float $long = null,
    public ?string $timezone = null,
    public ?int $parent_id = null,
) {
}

端点

在文档中检查所有端点。

获取所有国家

您可能想从最高级别开始获取划分。

use WeblaborMx\World\World;
use WeblaborMx\World\Entities\Division;

$client = World::getClient();

/** @var Division[] **/
$countries = $client->makeCall('/countries');

foreach ($countries as $division) {
    echo $division->name . \PHP_EOL;
}

按代码获取国家

您可以通过其ISO-3166代码搜索国家。

use WeblaborMx\World\World;
use WeblaborMx\World\Entities\Division;

$client = World::getClient();

$code = "MX";

/** @var Division|null **/
$country = $client->makeCall("/country/{$code}");

获取特定划分

要获取特定划分，请传递之前获得的ID。

use WeblaborMx\World\Entities\Division;

$id = 3531011; // Probably want to obtain it from the DB

/** @var Division|null **/
$division = Division::get($id);

获取所有子划分

/** @var Division[] **/
$children = $division->children();

获取父划分

/** @var Division|null **/
$parent = $division->parent();

与Laravel一起工作

为了保持库轻量级，没有添加任何依赖。但是，您可以在Laravel中找到一个Division类型转换类，尽管它没有实现Laravel的合约，但它应该像任何其他转换一样工作。

有了转换，您可以在模型中保存任何获得的ID，并在再次访问属性时自动获得Division。

use Illuminate\Database\Eloquent\Model;
use WeblaborMx\World\Casts\DivisionCast;

class Company extends Model
{
    protected $casts = [
        'country' => DivisionCast::class,
        'state' => DivisionCast::class,
    ];

    // ...
}

注册客户端

您可能希望通过服务提供程序（如AppServiceProvider）初始化客户端。

public function boot(): void
{
    // World::setApiBase(config('services.weblabor.world.endpoint'));
    World::init(apiKey: config('services.weblabor.world.token'));
}

然后设置services.php配置。

return [
    // ...
    'weblabor' => [
        'world' => [
            'endpoint' => env('WEBLABOR_WORLD_ENDPOINT', 'https://world.weblabor.mx/api'),
            'token' => env('WEBLABOR_WORLD_TOKEN'),
        ]
    ]
]

并在.env中设置凭据。

WEBLABOR_WORLD_ENDPOINT=
WEBLABOR_WORLD_TOKEN=

weblabormx / world

维护者

详细信息