Laracom Laravel Package

Getting Started

Laracom is a reference application, not a drop-in Composer package. You do not composer require it into an existing project — you clone the repo and treat it as your starting codebase, then prune/replace what you don't need.

Minimal bootstrap:

git clone https://github.com/jsdecena/laracom.git my-shop
cd my-shop
composer install
cp .env.example .env
php artisan key:generate
# edit .env for DB, MAIL, STRIPE keys
php artisan migrate --seed
php artisan storage:link
npm install && npm run dev   # or the Laravel Mix equivalent in the repo
php artisan serve

Where to look first, in order:

1. routes/web.php and routes/api.php — the whole feature surface (shopfront, customer account, admin, API) is visible here.
2. app/Shop/ — the domain lives here, one folder per bounded context: Products, Categories, Attributes, Cart, Checkout, Orders, Coupons, Customers, Addresses, Shipping, Payments, Roles, Users, plus Core with the base repository/contract machinery.
3. app/Providers/ (the shop service provider) — this is where every repository contract is bound to its implementation. If something is "not instantiable," the answer is almost always here.
4. database/migrations and database/seeds — the schema and the seeded admin/customer/demo data.
5. resources/views/ split into admin/ and front/ — the Blade layer you'll be restyling.

First use case to validate the install: log into /admin with the seeded admin credentials (check the UsersTableSeeder / AdminsTableSeeder — usually [email protected] with a known default password, change it immediately), create a category, create a product with an image and at least one attribute, then walk the storefront: add to cart → apply a coupon → checkout → confirm the order appears under admin orders. If that loop works, your environment is sound.

Implementation Patterns

Repository + Contract per module. Every domain folder follows the same shape: an Eloquent model (often with a presenter for currency/date formatting), a Contracts/*RepositoryInterface, an Eloquent*Repository, exceptions in Exceptions/, and transformers for API output. Controllers type-hint the interface and get the implementation injected. When you add a feature (say, "gift cards"), copy the shape of Coupons verbatim: migration → model → contract → repository → bind in the provider → controller → views/transformer. Consistency here buys you a lot; fighting it costs more than it saves.

Product creation is multi-step, not a single insert. The product repository handles the base row, but categories, attributes (with values), and images are attached separately. In practice your admin controller or a small service should orchestrate: create product → sync categories → attach attribute values to the pivot → store images and persist paths. Don't expect the repository's createProduct() to do all of it.

Cart is recalculated, not incrementally mutated. Prices, coupon discounts, and shipping are computed from the cart's items rather than trusted from the request. Follow that convention: after any cart mutation (quantity change, coupon applied/removed, shipping selection), recompute totals through the cart repository before persisting. This is the single most important pattern to respect—bypassing it produces totals that drift from line items.

Checkout → Order is a state transition, not a CRUD write. The checkout flow creates an order, snapshots line items and addresses onto the order (so later product edits don't rewrite history), then moves status through the order-status/transform classes rather than setting status directly. When you add fulfilment steps, add a status and a transition rather than an ad-hoc update().

Integrate new payment gateways behind an interface. Payments are abstracted under Shop/Payments with a charge contract. Implement the contract for your provider (Stripe is the reference), bind it, and select it via config/env — never call the SDK from the checkout controller.

Admin CRUD convention. Admin controllers are thin: Form Requests in app/Http/Requests for validation, repository calls for persistence, redirect-with-flash for feedback. Keep new admin screens inside this convention so the existing middleware, Blade layouts, and DataTables-ish listing views keep working.

API layer via transformers. The JSON API (JWT-authenticated) exposes models through transformers rather than returning Eloquent models directly. Add fields by editing the transformer, not by ->toArray() in the controller—this keeps shopfront and API output from diverging.

Gotchas and Tips

• The Laravel version is pinned and old. Expect Composer conflicts with modern PHP and any current package. Use the PHP version the repo's composer.json targets (Docker or a matching local runtime), and don't blindly composer update—you'll break framework internals the app relies on.
• "Target [XInterface] is not instantiable" means the contract isn't bound. Check the shop service provider first; it's the cause ~99% of the time.
• Images silently 404 after upload: run php artisan storage:link and verify the filesystems.php disk the repository writes to matches the one the Blade asset() calls read from. Intervention/image resizing is configured per-upload and will fail quietly on missing GD/Imagick.
• Slug collisions. Products/categories use sluggable behavior; seeding or bulk-importing duplicate names produces suffixed slugs you didn't intend. Normalize names before import or supply slugs explicitly.
• Roles/permissions are cached. Spatie's permission cache means new roles won't appear until php artisan permission:cache-reset (or cache:forget). This bites people editing seeders and re-running them.
• Don't trust seeded admin credentials in anything reachable. Rotate the admin password and remove demo users before any deployment.
• N+1 on the storefront listing. Product grids touch categories, images, and attribute values. Eager-load (with([...])) in the repository methods that back listing pages or you'll see the query count explode.
• Coupon math order matters. Percentage vs. fixed, minimum-spend thresholds, and whether shipping is discounted—verify the exact application order in the cart repository before you touch totals logic, and write a test for each combination you support.
• Order snapshots. If you "fix" the order to join back to live product data for pricing, you'll retroactively change historical invoices. Keep the snapshot columns.
• Debugging tools: php artisan route:list to find the actual controller for an admin URL (the route names are not always obvious), and DB::listen/Telescope dropped into a service provider when cart totals look wrong—almost always a missing recalculation rather than a formula bug.
• Extension points worth knowing: the payment contract, the order-status/transform classes, model presenters (formatting/currency), and the repository bindings. Those four cover most real customization without forking core.
• Treat it as a fork, not a dependency. There is no clean upgrade path; audit the code, strip unused modules early (e.g., if you don't need the API or coupons), and keep your own diff discipline so future changes stay reviewable.