README

Venditio is a headless ecommerce package for Laravel. It provides API-only ecommerce primitives while host applications own auth, frontend, and rendering.

Installation

composer require pictastudio/venditio

Install Venditio

php artisan venditio:install

Documentation

Architecture: docs/ARCHITECTURE.md
API reference: docs/API.md
Database schema (DBML): database.dbml

Product Variants Model

Venditio models variants using a parent/child product strategy:

A base product is a row in products with parent_id = null
Each purchasable variant is another row in products with parent_id set to the base product id
Variant axes live in product_variants (for example Color, Size)
Axis values live in product_variant_options (for example Red, M)
Assigned option values for each variant product are stored in product_configuration

This keeps a single product identity while still allowing independent SKU/inventory/pricing per concrete variant.

Configuration

All behavior is configured through config/venditio.php.

Key sections

routes.api: route enable/prefix/name/middleware/pagination and resource wrapping
models: model overrides (all package models are replaceable)
validations: validation contract to implementation bindings
authorize_using_policies: optional policy/gate authorization
price_lists: optional multi-price feature
discounts: discount calculator/bindings/rules configuration
product: product enums, sku generator and product list variant visibility defaults
product_variants: variant naming/copy behavior

User model and auth integration

Authentication is not enforced by default. If your host app uses Sanctum, add HasApiTokens to your user model and point the package user model config to it:

namespace App\Models;

use Laravel\Sanctum\HasApiTokens;
use PictaStudio\Venditio\Models\User as VenditioUser;

class User extends VenditioUser
{
    use HasApiTokens;
}

'models' => [
    // ...
    'user' => App\Models\User::class,
],

Optional policy integration

use App\Models\Product;
use App\Policies\ProductPolicy;
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::policy(Product::class, ProductPolicy::class);
}

Controllers call authorization only when enabled and when a policy/gate definition exists.

Validation customization

Validation rules are resolved from contracts in config('venditio.validations'). Override a resource by rebinding its contract to your implementation.

use App\Validations\AddressValidation;
use PictaStudio\Venditio\Validations\Contracts\AddressValidationRules;

public function boot(): void
{
    $this->app->singleton(AddressValidationRules::class, AddressValidation::class);
}

Identifier generator customization

use PictaStudio\Venditio\Contracts\CartIdentifierGeneratorInterface;
use PictaStudio\Venditio\Contracts\OrderIdentifierGeneratorInterface;

$this->app->singleton(CartIdentifierGeneratorInterface::class, App\Generators\CartIdentifierGenerator::class);
$this->app->singleton(OrderIdentifierGeneratorInterface::class, App\Generators\OrderIdentifierGenerator::class);

Commands

Release stock for abandoned carts

Enabled by default and configurable from:

venditio.commands.release_stock_for_abandoned_carts.enabled
venditio.commands.release_stock_for_abandoned_carts.inactive_for_minutes
venditio.commands.release_stock_for_abandoned_carts.schedule_every_minutes

Publish Bruno collection

php artisan vendor:publish --tag=venditio-bruno

High-level structure

src/
|--- Actions
|--- Contracts
|--- Discounts
|--- Dto
|--- Enums
|--- Http
|--- Models
|--- Pipelines
|--- Pricing
|--- Validations

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

pictastudio / venditio

Maintainers

Details