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:

• Overview - Package capabilities and architecture
• Configuration - Config keys and defaults
• Usage - Choose the right support primitive or foundation guide by task
• Multi-tenancy - Owner scoping model and safety rules
• Traits & Utilities - Shared traits and helper utilities
• Isolation Primitives - Owner-scoped cache/filesystem/job helpers
• Troubleshooting - Common owner-scoping, webhook, and helper issues

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-overview.md
│   ├── 03-configuration.md
│   ├── 04-multi-tenancy.md
│   ├── 10-traits-utilities.md
│   └── 11-isolation-primitives.md
└── src/
    ├── SupportServiceProvider.php
    ├── helpers.php
    ├── Commands/
    ├── Contracts/
    ├── Exceptions/
    ├── Middleware/
    ├── Support/
    ├── Targeting/
    ├── Testing/
    ├── Traits/
    └── Webhooks/

License

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