README

Spain Gas 是一个 PHP 客户端，它作为西班牙 Geoportal Gasolineras API 的包装器。它具有以下主要特性：

获取西班牙所有加油站的信息：地址、地理位置、提供的服务、营业时间等等！
全国每个加油站精确的燃油价格，每天更新多次。
使用如构建器模式等设计模式，界面设计美观。
使用最新的 PHP 类型功能进行静态类型化。
经过适当测试，覆盖率超过 80%。

要求

您需要安装 composer，无论是全局安装还是项目本地安装。
与 PHP 7.4 或更高版本 兼容。
PHP 需要的扩展：ext-json 和 ext-simplexml。

安装

要安装此软件包，请确保已安装 composer，然后在项目目录中运行以下命令

composer require flerex/spain-gas

使用

所有 API 的端点都可以通过使用 GasApi 类获得。目前，API 只有两个端点：

gasStations：这是最有用的端点。通过它，您可以根据省份或可用性等不同过滤器找到加油站。
towns：返回 City 对象的列表。用于获取特定城镇的 ID，以便在其他端点中使用作为过滤器。
locateGasStations：此端点提供了加油站的地理位置。与上一个端点不同的是，它提供了一个根据燃油价格（如果指定为过滤器）对加油站进行排名的列表。

注意：上述所有端点都会提供燃油价格，如果使用查询过滤器 fuel 指定，否则将始终返回 null。

每个端点都返回一个 Builder 类的实例，该类提供方法来过滤要发出的请求。一旦选择了过滤参数，就需要调用 get 方法来实际运行请求并检索数据。

如果您需要有关可用过滤器的更多信息，请参阅文档。

端点

以下是所有可用端点的列表以及检索的数据差异。

* 仅在按燃料筛选时返回。

示例

按燃料获取加油站

以下是一个示例，其中我们正在检索西班牙所有压缩天然气加油站。

use Flerex\SpainGas\Enums\Fuel;
use Flerex\SpainGas\GasApi;

$stations = GasApi::gasStations()
    ->fuel(Fuel::CNG())
    ->get();

获取特定城镇 ID

假设我们需要获取阿科鲁尼亚（城市）的所有加油站。为了能够在 gasStations 端点中按城镇筛选，我们首先需要检索城镇的 ID。

use Flerex\SpainGas\Dtos\Town;
use Flerex\SpainGas\Enums\Province;
use Flerex\SpainGas\GasApi;

$towns = GasApi::towns()
    ->province(Province::A_CORUNHA())
    ->get();
    
$townId = array_filter($towns, fn(Town $town) => stripos($town->name, 'Coruña') !== false)[0];

// Everything up to this point could be done once and then be replaced with the obtained ID to avoid unnecessary API calls. 

$stations = GasApi::gasStations()
    ->town($townId)
    ->get();

获取价格排名

价格排名用于将加油站中某些燃油的价格分类，并与竞争对手进行比较。API 使用的算法是未知的。

遗憾的是，排名仅在 locateGasStations 端点中可用。

在以下示例中，我们将检索最便宜的自助加油站。

use Flerex\SpainGas\Dtos\GasStationLocation;
use Flerex\SpainGas\Enums\Rank;
use Flerex\SpainGas\Enums\Fuel;
use Flerex\SpainGas\Enums\ServiceType;
use Flerex\SpainGas\GasApi;

$stations = GasApi::locateGasStations()
    ->serviceType(ServiceType::SELF_SERVICE())
    ->fuel(Fuel::DIESEL_A())
    ->get();

$cheapest = array_filter($stations, fn(GasStationLocation $station) => $station->rank->equals(Rank::CHEAP()));

注意：我们需要指定一个燃料，以便返回排名。

变更日志

变更日志可在发布中找到。

版权和许可

西班牙天然气由 Flerex 编写，并采用 MIT 许可协议发布。

flerex / spain-gas

维护者

详细信息