Orders Laravel Package

Getting Started

Install and confirm versions first. Before anything else, read the package's composer.json and confirm the Laravel/PHP constraints match what you actually run. This is a 0.0.x package from October 2022 — it was built against an older Laravel and a specific Livewire major version, and the TALL component will break silently or loudly depending on which Livewire version you have (wire:model semantics changed between Livewire 2 and 3). Pin exactly, don't use ^0.0.3:

composer require lariele/orders:0.0.3
php artisan vendor:publish --provider="Lariele\Orders\OrdersServiceProvider"
php artisan migrate

Where to look first, in order:

1. src/ — the models and the Livewire component class. This is the actual API; the changelog ("Order detail preparing") tells you nothing.
2. config/orders.php (after publishing) — table names, status enums/lists, currency and item configuration. This is where the package's opinions live.
3. database/migrations/ — what it actually persists. Confirm whether it owns an orders/order_items table pair or expects to attach to yours.
4. resources/views/ — the Livewire blade views. Copy them out and own them; do not render package views directly in production.

First real use case: a back-office order detail screen. Don't wire this into checkout or payment flows. Register the Livewire component on an admin route behind auth, point it at one seeded order, and confirm it renders items, totals, and status correctly against values you computed by hand. That single screen tells you whether the package's money handling matches yours — the most important thing to learn about it.

Implementation Patterns

Adapter boundary, non-negotiable. Wrap the package in one class you own, and let nothing else in the app touch Lariele\Orders\* types:

namespace App\Orders;

use Lariele\Orders\Models\Order as PackageOrder;

class OrderDetailAdapter
{
    public function __construct(private PackageOrder $order) {}

    public function toArray(): array
    {
        return [
            'reference' => $this->order->reference ?? $this->order->id,
            'status'    => $this->order->status,
            'items'     => $this->order->items->map(fn ($i) => [
                'sku'      => $i->sku,
                'qty'      => (int) $i->quantity,
                'subtotal' => (int) round($i->price * $i->quantity * 100),
            ])->all(),
            'total'     => (int) round($this->order->total * 100),
        ];
    }
}

Return integer minor units from the adapter. Whatever the package does internally with floats or decimals stays inside the package.

Status transitions belong in your domain. The package has a "flexible status" field; do not let Blade templates or Livewire actions set it directly. Route transitions through your own enum + a small service, then write the value through. If you later drop the package, the state machine stays.

Use the Livewire component as a reference implementation, not as your UI. Read the component to learn the intended data shape and the queries it issues, then rebuild the view yourself against the adapter. This gets you the package's logic without inheriting its markup, its Livewire version assumptions, or its asset requirements.

Feature-flag the integration. Ship the admin detail screen behind config('features.orders_package') and keep the existing implementation running in parallel for one release cycle. Diff the outputs on real orders before flipping the flag permanently.

Seed a golden-file test suite. Serialize adapter output for 10–15 representative orders (single item, many items, zero items, discounted, refunded, null totals) and assert against committed fixtures. This is the only reliable way to catch silent numerical drift on a package upgrade.

Gotchas and Tips

Exact-pin and lock. ^0.0.3 permits 0.0.4, which SemVer explicitly does not promise is compatible. Commit composer.lock, and disable Dependabot/Renovate for this package until it reaches 1.0. Treat every version bump as a production change with a diff review.

Assume the package owns rounding until proven otherwise. Order-detail packages typically carry opinions about currency formatting, tax representation, and line-item math. Grep the source for round, number_format, bcmath, and Money before you trust a single total. If it owns rounding and your app does too, you have two sources of truth and a reconciliation bug waiting.

Watch for N+1 in the Livewire component. Check with DB::listen or Telescope while rendering an order with 20 line items. If it lazy-loads items or per-item relations, eager-load from the adapter: PackageOrder::with('items.product')->findOrFail($id).

Provider registration can collide. If the package binds anything order-related into the container, it may silently override an existing binding or be overridden itself — producing confusing resolution behavior that looks like an unrelated bug. Read the service provider's register() and boot() fully before merging, and check php artisan about / container bindings afterward.

Config keys are not stable at 0.0.x. After publishing config/orders.php, copy the values you care about into your own config namespace and read those. Then a package update changing a config key doesn't move behavior under your feet.

Migration conflict risk. Run php artisan migrate --pretend first. If the package ships an orders table and you already have one, you need to either rename its tables in config before migrating or drop the package's migrations entirely and map its models onto your schema via protected $table.

Extension points, ranked by safety: config values > model subclassing > publishing and editing views > editing the package in vendor/ (never). If the package's model is final or its properties are protected without setters, your escape hatch is the adapter, not inheritance.

Debugging checklist when the component renders blank or throws: (1) Livewire major version mismatch — most likely cause; (2) views not published; (3) @livewireStyles/@livewireScripts missing from the layout; (4) auth middleware on the route blocking the component's data query; (5) a findOrFail on an order the seeded user doesn't own.

Maintenance reality. The changelog is intent, not change description, so you cannot trust release notes — you must read the diff. Assign a named owner for the adapter who understands both the package internals and your money invariants. Keep the adapter thin enough that replacing the package with 200 lines of your own code is a contained afternoon, because at 0.0.3 with no support channel and no 1.0 timeline, that is a realistic outcome rather than a contingency.