PHPackages                             atlasflow/order-bridge - 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. atlasflow/order-bridge

ActiveLibrary[API Development](/categories/api)

atlasflow/order-bridge
======================

Serialisation, validation and transport for the Atlas Core Order Bridge API.

v1.3.2(2mo ago)053↓81.8%proprietaryPHPPHP ^8.4CI failing

Since Mar 30Pushed 2mo agoCompare

[ Source](https://github.com/atlasflow/order-bridge)[ Packagist](https://packagist.org/packages/atlasflow/order-bridge)[ RSS](/packages/atlasflow-order-bridge/feed)WikiDiscussions main Synced 4w ago

READMEChangelog (6)Dependencies (14)Versions (8)Used By (0)

Atlas Core Order Bridge
=======================

[](#atlas-core-order-bridge)

[![Software License](https://camo.githubusercontent.com/074b89bca64d3edc93a1db6c7e3b1636b874540ba91d66367c0e5e354c56d0ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e737667)](LICENSE.md)

A framework-agnostic PHP package for serialising, validating, and transporting orders between Atlas Core and host applications (ePOS, E-commerce, etc.) according to the **Order Bridge API Specification v1.4.2**.

Core Concepts
-------------

[](#core-concepts)

The package owns two things exclusively:

1. **Serialisation**: Converting host application data into spec-compliant JSON payloads.
2. **Validation**: Enforcing all schema and arithmetic rules defined in the specification.

It is designed to be **unopinionated about persistence**. It does not include Eloquent models, migrations, or database logic. Instead, it defines a set of **Interfaces** that your application's models must implement.

Key Components
--------------

[](#key-components)

- **`OrderSerialiser`**: Takes objects implementing `OrderInterface` and produces a fully validated payload array. It handles all complex arithmetic (VAT, line totals, grand totals) using `bcmath` internally.
- **`PayloadValidator`**: Implements all rules from §5 of the spec, including arithmetic verification and idempotency checks.
- **`HttpTransport`**: A thin PSR-18 compatible layer for sending payloads to Atlas Core.
- **`InboundParser`**: The reverse direction—parses and validates JSON from Atlas Core into typed DTOs.
- **`TransferIdManager`**: Utility for generating and managing `transfer_id` GUIDs to ensure idempotency.

---

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

[](#installation)

```
composer require atlasflow/order-bridge
```

*Note: Requires PHP 8.4+ and the `bcmath` extension.*

---

Usage Instructions
------------------

[](#usage-instructions)

### 1. Implement the Interfaces

[](#1-implement-the-interfaces)

The package never touches your models directly. You must create "Adapters" that wrap your models and implement the interfaces in `Atlasflow\OrderBridge\Contracts`.

```
use Atlasflow\OrderBridge\Contracts\OrderInterface;
use Atlasflow\OrderBridge\Contracts\LineItemInterface;
// ... and other contracts

class MyOrderAdapter implements OrderInterface
{
    public function __construct(private MyOrderModel $order) {}

    public function getOriginRef(): string { return $this->order->reference; }
    public function getStatus(): string { return 'pos'; }
    // ... implement remaining methods
}
```

### 2. Serialise and Send

[](#2-serialise-and-send)

The `OrderSerialiser` computes all totals for you. You only provide raw values (quantities, unit prices, discount percentages, and VAT rates).

```
use Atlasflow\OrderBridge\Serialiser\OrderSerialiser;
use Atlasflow\OrderBridge\Transport\HttpTransport;

// 1. Setup Serialiser
$serialiser = new OrderSerialiser([
    'site_id' => 'site_richmond',
    'site_name' => 'The Palm Centre',
    'source_type' => 'cassa',
]);

// 2. Serialise your order(s)
// $orders should be an iterable of OrderInterface
$payload = $serialiser->serialise($orders, trigger: 'realtime');

// 3. Send via HTTP (requires a PSR-18 client and PSR-17 factories)
$transport = new HttpTransport($httpClient, $requestFactory, $streamFactory, $endpointUrl);
$result = $transport->send($payload);

if ($result->isSuccess()) {
    // Mark order as synced in your DB
}
```

### 3. Validate a Payload

[](#3-validate-a-payload)

You can use the validator independently to dry-run a batch or validate inbound webhooks.

```
use Atlasflow\OrderBridge\Validator\PayloadValidator;

$validator = new PayloadValidator();
$result = $validator->validate($payloadArray);

if (!$result->isValid()) {
    foreach ($result->getViolations() as $violation) {
        echo "Error in {$violation->field}: {$violation->message}\n";
    }
}
```

### 4. Parse Inbound Payloads

[](#4-parse-inbound-payloads)

When receiving an export from Atlas Core, use the `InboundParser` to get typed DTOs.

```
use Atlasflow\OrderBridge\Parser\InboundParser;

$parser = new InboundParser();
try {
    $envelope = $parser->parse($jsonString);

    foreach ($envelope->orders as $orderDto) {
        // Map DTO back to your application models
        echo $orderDto->originRef;
    }
} catch (ParseException $e) {
    // Handle malformed JSON or validation failure
}
```

---

Idempotency
-----------

[](#idempotency)

The package automatically generates a `transfer_id` (UUID v4) during serialisation. Atlas Core uses this ID combined with your `site_id` to prevent duplicate order processing.

If you need to retry a failed transport attempt:

1. **Identical Retries**: Reuse the same payload (and thus the same `transfer_id`). Core will acknowledge the retry without creating duplicate records.
2. **Modified Payloads**: If the content changes, you **must** generate a new `transfer_id` by re-serialising the order.

---

Laravel Integration
-------------------

[](#laravel-integration)

The package ships with a first-class Laravel service provider that handles configuration publishing and wires everything up automatically.

### Auto-discovery

[](#auto-discovery)

Laravel 5.5+ will auto-discover the service provider. No manual registration is needed.

### Publish the configuration file

[](#publish-the-configuration-file)

```
php artisan vendor:publish --tag=order-bridge-config
```

This copies `config/order-bridge.php` into your application's `config/` directory.

### Configuration reference

[](#configuration-reference)

KeyDefaultDescription`tolerance``'0.0001'`Arithmetic tolerance for §5.3 validation checks.`monetary_scale``4`Decimal places for all monetary output fields.`discount_scale``6`Decimal places for discount percentage strings.`vat_rounding_scale``2`Decimal places to which VAT amounts are rounded before output. Set to `4` to disable the extra rounding step.`vat_rounding_mode``'ceil'`Rounding direction for VAT amounts. `'ceil'` rounds toward positive infinity (always up for positive values); `'floor'` rounds toward negative infinity.### Manual registration (without auto-discovery)

[](#manual-registration-without-auto-discovery)

Add the provider to `config/app.php`:

```
'providers' => [
    Atlasflow\OrderBridge\Laravel\OrderBridgeServiceProvider::class,
],
```

### Framework-agnostic usage

[](#framework-agnostic-usage)

Outside of Laravel the package works out of the box with sensible defaults. If you need to override the defaults at runtime, call `SchemaVersion::configure()` early in your bootstrap:

```
use Atlasflow\OrderBridge\SchemaVersion;

SchemaVersion::configure([
    'vat_rounding_mode' => 'floor',
    'vat_rounding_scale' => 2,
]);
```

---

License
-------

[](#license)

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

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance84

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

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

Every ~1 days

Total

7

Last Release

82d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f68447628fda07406fb838fc490d8935d415088a93ec70584f59db2f719637c4?d=identicon)[mcpuishor](/maintainers/mcpuishor)

---

Tags

phpBridgeERPorderatlasflowatlascore

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/atlasflow-order-bridge/health.svg)

```
[![Health](https://phpackages.com/badges/atlasflow-order-bridge/health.svg)](https://phpackages.com/packages/atlasflow-order-bridge)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60315.4M74](/packages/mollie-mollie-api-php)[php-tmdb/api

PHP wrapper for TMDB (TheMovieDatabase) API v3. Supports two types of approaches, one modelled with repositories, models and factories. And the other by simple array access to RAW data from The Movie Database.

427382.4k17](/packages/php-tmdb-api)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

1003.6M46](/packages/getbrevo-brevo-php)[wtfzdotnet/php-tmdb-api

PHP wrapper for TMDB (TheMovieDatabase) API v3. Supports two types of approaches, one modelled with repositories, models and factories. And the other by simple array access to RAW data from The Movie Database.

4262.9k](/packages/wtfzdotnet-php-tmdb-api)

PHPackages © 2026

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