README

Laravel package (a2-atu/a2commerce) for a decoupled, event-driven e-commerce core: cart, checkout helpers, PayPal, guest checkout, wishlist, and comparison—aligned with Vormia (package-first models/traits) and Livewire 4.

Versioning: Release lines are tagged in Git. At runtime, A2\A2Commerce\Support\PackageInfo::version() (and the container binding a2commerce.version) resolve the installed version via Composer’s InstalledVersions API—no duplicated constant in source.

Breaking change (current major)

This line is package-first only: the installer does not edit routes/api.php, does not remove stub-copied app/ trees, and does not delete legacy migration PHP files from the host database/migrations folder. If you still have artifacts from an old copy-based workflow, remove or migrate them manually before upgrading, or stay on the previous major.

How this package is structured

• Runtime code lives in A2\A2Commerce\... and is autoloaded from vendor (like Vormia’s Vormia\Vormia\...). It is not copied into app/Models, app/Services, etc.
• Migrations ship with the package and load via A2CommerceServiceProvider (php artisan migrate in the host app).
• Config is merged as config('a2_commerce.*'). Optionally publish:
  php artisan vendor:publish --tag=a2commerce-config
• Events / listeners are registered by A2\A2Commerce\Providers\A2CommerceEventServiceProvider (no need to duplicate the full map in AppServiceProvider unless you add extra listeners).
• PayPal webhook is registered by the package:
  POST /api/a2/payment/paypal/webhook
  Route name: api.payment.paypal.webhook
  Controller: A2\A2Commerce\Http\Controllers\A2\Commerce\PaymentController
• Payment confirmation emails are plain text mailables in the package (A2\A2Commerce\Mail\...); no Blade views in the package for those.
• Storefront UI (Livewire Volt/Blade routes, buyer middleware, marketing pages) remains in the host application; this package provides domain services, models, jobs, and HTTP entrypoints you route to.

For end-to-end storefront patterns, see packageflow-md/0-a_2_commerce_implementation_guide.md.

Requirements

• PHP 8.2+
• Laravel 12.x or 13.x (illuminate/* aligned with Vormia’s constraints)
• vormiaphp/vormia ^5.4 (taxonomy, slugs, user meta; configure vormia.user_model if needed)
• livewire/livewire ^4.0 (required by this package’s composer.json; Volt storefront is optional in the host app)
• PayPal developer account for sandbox/live keys

Installation

1. Require packages

composer require vormiaphp/vormia
composer require a2-atu/a2commerce

Follow Vormia’s installation docs for auth, migrations, and User model traits.

2. Run the installer (housekeeping)

php artisan a2commerce:install

This does not copy models/services into app/. It:

• Appends any missing A2-related .env / .env.example keys (unless --skip-env)
• Optionally runs php artisan migrate when you confirm at the prompt

Options

• --skip-env — do not append A2 keys via the installer’s env helper (you can still edit .env yourself)

3. Environment

Set PayPal and commerce variables (see also php artisan a2commerce:help):

A2_PAYPAL_MODE=sandbox
A2_PAYPAL_CLIENT_ID=
A2_PAYPAL_SECRET=
A2_PAYPAL_WEBHOOK_ID=
A2_ORDER_PREFIX=SP-OD
A2_TAX_RATE=0
A2_SHIPPING_FEE=0
A2_CURRENCY=USD
A2_CURRENCY_SYMBOL=$
A2_CURRENCY_CONVERSION_RATE=130
ADMIN_EMAIL=orders@example.com

4. Migrate

php artisan migrate

5. Host app wiring

• Define storefront routes (cart, checkout, PayPal UI) and point actions at A2\A2Commerce\Http\Controllers\A2\Commerce\PaymentController where appropriate (initPayPal, confirmPayPal, success, failed, etc.).
• Resolve services with their package FQCNs, e.g.
  app(\A2\A2Commerce\Services\A2\Commerce\CartService::class)
• Dispatch package events, e.g.
  A2\A2Commerce\Events\A2\Commerce\CartUpdated
  (do not rely on old App\Events\A2\Commerce\... copies after migrating off legacy installs.)

Optional: publish config

php artisan vendor:publish --tag=a2commerce-config

Usage (concepts)

Services (package)

Events (package)

Examples: CartUpdated, OrderCreated, PaymentCompleted, PaymentFailed, wishlist/comparison events. Listeners run from A2CommerceEventServiceProvider.

PayPal

1. Create order (host checkout + OrderService).
2. Client uses PayPal JS; server confirms via package services.
3. Webhook hits /api/a2/payment/paypal/webhook for reconciliation.

Artisan commands

Development (this repo)

composer install
vendor/bin/phpunit

Tests use Orchestra Testbench and register Vormia + A2Commerce providers (see tests/TestCase.php).

Documentation

Troubleshooting

Links

• Laravel application structure
• Laravel Mail (mailable Content / textString)
• Vormia
• Livewire

Thank you for using A2Commerce.