v0.9.5

Order Management

Orchestrate orders from checkout to fulfillment. Handle complex workflows, rigorous status transitions, and shipment tracking without the spaghetti code.

Getting Started

Installation

 $ composer require obelaw/ium-oms

Publish Configuration

 $ php artisan vendor:publish --tag=ium-oms-config

Run Migrations

 $ php artisan migrate

Requirements

• PHP 8.2+
• Laravel 10+
• MySQL 8.0+ or PostgreSQL 14+

Orders

Orders are the central entity in IUM-OMS. Create, update, and transition orders through configurable status workflows with full audit logging.

Creating an Order

use Obelaw\Ium\Oms\Actions\CreateOrder;

$order = CreateOrder::run([
    'customer_id' => 42,
    'currency' => 'USD',
    'items' => [
        ['sku' => 'WIDGET-001', 'qty' => 2, 'price' => 29.99],
        ['sku' => 'WIDGET-002', 'qty' => 1, 'price' => 49.99],
    ],
]);

Order Statuses

Pending → Processing → Shipped → Delivered

Workflows

Define custom status transitions with guards, actions, and notifications. The workflow engine validates every transition and prevents invalid state changes.

Transitioning an Order

use Obelaw\Ium\Oms\Actions\TransitionOrder;

// Move order to processing
TransitionOrder::run($order, 'processing');

// Invalid transitions throw an exception
TransitionOrder::run($order, 'delivered'); // ❌ WorkflowException

Guards

• Payment verification
• Stock availability check
• Address validation
• Custom guard classes

Side Effects

• Email notifications
• Stock reservation / release
• Invoice generation
• Webhook dispatching

Shipments

Create shipments from orders with carrier integration. Track parcels and handle partial shipments for split deliveries.

Creating a Shipment

use Obelaw\Ium\Oms\Actions\CreateShipment;

$shipment = CreateShipment::run($order, [
    'carrier' => 'fedex',
    'tracking_number' => '7489236401',
    'items' => [
        ['sku' => 'WIDGET-001', 'qty' => 2],
    ],
]);

Invoices

Generate invoices automatically on order transitions or manually. Invoices support line-item totals, tax calculation, and credit memos.

Generating an Invoice

use Obelaw\Ium\Oms\Actions\GenerateInvoice;

$invoice = GenerateInvoice::run($order);

$invoice->number;      // INV-2026-0042
$invoice->subtotal;    // 109.97
$invoice->tax;         // 9.90
$invoice->total;       // 119.87