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 docs/packageflow-md/0-a_2_commerce_implementation_guide.md. For assistants and architecture entry points, see docs/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)

Class	Role
`A2\A2Commerce\Services\A2\Commerce\CartService`	Cart session, guest + auth
`A2\A2Commerce\Services\A2\Commerce\OrderService`	Orders from cart
`A2\A2Commerce\Services\A2\Commerce\PaymentService` / `PayPalPaymentService`	Payments
`A2\A2Commerce\Services\A2\Commerce\WishlistService`	Wishlist
`A2\A2Commerce\Services\A2\Commerce\ComparisonService`	Comparison

Events (package)

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

PayPal

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

Artisan commands

Command	Purpose
`php artisan a2commerce:install`	Append missing A2 env keys; optional migrate; reminds about publish
`php artisan a2commerce:update`	Append missing A2 env keys (unless `--skip-env`); cache clear
`php artisan a2commerce:uninstall`	Optional env strip; optional DB teardown (MySQL/MariaDB: drops `a2_ec_` and prunes package rows from `migrations` when you confirm; other drivers: drop tables manually). Does not* remove `vendor`
`php artisan a2commerce:help`	Env keys, webhook URL, command summary

Development (this repo)

composer install
vendor/bin/phpunit

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

Documentation

Long-form guides live under docs/ (single copy; there is no duplicate packageflow-md/ at the repository root).

Doc	Content
docs/guide.md	AI / contributor entry: package boundaries, boot path, truth sources
docs/packageflow-md/0-a_2_commerce_implementation_guide.md	Host app integration, routes, Volt examples
docs/packageflow-md/1-a_2_commerce_schema.md	Tables and relationships
docs/packageflow-md/2-a_2_event_flow.md	Event flows
docs/packageflow-md/3-a_2_payment_guide.md	Payment pipeline and webhooks
docs/packageflow-md/4-a_2_commerce_fixes_plan.md	Planning / history notes
docs/packageflow-md/5-a_2_commerce_admin_order_review_shipping.md, docs/packageflow-md/6-a_2_commerce_admin_order_review_shipping-guide-2.md	Admin order / shipping notes

Troubleshooting

Issue	What to check
Webhook not hit	PayPal dashboard URL must be `{APP_URL}/api/a2/payment/paypal/webhook`; route is on `api` middleware
Wrong user model on relations	`config('vormia.user_model')` and `config('auth.providers.users.model')`
Events not firing	Dispatch `A2\A2Commerce\Events\...` classes; ensure `A2CommerceServiceProvider` is registered
“Class not found” for services	Use `A2\A2Commerce\Services\A2\Commerce\...` — not `App\Services\A2\...`

a2-atu / a2commerce

Maintainers

Package info

Statistics

Security