README

此包提供了一个PHP包装器，用于与BusSystem API交互，旨在简化您的Laravel应用程序与BusSystem API之间的通信，包括公交车票预订、路线搜索和其他相关服务。

特性

• 在地点之间搜索可用的路线。
• 检索关于站点、路线、车票和折扣的详细信息。
• 管理公交车票预订，包括预订、支付和取消。
• 支持测试和生产环境。
• 缓存API响应以减少冗余请求。

要求

• PHP 8.2或更高版本
• Laravel 10.x或更高版本

安装

1. 通过Composer安装包:

   composer require nikba/bussystem

2. 发布配置文件：安装后，发布配置文件以设置您的API凭据和其他设置

   php artisan vendor:publish --provider="Nikba\BusSystem\BusSystemServiceProvider"

3. 配置：在您的.env文件中，添加以下配置

   BUSSYSTEM_API_LOGIN=your_login_here
   BUSSYSTEM_API_PASSWORD=your_password_here
   BUSSYSTEM_API_TEST_MODE=true
   BUSSYSTEM_API_LANG=en

   以下环境变量将在配置文件（config/bussystem.php）中使用，您也可以进行自定义

   return [
       'login' => env('BUSSYSTEM_API_LOGIN', ''),
       'password' => env('BUSSYSTEM_API_PASSWORD', ''),
       'test_mode' => env('BUSSYSTEM_API_TEST_MODE', true),
       'lang' => env('BUSSYSTEM_API_LANG', 'en'),
       'endpoints' => [
           'test' => 'https://test-api.bussystem.eu/server',
           'production' => 'https://api.bussystem.eu/server',
       ],
       'cache_times' => [
           'get_points' => 525600, // 1 year in minutes
           'get_routes' => 1440,   // 1 day in minutes
           'get_baggage' => 720,   // 12 hours
           // Add other cache times as needed
       ],
   ];

4. 添加服务提供者（如有需要）：Laravel会自动检测服务提供者，但如果您使用的是较旧版本，您可能需要手动将其添加到config/app.php文件中

   'providers' => [
       Nikba\BusSystem\BusSystemServiceProvider::class,
   ],

5. 添加外观别名（可选）：如果您想使用外观

   'aliases' => [
       'BusApi' => Nikba\BusSystem\Facades\BusApi::class,
   ],

用法

安装后，您可以通过BusApi外观或底层的服务类Nikba\BusSystem\Services\BusApiService与BusSystem API交互。

示例：获取站点（城市或地点）

$points = BusApi::getPoints([
    'country_id' => 1, // Optional country filter
    'autocomplete' => 'Prague', // Optional search filter
    'trans' => 'bus', // Type of transport: [all, bus, train, air, etc.]
]);

函数和参数

1. getPoints()

描述：根据国家或运输类型等过滤器获取可用站点（城市、车站或机场）的列表。

参数:

• country_id（可选）：按国家ID过滤。
• autocomplete（可选）：按匹配地点名称的初始字符进行过滤。
• trans：运输类型[all, bus, train, air, travel, hotel]。

示例:

$points = BusApi::getPoints([
    'country_id' => 1,
    'autocomplete' => 'Praha',
    'trans' => 'bus'
]);

2. getRoutes()

描述：检索特定日期两个地点之间的可用公交车路线。

参数:

• id_from：出发城市ID。
• id_to：到达城市ID。
• date：出发日期（格式：yyyy-mm-dd）。
• trans：运输类型[all, bus, train, air]。

示例:

$routes = BusApi::getRoutes([
    'id_from' => 3, // Praha
    'id_to' => 6,   // Kiev
    'date' => '2024-09-09',
    'trans' => 'bus'
]);

3. getBaggage()

描述：检索指定路线和区间的行李信息。

参数:

• interval_id：从getRoutes请求中获取的区间ID。
• station_from_id：出发站ID。
• station_to_id：到达站ID。
• currency：响应货币[EUR, RON, PLN, MDL等.]。

示例:

$baggage = BusApi::getBaggage([
    'interval_id' => '90|gh340|d29-96',
    'station_from_id' => 1547,
    'station_to_id' => 757,
    'currency' => 'EUR'
]);

4. getFreeSeats()

描述：检索指定路线和区间可用的座位。

参数:

• interval_id：从getRoutes请求中获取的区间ID。
• train_id：（对于火车）火车ID。
• vagon_id：（对于火车）车厢ID。
• currency：响应货币。

示例:

$freeSeats = BusApi::getFreeSeats([
    'interval_id' => '90|gh340|d29-96',
    'train_id' => '141Sh',
    'vagon_id' => '14BLB',
    'currency' => 'EUR'
]);

5. newOrder()

描述：根据可用路线和选定的乘客创建新的车票订单。

参数:

• date：出发日期。
• interval_id：路线的区间ID。
• station_from_id：出发站ID。
• station_to_id：到达站ID。
• seat：选定的座位号。
• name：乘客姓名。
• surname：乘客姓氏。
• birth_date：乘客出生日期。
• doc_type：文件类型。
• doc_number：文件号码。
• doc_expire_date：文件到期日期。

示例:

$order = BusApi::newOrder([
    'date' => ['2024-09-09'],
    'interval_id' => ['ju34hd|30122023|30122023'],
    'station_from_id' => [1547],
    'station_to_id' => [757],
    'seat' => [["32"]],
    'name' => ['John'],
    'surname' => ['Doe'],
    'birth_date' => ['2000-01-01'],
    'doc_type' => [1],
    'doc_number' => ['CZRE5752475-54'],
    'doc_expire_date' => ['2045-12-30'],
    'citizenship' => ['UK'],
    'gender' => ['M'],
]);

6. cancelTicket()

描述：取消未付款订单或全额或部分退款已付款的车票。

参数:

• order_id：要取消的订单ID。
• ticket_id：要取消的票务ID。
• session：您的会话。

示例:

$response = BusApi::cancelTicket([
    'order_id' => 5397146,
    'ticket_id' => 4461298,
    'session' => 'c227e552956b'
]);

测试

本包包含PHPUnit测试。要运行测试

1. 安装依赖

   composer install

2. 运行测试

   vendor/bin/phpunit

缓存

为了效率，API响应被缓存。不同端点的缓存时长可以在config/bussystem.php文件下的cache_times中进行自定义。

例如，要将getRoutes函数的缓存时长设置为1天（1440分钟）

'cache_times' => [
    'get_routes' => 1440,   // 1 day in minutes
],

许可证

本包是开源软件，遵循MIT许可证。

支持

对于任何问题，请随意在GitHub上提交问题或联系开发者office@nikba.com。