README

Core utilities, contracts, exceptions, and foundation code for all AIArmada Commerce packages.

Purpose

This package provides shared utilities, traits, and standardized patterns used across all AIArmada Commerce packages. It eliminates code duplication and ensures consistency across the ecosystem.

Requirements

Installation

This package is automatically required by all AIArmada Commerce packages. You don't need to install it directly unless building custom extensions:

composer require aiarmada/commerce-support

Features

• Exception Hierarchy - Standardized exceptions for consistent error handling
• Payment Contracts - Universal interfaces for payment gateway integrations
• Configuration Traits - Runtime configuration validation helpers
• Helper Functions - JSONB column type resolver for PostgreSQL support
• Setup Command - Interactive wizard for configuring Commerce packages

Documentation

See the docs folder for detailed documentation:

• Exceptions - Exception hierarchy and usage
• Payment Contracts - Gateway interfaces
• Helpers - Helper functions and traits

Quick Start

Exception Handling

use AIArmada\CommerceSupport\Exceptions\CommerceException;

throw new CommerceException(
    message: 'Operation failed',
    errorCode: 'operation_failed',
    errorData: ['context' => 'value']
);

Payment Gateway

use AIArmada\CommerceSupport\Contracts\Payment\PaymentGatewayInterface;

class MyGateway implements PaymentGatewayInterface
{
    public function createPayment(
        CheckoutableInterface $checkoutable,
        ?CustomerInterface $customer = null,
        array $options = []
    ): PaymentIntentInterface;
}

Configuration Validation

use AIArmada\CommerceSupport\Traits\ValidatesConfiguration;

class MyServiceProvider extends PackageServiceProvider
{
    use ValidatesConfiguration;

    public function boot(): void
    {
        $this->validateConfiguration('mypackage', ['api_key']);
    }
}

Package Structure

commerce-support/
├── composer.json
├── LICENSE
├── README.md
├── docs/
│   ├── 01-exceptions.md
│   ├── 02-payment-contracts.md
│   └── 03-helpers.md
└── src/
    ├── SupportServiceProvider.php
    ├── helpers.php
    ├── Commands/
    ├── Contracts/
    ├── Exceptions/
    └── Traits/

License

The MIT License (MIT). See LICENSE for details.