PHPackages                             nikba/laravel-bussystem-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. nikba/laravel-bussystem-api

ActiveLibrary[API Development](/categories/api)

nikba/laravel-bussystem-api
===========================

Laravel package providing seamless integration with BusSystem transportation services

v1.0.0(10mo ago)03MITPHPPHP ^8.1CI passing

Since Jun 23Pushed 10mo agoCompare

[ Source](https://github.com/Nikba-Creative-Studio/Laravel-Bussystem-Api)[ Packagist](https://packagist.org/packages/nikba/laravel-bussystem-api)[ Docs](https://github.com/Nikba-Creative-Studio/Laravel-Bussystem-Api)[ RSS](/packages/nikba-laravel-bussystem-api/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (7)Versions (2)Used By (0)

Laravel BusSystem API
=====================

[](#laravel-bussystem-api)

[![Latest Version on Packagist](https://camo.githubusercontent.com/43be00f092ccd5803108600ad24db59684618f2d55e0b85fa3fa2b72d1e85fe2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e696b62612f6c61726176656c2d62757373797374656d2d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nikba/laravel-bussystem-api)[![Total Downloads](https://camo.githubusercontent.com/8d42f67c5e79ba2b0360149ff88e9943943bcf34ff35e53189e54f38fa864270/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e696b62612f6c61726176656c2d62757373797374656d2d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nikba/laravel-bussystem-api)[![GitHub Tests Action Status](https://camo.githubusercontent.com/65018ab932b48b684d8bc106d5d6ddbdf161a114308b38c9e907f616788da94b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f6e696b62612d63726561746976652d73747564696f2f6c61726176656c2d62757373797374656d2d6170692f72756e2d74657374733f6c6162656c3d7465737473)](https://github.com/nikba-creative-studio/laravel-bussystem-api/actions?query=workflow%3Arun-tests+branch%3Amain)

Laravel package providing seamless integration with BusSystem transportation services. This comprehensive SDK enables easy integration with BusSystem's passenger transportation API for bus, train, and air travel booking.

Features
--------

[](#features)

- 🚌 **Multi-Transport Support** - Bus, train, and air travel integration
- 🎫 **Complete Booking Flow** - Search, book, pay, and manage tickets
- 💺 **Seat Management** - Detailed seat selection and layout support
- 💳 **Payment Processing** - Secure payment handling and order management
- 📱 **Mobile-Friendly** - Payment on boarding and SMS validation
- 🏗️ **Laravel Integration** - Native Laravel service provider and facades
- 🔄 **Caching Support** - Built-in caching for improved performance
- 📊 **Database Models** - Eloquent models for order and ticket management
- 🧪 **Testing Support** - Comprehensive test suite and mocking capabilities

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require nikba/laravel-bussystem-api
```

Publish the configuration file:

```
php artisan vendor:publish --provider="Nikba\LaravelBussystemApi\BusSystemServiceProvider" --tag="bussystem-config"
```

Optionally, publish the database migrations:

```
php artisan vendor:publish --provider="Nikba\LaravelBussystemApi\BusSystemServiceProvider" --tag="bussystem-migrations"
php artisan migrate
```

Configuration
-------------

[](#configuration)

Add your BusSystem API credentials to your `.env` file:

```
BUSSYSTEM_API_URL=https://test-api.bussystem.eu/server
BUSSYSTEM_LOGIN=your_login
BUSSYSTEM_PASSWORD=your_password
BUSSYSTEM_PARTNER_ID=your_partner_id
BUSSYSTEM_DEFAULT_CURRENCY=EUR
BUSSYSTEM_DEFAULT_LANGUAGE=en
```

Basic Usage
-----------

[](#basic-usage)

### Search for Routes

[](#search-for-routes)

```
use Nikba\LaravelBussystemApi\Data\SearchCriteria;
use Nikba\LaravelBussystemApi\Facades\BusSystem;

// Create search criteria
$criteria = SearchCriteria::create()
    ->date('2024-12-31')
    ->from(3) // Prague
    ->to(7)   // Vienna
    ->bus()
    ->currency('EUR')
    ->language('en');

// Search for routes
$routes = BusSystem::getRoutes($criteria);
```

### Create a Booking

[](#create-a-booking)

```
use Nikba\LaravelBussystemApi\Data\BookingData;

// Create booking data
$booking = BookingData::create('EUR', 'en')
    ->addRoute('2024-12-31', 'interval_id_from_search')
    ->addPassenger('John', 'Doe', '1990-01-01', 1, 'AB123456', 'M')
    ->addPassenger('Jane', 'Doe', '1992-02-02', 1, 'CD789012', 'F')
    ->addSeats(0, ['1', '2'])
    ->setContactInfo('+1234567890', 'john@example.com');

// Validate booking data
$errors = $booking->validate();
if (!empty($errors)) {
    // Handle validation errors
    foreach ($errors as $error) {
        echo $error . "\n";
    }
    return;
}

// Create order
$order = BusSystem::createOrder($booking);
echo "Order ID: " . $order['order_id'];
echo "Reservation until: " . $order['reservation_until'];
```

### Complete Payment

[](#complete-payment)

```
// Buy tickets for the order
$orderId = $order['order_id'];
$tickets = BusSystem::buyTickets($orderId, 'en');

// Access ticket information
foreach ($tickets['item'] as $ticket) {
    echo "Ticket ID: " . $ticket['ticket_id'];
    echo "PDF Link: " . $ticket['link'];
}
```

### Using Dependency Injection

[](#using-dependency-injection)

```
use Nikba\LaravelBussystemApi\Contracts\BusSystemClientInterface;

class BookingController extends Controller
{
    public function __construct(
        private BusSystemClientInterface $busSystem
    ) {}

    public function searchRoutes(Request $request)
    {
        $criteria = SearchCriteria::create()
            ->date($request->date)
            ->from($request->from_city_id)
            ->to($request->to_city_id)
            ->transport($request->transport)
            ->currency($request->currency ?? 'EUR');

        return $this->busSystem->getRoutes($criteria);
    }
}
```

Advanced Usage
--------------

[](#advanced-usage)

### Air Travel Booking

[](#air-travel-booking)

```
// Search for flights
$criteria = SearchCriteria::create()
    ->date('2024-12-31')
    ->airportFrom('PRG') // Prague Airport
    ->airportTo('VIE')   // Vienna Airport
    ->air()
    ->airPassengers(2, 1, 0) // 2 adults, 1 child, 0 infants
    ->airServiceClass('E')    // Economy
    ->airDirect(false);       // Allow connections

$flights = BusSystem::getRoutes($criteria);

// Create flight booking
$booking = BookingData::create()
    ->addRoute('2024-12-31', $flights[0]['interval_id'])
    ->addPassenger('John', 'Doe', '1990-01-01', 1, 'AB123456', 'M', null, 'US', '2030-01-01')
    ->addPassenger('Jane', 'Doe', '1992-02-02', 1, 'CD789012', 'F', null, 'US', '2030-02-02')
    ->addPassenger('Johnny', 'Doe', '2020-03-03', 3, 'EF345678', 'M') // Child
    ->addSeats(0, ['adt', 'adt', 'chd']) // Adult, Adult, Child
    ->setContactInfo('+1234567890', 'john@example.com');
```

### Train Booking with Wagon Selection

[](#train-booking-with-wagon-selection)

```
// Search for train routes
$criteria = SearchCriteria::create()
    ->date('2024-12-31')
    ->trainFrom(2200001) // Kyiv train station
    ->trainTo(5400076)   // Prague train station
    ->train();

$routes = BusSystem::getRoutes($criteria);
$route = $routes[0];

// Get available wagons
$wagons = BusSystem::getFreeSeats($route['interval_id'], [
    'train_id' => $route['train_id'][0]
]);

// Get seats in selected wagon
$wagonId = $wagons[0]['vagon']['item'][0]['vagon_id'];
$seats = BusSystem::getFreeSeats($route['interval_id'], [
    'vagon_id' => $wagonId
]);

// Create booking with wagon and seat selection
$booking = BookingData::create()
    ->addRoute('2024-12-31', $route['interval_id'])
    ->addWagon(0, $wagonId)
    ->addPassenger('John', 'Doe', '1990-01-01', 1, 'AB123456', 'M')
    ->addSeats(0, ['1']) // Seat number from seats response
    ->setContactInfo('+1234567890', 'john@example.com');
```

### Payment on Boarding

[](#payment-on-boarding)

```
// Validate phone number for payment on boarding
$validation = BusSystem::validateReservation('+1234567890', 'en');

if ($validation['reserve_validation'] === '1') {
    if ($validation['need_sms_validation'] === '1') {
        // Send SMS verification
        $smsResult = BusSystem::validateSms([
            'sid_guest' => session()->getId(),
            'phone' => '+1234567890',
            'send_sms' => 1,
            'lang' => 'en'
        ]);

        // User enters SMS code, then verify
        $verification = BusSystem::validateSms([
            'sid_guest' => session()->getId(),
            'phone' => '+1234567890',
            'check_sms' => 1,
            'validation_code' => $request->sms_code,
            'lang' => 'en'
        ]);
    }

    // Reserve tickets for payment on boarding
    $reservation = BusSystem::reserveTickets($orderId, [
        'phone' => '+1234567890',
        'email' => 'john@example.com',
        'lang' => 'en'
    ]);
}
```

### Working with Seat Plans

[](#working-with-seat-plans)

```
// Get seat layout for visual selection
$seatPlan = BusSystem::getSeatPlan([
    'bustype_id' => $route['bustype_id'],
    'position' => 'h', // horizontal layout
    'v' => '2.0'
]);

// Process seat plan for frontend
foreach ($seatPlan['floors'] as $floor) {
    foreach ($floor['rows'] as $row) {
        foreach ($row['seat'] as $seat) {
            if (is_string($seat) && !empty($seat)) {
                echo "Seat: " . $seat . "\n";
            } elseif (is_array($seat) && isset($seat['icon'])) {
                echo "Icon: " . $seat['icon'] . "\n";
            }
        }
    }
}
```

### Order Management

[](#order-management)

```
// Get order details
$orderDetails = BusSystem::getOrder($orderId, $securityCode, 'en');

// Get specific ticket information
$ticketInfo = BusSystem::getTicket([
    'ticket_id' => $ticketId,
    'security' => $ticketSecurityCode,
    'lang' => 'en'
]);

// Cancel tickets
$cancellation = BusSystem::cancelTickets([
    'order_id' => $orderId,
    'security' => $securityCode,
    'lang' => 'en',
    'v' => '1.1'
]);

echo "Refund amount: " . $cancellation['money_back_total'];
```

Database Models
---------------

[](#database-models)

The package includes Eloquent models for storing booking data:

### Order Model

[](#order-model)

```
use Nikba\LaravelBussystemApi\Models\Order;

// Create order record
$order = Order::create([
    'order_id' => $apiResponse['order_id'],
    'security_code' => $apiResponse['security'],
    'status' => $apiResponse['status'],
    'price_total' => $apiResponse['price_total'],
    'currency' => 'EUR',
    'passenger_count' => 2,
    'route_count' => 1,
    'phone' => '+1234567890',
    'email' => 'john@example.com',
    'reservation_until' => $apiResponse['reservation_until'],
    'api_response' => $apiResponse,
    'user_id' => auth()->id(),
]);

// Query orders
$userOrders = Order::forUser(auth()->id())->active()->get();
$expiredOrders = Order::expired()->get();
$paidOrders = Order::paid()->get();
```

### Ticket Model

[](#ticket-model)

```
use Nikba\LaravelBussystemApi\Models\Ticket;

// Create ticket records
foreach ($ticketsResponse['item'] as $ticketData) {
    Ticket::create([
        'order_id' => $order->id,
        'ticket_id' => $ticketData['ticket_id'],
        'transaction_id' => $ticketData['transaction_id'],
        'security_code' => $ticketData['security'],
        'passenger_name' => 'John',
        'passenger_surname' => 'Doe',
        'price' => $ticketData['price'],
        'currency' => 'EUR',
        'status' => 'buy',
        'pdf_link' => $ticketData['link'],
        'api_response' => $ticketData,
    ]);
}

// Query tickets
$activeTickets = Ticket::active()->get();
$upcomingTrips = Ticket::departingAfter(now())->get();
```

Error Handling
--------------

[](#error-handling)

The package provides specific exception types for different error scenarios:

```
use Nikba\LaravelBussystemApi\Exceptions\BusSystemAuthenticationException;
use Nikba\LaravelBussystemApi\Exceptions\BusSystemValidationException;
use Nikba\LaravelBussystemApi\Exceptions\BusSystemApiException;

try {
    $routes = BusSystem::getRoutes($criteria);
} catch (BusSystemAuthenticationException $e) {
    // Handle authentication errors (invalid credentials)
    Log::error('BusSystem authentication failed: ' . $e->getMessage());
} catch (BusSystemValidationException $e) {
    // Handle validation errors (missing required data)
    return response()->json(['error' => $e->getMessage()], 422);
} catch (BusSystemApiException $e) {
    // Handle general API errors
    Log::error('BusSystem API error: ' . $e->getMessage());
    return response()->json(['error' => 'Service temporarily unavailable'], 503);
}
```

Caching
-------

[](#caching)

The package supports automatic caching of API responses to improve performance:

```
// Caching is configured in config/bussystem.php
'cache' => [
    'enabled' => env('BUSSYSTEM_CACHE_ENABLED', true),
    'prefix' => env('BUSSYSTEM_CACHE_PREFIX', 'bussystem'),
    'ttl' => [
        'points' => env('BUSSYSTEM_CACHE_POINTS_TTL', 3600), // 1 hour
        'routes' => env('BUSSYSTEM_CACHE_ROUTES_TTL', 300),  // 5 minutes
        'plans' => env('BUSSYSTEM_CACHE_PLANS_TTL', 86400),  // 24 hours
    ],
],
```

Testing
-------

[](#testing)

Run the tests with:

```
composer test
```

Run tests with coverage:

```
composer test-coverage
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Nicolai Bargan](https://www.linkedin.com/in/nicolai-bargan/)
- [Nikba Creative Studio](https://github.com/nikba-creative-studio)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

API Documentation
-----------------

[](#api-documentation)

For complete API documentation, visit: [BusSystem API Documentation](https://nikba-creative-studio.github.io/Laravel-Bussystem-Api/)

Support
-------

[](#support)

- **Documentation Issues**: [GitHub Issues](https://github.com/Nikba-Creative-Studio/Laravel-Bussystem-Api/issues)
- **API Support**: Contact BusSystem support
- **Package Support**: [GitHub Discussions](https://github.com/Nikba-Creative-Studio/Laravel-Bussystem-Api/discussions)

###  Health Score

29

—

LowBetter than 60% of packages

Maintenance56

Moderate activity, may be stable

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

320d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0bcd10cd5a6707af2160f69291d06ff63cada1a920921edf7e3a4bdca6950c84?d=identicon)[nikba](/maintainers/nikba)

---

Top Contributors

[![Nikba-Creative-Studio](https://avatars.githubusercontent.com/u/41567806?v=4)](https://github.com/Nikba-Creative-Studio "Nikba-Creative-Studio (23 commits)")

---

Tags

apilaravelbookingtraveltransportationbussystem

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/nikba-laravel-bussystem-api/health.svg)

```
[![Health](https://phpackages.com/badges/nikba-laravel-bussystem-api/health.svg)](https://phpackages.com/packages/nikba-laravel-bussystem-api)
```

###  Alternatives

[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[resend/resend-laravel

Resend for Laravel

1191.4M6](/packages/resend-resend-laravel)[smodav/mpesa

M-Pesa API implementation

16363.7k1](/packages/smodav-mpesa)[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[ardakilic/mutlucell

Mutlucell SMS API wrapper for sending sms text messages for Laravel

457.3k](/packages/ardakilic-mutlucell)[dragon-code/laravel-json-response

Automatically always return a response in JSON format

1118.6k1](/packages/dragon-code-laravel-json-response)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)