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.5(1mo ago)081↓70%proprietaryPHPPHP ^8.4CI failing

Since Mar 30Pushed 1mo 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 1w ago

READMEChangelog (6)Dependencies (21)Versions (11)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

44

—

FairBetter than 90% of packages

Maintenance92

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity58

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 ~10 days

Recently: every ~21 days

Total

10

Last Release

40d 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.3k37.6k20](/packages/tempest-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

86337.5k](/packages/flow-php-flow)[getbrevo/brevo-php

Official PHP SDK for the Brevo API.

1004.1M59](/packages/getbrevo-brevo-php)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6943.5M448](/packages/drupal-core-recommended)[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.

36826.2k2](/packages/telnyx-telnyx-php)[chargebee/chargebee-php

ChargeBee API client implementation for PHP

758.7M10](/packages/chargebee-chargebee-php)

PHPackages © 2026

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