Framework Laravel Package

Getting Started

avored/framework is the domain layer of AvoRed, a Laravel e-commerce platform: models, repository contracts, GraphQL schema, admin scaffolding, and the menu/payment/shipping registries. It is not a storefront you install and run by itself — the runnable app lives in avored/laravel-ecommerce. Decide which one you need before you start:

• You want a working store/admin panel → install the app scaffold and treat framework as a dependency you read but rarely touch.
• You want the e-commerce domain inside your own Laravel app → require framework directly and wire your own admin/storefront around its contracts and models.

Minimal path for the second case:

composer require avored/framework
php artisan vendor:publish --provider="AvoRed\Framework\Providers\AvoRedServiceProvider"
php artisan migrate

The provider name is whatever composer.json lists under extra.laravel.providers — check that first, since it has changed across AvoRed versions. Then publish config and assets separately (--tag=avored-config, --tag=avored-assets or similar) rather than all at once, so you can see what each tag drops into your app.

Where to look first, in this order:

1. src/Database/Models — Product, Category, Property, Attribute, ProductVariation, Order, OrderItem, Cart, Customer, AdminUser. Reading these teaches you the domain faster than any docs.
2. src/Database/Contracts and src/Database/Repository — the repository pattern is the main extension seam for non-UI code.
3. src/GraphQL (schema + resolvers) if you're building headless.
4. src/Events and src/Listeners — order lifecycle hooks.
5. routes/ and src/Http/Controllers — the admin panel's structure.

A first use case that exercises the important parts: a product listing page driven by the repository contract, not the model directly.

use AvoRed\Framework\Database\Contracts\ProductRepositoryInterface;

class ShopController extends Controller
{
    public function __construct(private ProductRepositoryInterface $products) {}

    public function index()
    {
        return view('shop.index', [
            'products' => $this->products->paginate(24),
        ]);
    }
}

Confirm the interface and method names in src/Database/Contracts before committing to them — this package has no API docs, and repository signatures are the thing most likely to have drifted between releases.

Implementation Patterns

Resolve the domain through contracts, not models. Every repository has a contract bound in the package's service provider. Injecting ProductRepositoryInterface, CategoryRepositoryInterface, OrderRepositoryInterface etc. keeps your controllers free of the framework's query details and gives you a one-line swap point later:

// AppServiceProvider::register()
$this->app->bind(
    \AvoRed\Framework\Database\Contracts\ProductRepositoryInterface::class,
    \App\Repositories\ProductRepository::class
);

This is the cleanest way to add tenant scoping, caching, or custom pricing rules without forking anything. Extend the package's repository class rather than reimplementing the contract, so you inherit its eager-loads and filters.

Get the property/attribute/variation model right early. This is the biggest domain decision in the package and is hard to unwind. In AvoRed's model: properties are descriptive key-values on a product (Material, Weight), attributes are the options that generate variants (Size, Color), and variations are the concrete sellable combinations of attribute values with their own SKU/price/stock. Catalogue imports, filters, and the storefront's variant selector all key off this split. If you model Color as a property, you will not be able to sell a red and a blue version of the same product without hacks.

Use the event system for anything that leaves the system. Orders are the integration point for inventory, ERP, email, and analytics. Register listeners in your own EventServiceProvider and never modify the package's listeners:

protected $listen = [
    \AvoRed\Framework\Events\OrderPlacedEvent::class => [
        \App\Listeners\SyncInventory::class,
        \App\Listeners\PushOrderToErp::class,
    ],
];

Check src/Events for the exact class names — the order lifecycle typically has placed/status-changed events, which is where you hook fulfilment workflows. Keep listeners idempotent: retries and duplicate webhooks are normal.

Extend the admin via the menu builder instead of replacing it. The admin panel is assembled from a menu registry, so a custom CRUD screen slots into the existing shell if you register it in a service provider rather than adding your own layout. Look at how the package registers its own catalog/order entries in src/Menu and mirror that. This is also the answer to "where do I put my custom module's nav item" — it disappears if you register it inside a controller.

Register payment and shipping methods through the package registries. Both are pluggable driver collections; you implement the contract and register your driver, and the checkout/admin pick it up. That's the correct integration path for local gateways that AvoRed doesn't ship, and it keeps the checkout code untouched.

Headless: prefer GraphQL over hand-rolled REST. The schema in src/GraphQL already models products, categories, carts, and checkout, so a Nuxt/Next storefront can be built against it with Sanctum tokens for authenticated cart operations. Typical query shape:

query {
  products(first: 12) {
    data { id name slug price }
    paginatorInfo { total currentPage }
  }
}

Watch for N+1 on product properties/attributes — either eager-load in a custom resolver or use the repository behind your own endpoint if you're not already committed to Lighthouse.

Copy vendor migrations before altering schema. You will need extra columns eventually. Publish or copy the migrations into database/migrations, delete the published originals from the package's load path, and keep a diff log against upstream. Editing anything under vendor/ makes the next composer update a manual merge.

Gotchas and Tips

The package is stale. Last release February 2023 at 77 stars means it has not tracked Laravel's release cadence. Before adopting, open composer.json and check the illuminate/* constraints against your target Laravel version. If you're on Laravel 10+ and the constraint doesn't allow it, you're looking at a fork ("avored/framework": "dev-master" plus a compatibility branch) or a different package. Budget for this — it's the single biggest adoption risk.

The source is the documentation. There's no meaningful docs site for the framework package itself, and the README is thin. Plan to read src/ — models for relationships, contracts for behaviour, and routes/ for what the admin actually exposes. This makes onboarding slower than a typical Laravel package but is entirely tractable for a mid-level developer.

Admin assets and config caching. After any upgrade, republish assets with --force, run php artisan view:clear, and check public/vendor/avored. If you register menus, payment methods, or shipping options inside a service provider and run php artisan config:cache, those registrations can silently vanish from the UI — always php artisan optimize:clear after changing registration code and re-test with config cached before deploying.

Guards are separate. The admin panel uses its own guard, not web. Mixing them causes "user is logged in but sees no products" symptoms that look like permissions bugs. When you write middleware, policies, or auth()->user() calls outside the admin, check config/auth.php for the guard you actually mean.

Money and currency. Prices are stored in the store's base currency and formatting is done through the package's helper. Do not number_format() a price in a Blade template — you'll lose the currency symbol and get inconsistent decimal places between cart, order confirmation, and admin. Also verify how your version stores totals (integer minor units vs decimal) before writing reporting queries; this is a common source of off-by-100 bugs.

Slugs are load-bearing. Product and category routes bind by slug. Enforce uniqueness in your import/seed scripts, and be careful with slug regeneration on rename — old URLs will 404 unless you add redirects yourself.

Storage and media. Product images rely on the standard filesystem config. php artisan storage:link is easy to forget in a fresh environment, and the failure mode is broken images rather than an error. Check which disk the package defaults to in its config and override it explicitly.

Debugging checklist when something "isn't there": composer show avored/framework for the actual installed version, php artisan route:list | grep -i avored for what's registered, php artisan vendor:publish (no tag) to see available publish groups, and php artisan optimize:clear before assuming a code bug.

Extension points, ranked by leverage: repository contract bindings → events/listeners → menu builder → payment/shipping registries → published config → published views (avored:: namespace) → forking. Publishing views should be a last resort; every published view is one you now maintain.

Don't fight the opinionation. This is an e-commerce application's core, not a toolkit. Single-store, single-currency, catalogue-and-cart flows are well covered; multi-warehouse inventory, B2B tiered pricing, and marketplace-style multi-vendor are not. If your requirements sit outside the model, use this package as a reference implementation and build your own domain — wrapping it will cost more than replacing it.