DEV Community: Aimeos

How to implement a multi-vendor e-commerce marketplace using Laravel

Aimeos — Thu, 25 Jun 2026 11:09:19 +0000

A marketplace is a multi-tenant system that happens to sell things. That sentence is the whole implementation problem in one line. The seller dashboard looks like the hard part during planning, but the real work shows up around week three, when every query in the system suddenly has to answer a new question. Whose data is this? Which vendor owns this product, this order line, this stock level, this price? The storefront was never the issue. The issue is that a marketplace is multi-tenant from the first table, and most shops are not.

So the first decision you make is also the one that costs the most if you get it wrong: do you build the tenancy yourself, or start from a backend that already has it. Retrofitting isolation onto a single-tenant shop is not a feature you add — it's a rewrite you discover. You thread a vendor_id through models, then through queries, then through the cart, then through the admin, and every place you forget becomes a data leak where one seller sees another seller's orders. This guide takes the other path: build on Aimeos, a Laravel ecommerce package that's multi-tenant from the data model up, and spend your time on the marketplace instead of the plumbing.

Decide where tenancy lives

Before any code, pick the foundation honestly, because it determines how much of the next month you spend on isolation you'll never show a user.

Approach	Vendor isolation	Self-service onboarding	Scales to thousands of vendors
Build it yourself	you thread it through every query	you build it	you re-architect for it later
Single-tenant shop + add-on	bolted onto a single-tenant base	extension-dependent	medium
Aimeos	built into the data model, scoped per site	one env flag	designed for it, 1 to more than 1 billion items

Build it yourself looks cheapest on a whiteboard and turns out to be the most expensive. Tenancy is a cross-cutting concern: it touches every model, every join, every report and every API endpoint, and the cost isn't the scoping code you write — it's the one clause you forget. A single missing filter in a join is one vendor reading another's orders, and you find it in production, not review. It also never stays finished. Every feature you add afterwards has to re-earn its isolation, so you end up maintaining a multi-tenancy framework as an unpaid side project to the marketplace you actually wanted to build.

Single-tenant shop + add-on moves the problem rather than solving it. The base assumes one merchant, so the extension grafts vendor columns and filters onto a schema that was never designed for them. Isolation then lives in the add-on's discipline instead of the data layer — it holds where the extension remembered to apply it and leaks at the edges the base shop reaches directly: admin tools, exports, and third-party plugins that have never heard of vendors. On top of that you inherit the add-on's release cycle and price, and you're betting it keeps pace with the platform it's bolted to.

The rest of this guide assumes the third row, where isolation is a property of the data model rather than something layered on top. Each step is a flag or a small amount of config, not a sprint.

Stand up the backend

You need PHP 8.2+ and a database (MySQL, MariaDB, PostgreSQL or SQL Server). The distribution wires the storefront, the admin, the APIs and a seeded catalog in one command.

composer create-project aimeos/aimeos myshop

Answer the prompts for database, mail and the admin account, then look around:

cd myshop
php artisan serve

The storefront is at http://127.0.0.1:8000, the admin at http://127.0.0.1:8000/admin. At this point you have a working single shop. The next two steps turn it into a marketplace.

Enable multi-vendor mode

The multi-vendor machinery ships in the box. You switch it on with one line in .env:

SHOP_MULTISHOP=true

That gives every vendor a scoped storefront and a scoped backend at their own site — Aimeos's word for a tenant. You can see what the flag did in the routing: every route gains a {site} segment, so the storefront, the JSON:API, the admin panels and the seller's own backend all scope to the vendor in the URL.

'admin'    => ['prefix' => 'admin/{site}/jqadm',   'middleware' => ['web', 'auth', 'verified']],
'graphql'  => ['prefix' => 'admin/{site}/graphql', 'middleware' => ['web', 'auth', 'verified']],
'jsonapi'  => ['prefix' => '{site}/jsonapi',       'middleware' => ['web', 'api']],
'default'  => ['prefix' => '{site}/shop',          'middleware' => ['web']],
'supplier' => ['prefix' => '{site}/s',             'middleware' => ['web']],

The {site} placeholder isn't there for pretty URLs. It's the seam that keeps one vendor's administration from reaching into another's, all the way down to the API.

Let vendors onboard themselves

Creating each seller account by hand doesn't scale past a demo. Turn on self-registration:

SHOP_REGISTRATION=true

A newly registered seller gets administrator rights over their own site and nothing else — their catalog, their orders, their customers, their settings, none of anyone else's. If that's more power than you want to hand a fresh signup, drop the default permission level:

SHOP_PERMISSION=editor

And if neither "admin" nor "editor" maps to the access you have in mind, the permission sets are themselves configuration. Publish your own version of the admin resource config and decide exactly which panels and actions each role can touch. The platform operator keeps the root; vendors get precisely the slice you grant them.

Understand the isolation you just got

It's worth knowing why the two flags above are enough, so you trust the result instead of double-checking it forever. Aimeos organizes everything around the site. Every record the system stores — products, prices, orders, stock — carries a site id, and the data layer filters on it automatically. You never write the where siteid = ? clause; the manager that loads the data already added it. That single design decision is what turns "build a marketplace" from a tenancy project back into a normal shop project.

Sites form a tree rather than a flat list, so a parent can hold shared catalog, categories or configuration that child vendors inherit, while each vendor still owns and overrides their own. A platform operator runs the root; vendors live underneath it with their data sealed off from each other by default.

Give each vendor a catalog and a storefront

Each seller logs into a backend that looks like a complete shop because, scoped to their site, it is one. They manage their own products with the full Aimeos catalog model behind them — variants, bundles, vouchers, virtual and downloadable goods, configurable and custom products, and subscriptions with recurring payments. A marketplace rarely sells one shape of thing; the moment one vendor wants tiered B2B pricing while another sells monthly boxes and a third sells license keys, a thin product table becomes the bottleneck. Aimeos models all of it without schema surgery, so you don't have to say no to a seller's business model.

On the storefront side, each vendor has a public supplier page (the /s route from Step 2) — a branded presence inside the marketplace with their catalog, profile and listings. Buyers shop across vendors; the basket and checkout are shared; the data behind each line stays attributed to the vendor that owns it.

Handle the money

This is the step teams put off and regret. The marketplace-specific concerns — routing the lines of a mixed-vendor order to the right sellers, commissions, and seller payouts — live in a dedicated marketplace extension that builds on the multi-vendor core. The core gives you isolation and per-vendor administration for free; the extension adds the commercial layer of running a platform that takes a cut.

Settle the money at the gateway rather than reconciling it by hand afterward. Aimeos ships payment extensions built for marketplaces — Stripe among them — that split each transaction the moment it's captured, sending the platform its commission and forwarding the remainder to the seller who fulfilled the line. Payouts stop being a monthly spreadsheet exercise and become a property of checkout: the buyer pays once, and the money lands where it's owed, already divided. The same model covers the awkward cases a marketplace inherits — refunds that have to claw back the right share, and orders spanning several vendors that need several payees from a single basket.

Plan for scale before you need it

Marketplaces don't fail at launch. They fail when they succeed — when a few dozen vendors become a few thousand, each with thousands of SKUs, and the catalog that felt instant at 5,000 products crawls at five million. Scale is the requirement that's invisible on day one and existential by month eighteen.

You don't implement anything extra here; you inherit it. Aimeos runs the same architecture from a single seller up past a billion items, with render times down to around 20ms and response times near 100ms on a properly built catalog. The performance work a hand-rolled marketplace postpones until it's an emergency is the work this backend already did, so growth stays a business problem instead of becoming a database firefight.

Go headless where it pays

Vendors increasingly want their own tooling — a mobile app to manage listings, a custom analytics view, an ERP that pushes inventory. Aimeos is API-first underneath the bundled storefront: a JSON:API following jsonapi.org for the buyer side and a GraphQL API for administration, both already scoped per site. Drive the whole marketplace headless, give vendors programmatic access to their own data, or keep the included storefront and only go headless where it pays. None of those are a rebuild — they're the same backend addressed differently.

Verify it

The claim worth testing is the boring one: that the isolation is real and you didn't have to write it. With SHOP_MULTISHOP=true and SHOP_REGISTRATION=true set, create a couple of vendor accounts, sign in as each, and confirm the obvious thing from the inside — neither one can see the other's catalog or orders, and nobody wrote a scoping clause to make that true.

The live frontend demo and admin demo are up if you want a look first, the docs cover the multi-vendor setup end to end, and the marketplace extension is where the commission and payout layer lives.

Implementing a marketplace is mostly about not implementing the parts that should already exist. Start from a backend that's multi-tenant by design, and the thing you ship is the marketplace — not the plumbing underneath it.

PagibleAI: A CMS for your Laravel application

Aimeos — Mon, 22 Jun 2026 12:15:09 +0000

Add content management to a Laravel app you already run. Pagible is a Composer package that brings structured content, versioning, GraphQL and JSON:API, an AI editor, and an MCP server — without taking over your app.

Every Laravel project hits the same question eventually. The client wants to edit the content themselves, and you have to decide who owns the application.

None of the usual answers are clean.

Run WordPress in headless mode and you take on a second runtime, a second auth system, and a REST API you didn't design. Adopt a hosted platform like Contentful and you pay per record while your content lives on someone else's servers. Build a bespoke admin panel and you spend the next two months rebuilding a tree editor, a media library, and a draft/publish flow instead of shipping the product.

Approach	What you take on
Headless WordPress	A second runtime, a second auth system, a REST API you didn't design
Hosted platform (Contentful)	Per-record pricing, your content on someone else's servers
Bespoke admin panel	Months rebuilding a tree editor, media library, and publish flow
PagibleAI	One Composer package; your app stays yours

PagibleAI starts from a different premise: add content management to a Laravel app you already run. You composer require it, and your app stays your app. The CMS moves in as a set of packages, brings its own models, migrations, admin panel, and APIs, and stays out of the way the rest of the time.

Here's what stands out from a developer's seat.

The install is a normal Composer package

There's no service to host and nothing external to wire up. If you have a Laravel 11, 12, or 13 app on PHP 8.2+, you add the package and run the migrations. That's the whole install:

composer require aimeos/pagible
php artisan cms:install
php artisan migrate

Then grant yourself editing rights:

php artisan cms:user -e editor@example.com

The admin panel is served from your own app at /cmsadmin. It's a Vue 3 and Vuetify single-page app talking to a GraphQL endpoint. No external dashboard, no webhook round-trips, no second deployment to keep in sync.

Underneath, it's a monorepo split into focused packages: core models, admin, AI, GraphQL, JSON:API, search, MCP, backup, import, and theming. They share the Aimeos\Cms\ namespace. You install one meta-package and get all of it, but each concern stays isolated, so the surface you have to reason about stays small.

What it's built on

There's not much exotic here. Each capability leans on a package the Laravel community already knows, so most of the stack is familiar before you read a line of Pagible's own code.

Package	Role
`laravel/framework`	Laravel 11 / 12 / 13
`nuwave/lighthouse`	GraphQL admin API
`laravel-json-api/laravel`	JSON:API content delivery
`laravel/scout`	Full-text search engine
`laravel/mcp`	MCP server
`laravel/reverb`	Real-time broadcasting (optional)
`laravel/cashier`	Payments and paywalls — Stripe, Paddle, Mollie (optional)
`aimeos/prisma`	Broad LLM provider integration
`aimeos/laravel-nestedset`	Optimized nested-set page tree
`intervention/image`	Image processing and previews
`league/commonmark`	Markdown rendering
`ezyang/htmlpurifier`, `enshrined/svg-sanitize`	Content sanitization

The admin panel is its own front end on top: Vue 3, Vuetify, and Vite, built into a bundle that ships with the package.

Content is structured, not a wall of HTML

This is what sets Pagible apart from the WordPress lineage. A page isn't one big rich-text field. It's a node in a tree that holds an ordered list of typed content elements.

Three models carry the weight:

Page — a node in a nested-set tree, with drag-and-drop reordering, UUIDs, and soft deletes.
Element — a content block with a type and a data payload. Pages reference their elements in order, and the same element can be shared across many pages.
File — media, with AI-generated descriptions and automatically sized previews.

cms_pages  (nested-set tree)
└─ Page ─┬─ ordered elements ── cms_elements   typed, reusable blocks
         ├─ attached files   ── cms_files      media + AI descriptions
         └─ every change     ── cms_versions   immutable snapshots

A content element is a small, typed structure:

[
    'id'    => 'ByC2ze',
    'type'  => 'text',
    'group' => 'main',
    'data'  => ['text' => '## A heading\n\nSome **markdown** body copy.'],
]

Each type maps to a Blade partial in the theme. The entire renderer for a text element in e.g. theme/views/text.blade.php is one line:

@markdown($data->text ?? '')

You get a generous set of ~30 content element types out of the box including:

Type	Renders
`text`	Markdown body copy
`hero`	Full-width banner with background media
`cards`	Grid of linked cards
`image-text`	Image alongside text
`pricing`	Pricing tables
`slideshow`	Image carousel
`code`	Syntax-highlighted snippets
`questions`	FAQ accordion

Adding your own type means defining its data shape and writing the partial that renders it. You keep full control of the markup, and you can override any view or drop in your own components.

One detail matters for security. The mapping from a type to its handler comes from a trusted schema keyed by the type name, never from the stored element data. A content author can't smuggle a different handler into a record's payload, which closes a whole class of injection problems before it starts.

The payoff is the one Contentful built a business on. Your front end consumes predictable, typed data instead of parsing arbitrary HTML. The same content can render as a web page, feed a mobile app, or drive a sitemap, with no one copy-pasting markup.

Two APIs, pointed in opposite directions

Pagible is API-first in a literal sense. The admin panel is just one client of the API, not a privileged path into the database.

Editing runs over GraphQL, built on Lighthouse. It's the read-write surface the admin uses, and the same one your own tooling, scripts, or integrations can talk to.

Delivery runs over a read-only JSON:API that follows the spec, tuned for the public side. The split is deliberate. The write API can afford to be expressive; the read API is built to serve content fast and cache hard. Rendered pages are cached per-page with a configurable TTL, a day by default, so the common case never touches the editing machinery.

Prefer to render server-side? The theme package ships Blade templates and small directives like @markdown and @localDate, and all of it is yours to override.

Versioning an editorial team can trust

Every change to a page, element, or file becomes an immutable snapshot in cms_versions. Editors see the latest draft. The public sees the most recently published version. Those are two different things, on purpose.

That model gives you the workflow features for free:

Save a draft without touching the live site.
Schedule a version to go live later. cms:publish promotes anything whose publish_at has passed, on a schedule.
Revert to any earlier snapshot when an edit goes wrong.
Keep a bounded history (ten versions per item by default) as an audit trail.

For teams, there's an unsaved-changes guard, concurrent-edit protection, and a Git-like three-way merge when two people touch the same content. A half-finished draft is never one stray click from production.

AI is wired in per task, not bolted on as a chatbot

The "AI" in PagibleAI isn't one assistant sitting in a corner. It's a set of content operations, each routed to whichever provider does that job best, configured by environment variable.

The defaults look like this:

Task	Provider
Write and refine copy, describe media	Gemini
Generate and edit images (inpaint, repaint)	Gemini
Translate	DeepL
Erase, isolate background, uncrop, upscale	Clipdrop
Transcribe audio	OpenAI Whisper

Each task reads its own CMS_AI_{TASK} / _MODEL / _API_KEY trio. You configure only the providers you use, and you can point any task at a different model or provider without touching code. There are batch commands too. cms:description, for example, walks through pages and media that lack descriptions and writes SEO meta text and alt text for them.

Translation is the standout. Content can be translated into more than 35 languages while keeping its structured shape intact, so a translated page is still a real page, not a flattened copy. The whole AI layer is there when you want it and out of the way when you don't — it's truly optional.

The MCP server is the genuinely new part

This is where Pagible reads the room. The same operations the admin panel performs are exposed as Model Context Protocol tools — 33 of them, covering pages, elements, files, image editing, translation, and search.

The result: an assistant like Claude can run the CMS the way an editor would. Not by scraping a UI or guessing at an undocumented API, but through typed tools with real authorization behind them.

"Draft a pricing page from these bullet points, generate a hero image, translate it into German, and schedule it for Monday" stops being a feature request. It becomes a sequence of tool calls an agent makes against your content, with the same permission checks and versioning a human edit goes through.

The CMS turns into something an agent can operate, not just a UI a human clicks through.

It works because the architecture was structured-first from the start. When content is typed and the operations are explicit, an agent has something solid to act on. That's the upside of not storing everything as a wall of HTML.

Scaling, and the boring parts that matter

The same install runs on a single SQLite file for a brochure site and on a database cluster for millions of pages. It's Octane-friendly and built for cloud-native deployment.

Search reflects that range. A custom Laravel Scout engine speaks the native dialect of whatever database you're on: FTS5 on SQLite, MATCH … AGAINST on MySQL, tsvector on PostgreSQL, CONTAINSTABLE on SQL Server. No separate search cluster for something the database already does.

Multi-tenancy is single-database by design. Every model is scoped by a tenant_id through a global Eloquent scope, resolved by the Laravel tenancy package you probably already use. Multi-domain routing is a config flag. Real-time collaboration is opt-in over Laravel Reverb, broadcasting compact, metadata-only events so two editors don't clobber each other.

The security posture is the kind you'd rather inherit than assemble: user content sanitized through HTMLPurifier, CSP headers enforced, hCaptcha on forms, URL validation on submitted links, and rate limiting across the API.

Migrating in? There's a WordPress importer that moves a site over with an Artisan command, plus per-tenant backup and restore with integrity checks.

Want to charge for content? A separate aimeos/pagible-cashier package wires Pagible into Laravel Cashier, so you can put pages behind a paywall or sell course access through Stripe, Paddle, or Mollie. Its installer prompts for a provider, writes the credentials, and adds the Billable trait to your user model. Like the rest, it's opt-in — install it only if you need it.

Who it's for, and the honest caveats

Pagible fits when you have a Laravel app and want the people who own the content to manage it without you handing over the codebase. The headless APIs, structured content, and MCP tooling make it a solid base for anything where content feeds more than one front end.

Two things to weigh. It's young and moving fast, and the AI features need third-party API keys, which means accounts and may need a budget if you want the full set.

It's MIT licensed, so you can use it in commercial work with no per-site fees and no lock-in.

None of the caveats change the central pitch, which is the thing I keep coming back to: it installs into your app instead of asking your app to live inside it. If you've ever lost a weekend to a headless WordPress proxy, that alone is worth the composer require.

The code and docs are at pagible.com and on GitHub. If you try it, I'd like to hear which part of the workflow surprised you.

A working Laravel shop in five minutes with Aimeos

Aimeos — Thu, 18 Jun 2026 13:20:40 +0000

Adding a shop to a Laravel app usually turns into a quarter of work. You pick a cart library, bolt on a payment gateway, build an admin panel nobody asked to build, then discover your product model can't handle variants, bundles or tier prices without a rewrite. The ecommerce part eats the schedule; the Laravel part was never the problem.

Aimeos takes the opposite route. It's a Laravel package that brings the storefront, the admin backend, a JSON:API for the frontend, a GraphQL API for administration, and a product model built for variants, bundles, subscriptions and block pricing. You install it the way you install anything else in Laravel, and you have a running shop before your coffee is cold.

Here's the part people don't believe until they run it: the full setup is about five minutes. Two paths, depending on whether you're starting fresh or extending an app you already have.

Path one: a standalone shop

If you don't have an app yet, the distribution wires everything up for you. You need PHP 8.2+ and a database (MySQL, MariaDB, PostgreSQL or SQL Server).

composer create-project aimeos/aimeos myshop

During install it asks for your database credentials, your mail settings, and the email and password for the admin account. It runs the schema setup and seeds demo data as part of the same step, so when it finishes you have a populated catalog, not an empty shell.

Start it with the built-in server to look around:

cd myshop
php artisan serve

The storefront is at http://127.0.0.1:8000 and the admin backend at http://127.0.0.1:8000/admin. Log in with the account you just created. Catalog, baskets, checkout, orders and the dashboard are already there.

For hosting, point your vhost document root at myshop/public/ and set APP_URL in .env to your domain. That's the only deployment-specific change.

Path two: into an existing Laravel app

Already have an app and want a shop inside it? Require the package:

composer require aimeos/aimeos-laravel:~2025.10

Publish the config and assets, run the migration, and let Aimeos set up its tables:

php artisan vendor:publish --tag=config --tag=public
php artisan migrate
php artisan aimeos:setup

Append --option=setup/default/demo:1 to aimeos:setup if you want demo data to click through; leave it off in production.

Create a superuser for the backend:

php artisan aimeos:account --super you@example.com

It prompts for a password. The shop now lives under your app's routes, sharing the same Laravel session, auth and config. The frontend renders at / and the admin at /admin, alongside whatever your app already serves.

What you actually get

The install is short because the package isn't a starting point you finish writing — it's the finished thing, built to be customized rather than completed. Out of the box:

A storefront with catalog filters, search, basket, multi-step checkout and customer accounts.
A full admin backend with a dashboard for products, orders, customers, pricing and marketing.
A JSON:API following jsonapi.org for the frontend, so you can drop the bundled views and drive it from React, Vue or a native app.
A GraphQL API for administration if you'd rather manage data programmatically.
A product model that handles variants, bundles, vouchers, virtual and configurable products, plus subscriptions with recurring payments and block/tier pricing — without schema surgery.
Over 100 payment gateway integrations through Omnipay.
Multi-language routing, multi-vendor and multi-warehouse support, translated into 30+ languages.

It's designed to stay fast as the catalog grows, from a handful of products into the millions, which is the part that usually decides whether a shop survives its second year.

Customizing without forking

Every layer is replaceable through Laravel's own conventions. Configuration lives in config/shop.php. Templates are standard Blade views you override by copying them into resources/views/vendor/shop/. Business logic sits in decorators you register in config, so you change behavior by wrapping it, not by editing vendor code that the next update would overwrite. Turn on multi-language routing, multi-vendor mode or self-registration for sellers with a single .env flag each:

SHOP_MULTILOCALE=true
SHOP_MULTISHOP=true
SHOP_REGISTRATION=true

Try it

The honest test is to run it yourself rather than take the word count on faith. composer create-project aimeos/aimeos myshop, answer the prompts, php artisan serve, and open the browser. If you want to see the result first, the frontend demo and admin demo are live.

Docs are at aimeos.org/docs/latest/laravel, and if you're building a headless or PWA frontend, the Aimeos headless distribution ships API-only with JWT auth already configured.

Five minutes to a working shop. The rest of the quarter is yours to spend on the parts that make it yours.

Stop juggling AI SDKs in PHP — meet Prisma

Aimeos — Fri, 22 May 2026 12:00:17 +0000

If you've ever integrated an AI provider into a PHP application, you know the drill. You pull in the OpenAI SDK. Then the client wants image generation, so you add StabilityAI — different SDK, different request format, different error handling. Then they want audio transcription — enter Deepgram, yet another integration. Before you know it, you're maintaining three separate API integrations, each with their own quirks, response formats, and retry logic.

Prisma fixes this. One package. One API. 25+ providers. Text, image, audio, and video.

composer require aimeos/prisma

What is Prisma?

Prisma is a light-weight, MIT-licensed PHP package that provides a unified interface for working with AI providers across four media domains. No framework coupling. Just Guzzle under the hood, PHP 8.2+, and a clean fluent API.

Here's the core idea — every provider works through the same interface:

use Aimeos\Prisma\Prisma;

// Generate text with OpenAI
$text = Prisma::text()
    ->using('openai', ['api_key' => '...'])
    ->write('Summarize the benefits of renewable energy')
    ->text();

// Generate an image with StabilityAI
$image = Prisma::image()
    ->using('stabilityai', ['api_key' => '...'])
    ->imagine('a mountain landscape at sunset')
    ->binary();

// Transcribe audio with Deepgram
$transcript = Prisma::audio()
    ->using('deepgram', ['api_key' => '...'])
    ->transcribe($audioFile)
    ->text();

// Describe a video with Gemini
$description = Prisma::video()
    ->using('gemini', ['api_key' => '...'])
    ->describe($videoFile)
    ->text();

Same pattern everywhere: Prisma::{domain}()->using(provider, config)->{method}(). Switch providers by changing a single string. Your application code stays the same.

Why this matters in practice

Imagine you're building a product listing tool. You need to:

Generate product descriptions from images
Extract structured data (name, price, category) from the descriptions
Generate marketing images for missing

Without Prisma, that's three different SDK integrations. With Prisma:

use Aimeos\Prisma\Prisma;
use Aimeos\Prisma\Schema\Schema;

// 1. Describe a product image
$description = Prisma::image()
    ->using('openai', ['api_key' => '...'])
    ->describe($productPhoto)
    ->text();

// 2. Extract structured data
$schema = Schema::for('product', [
    'name' => Schema::string()->required(),
    'price' => Schema::number(),
    'category' => Schema::string()->enum(['electronics', 'clothing', 'food', 'other']),
]);

$product = Prisma::text()
    ->using('gemini', ['api_key' => '...'])
    ->structure("Extract product info from: {$description}", $schema)
    ->structured();
// ['name' => 'Wireless Headphones', 'price' => 79.99, 'category' => 'electronics']

// 3. Generate a product image
$image = Prisma::image()
    ->using('stabilityai', ['api_key' => '...'])
    ->imagine("Professional illustration of {$product['name']}")
    ->binary();

Three providers, three media types, one consistent API. And if tomorrow you want to swap Gemini for Anthropic, you change one line.

You can also check provider capabilities at runtime:

$provider = Prisma::image()->using('clipdrop', ['api_key' => '...']);

if ($provider->has('upscale')) {
    $image = $provider->upscale($lowResImage)->binary();
}

// Or throw if the capability is missing
$provider->ensure('upscale'); // throws NotImplementedException if not supported

What's new in 0.4

Version 0.4 is a major release that adds text generation, structured output, tool calling, and a lot more. Here's what landed.

Text generation across 14 providers

The write() method brings text generation to Prisma with support for OpenAI, Anthropic, Gemini, Bedrock, Mistral, Groq, Cohere, Deepseek, Alibaba, xAI, Perplexity, OpenRouter, Ollama, and Deepseek. All multimodal — pass images, audio, or documents alongside your prompt:

use Aimeos\Prisma\Base\File;

$response = Prisma::text()
    ->using('anthropic', ['api_key' => '...'])
    ->withSystemPrompt('You are a helpful assistant')
    ->write('Describe this image', [File::from('photo.jpg')]);

echo $response->text();

Structured output

Get typed JSON responses from LLMs using a fluent Schema builder. Prisma uses each provider's native structured output API — no prompt engineering hacks:

use Aimeos\Prisma\Schema\Schema;

$schema = Schema::for('event', [
    'title' => Schema::string()->required(),
    'date' => Schema::string()->format('date')->required(),
    'attendees' => Schema::array()->items(Schema::string()),
    'location' => Schema::object([
        'city' => Schema::string()->required(),
        'country' => Schema::string(),
    ]),
]);

$response = Prisma::text()
    ->using('openai', ['api_key' => '...'])
    ->structure('Parse: Team meetup on June 15 in Berlin with Alice and Bob', $schema);

$event = $response->structured();
// [
//     'title' => 'Team meetup',
//     'date' => '2026-06-15',
//     'attendees' => ['Alice', 'Bob'],
//     'location' => ['city' => 'Berlin', 'country' => 'Germany'],
// ]

The Schema builder supports strings, integers, numbers, booleans, arrays, objects, enums (including PHP BackedEnum), nested objects, required(), nullable(), min()/max(), regex pattern(), and more. You can also pass raw JSON Schema arrays via Schema::fromArray().

Tool calling with auto-execution

This is where things get interesting. Prisma supports full agentic tool calling with an automatic execution loop. You define tools, the model calls them, Prisma executes the handlers and feeds results back — all automatically:

use Aimeos\Prisma\Tools;
use Aimeos\Prisma\Schema\Schema;

$searchTool = Tools::make(
    'search_products',
    'Search the product database',
    Schema::for('search', [
        'query' => Schema::string()->description('Search query')->required(),
        'limit' => Schema::integer()->description('Max results')->min(1)->max(50),
    ]),
    function(array $args): string {
        $results = ProductSearch::query($args['query'], $args['limit'] ?? 10);
        return json_encode($results);
    }
);

$response = Prisma::text()
    ->using('openai', ['api_key' => '...'])
    ->withTools([$searchTool])
    ->withMaxSteps(5)
    ->write('Find me the top 3 wireless headphones under $100');

echo $response->text();
// The model searched, got results, and wrote a summary

You can inspect what happened during the tool loop:

foreach ($response->steps() as $step) {
    echo $step->name();      // 'search_products'
    echo $step->arguments(); // ['query' => 'wireless headphones', 'limit' => 3]
    echo $step->result();    // '[ ... search results ... ]'
}

Tools also support:

Per-tool call limits: Tools::make(...)->max(3) — the tool can only be called 3 times
Custom error handlers: ->failed(fn($e, $args) => 'Fallback message') — catch exceptions gracefully
Concurrent execution: ->concurrent() — tools run in parallel via pcntl_fork
Decorators: wrap tools with logging, caching, or any custom behavior
Tool choice: ->withToolChoice(Provider::REQ) to force tool use

Provider tools

Some providers offer built-in server-side tools like web search and code execution. Prisma normalizes these too:

use Aimeos\Prisma\Tools;

$response = Prisma::text()
    ->using('anthropic', ['api_key' => '...'])
    ->withTools([
        Tools::provider('web_search'),
        Tools::provider('code_execution'),
    ])
    ->write('Search for the latest PHP version and verify it');

Available provider tools include web_search, code_execution, file_search, web_fetch, image_generation, and document_library — each mapped to the providers that support them. You can mix custom and provider tools in the same request.

Framework tool adapters

Already have tools built for Laravel AI or Symfony? Reuse them directly:

// Laravel AI / Prism tools
$tool = Tools::laravel(new MyLaravelTool());

// Symfony #[AsTool] classes
$tool = Tools::symfony(MySymfonyTool::class);

Thinking budgets

Enable extended reasoning for models that support it. Prisma automatically maps token counts to each provider's native format:

$response = Prisma::text()
    ->using('anthropic', ['api_key' => '...'])
    ->withThinkingBudget(5000)
    ->withMaxTokens(4096)
    ->write('Solve this step by step: ...');

// Access the model's reasoning
$thinking = $response->meta()['thinking'] ?? null;

Citations

Normalized citation objects across providers that support them (Anthropic, OpenAI, Gemini, Perplexity, xAI):

foreach ($response->citations() as $citation) {
    $citation->title();  // source title
    $citation->url();    // source URL
    $citation->text();   // output text that cites this source
    $citation->source(); // verbatim quote from the source
}

Rate limits and retry handling

// Automatic retry with exponential backoff
$response = Prisma::text()
    ->using('openai', ['api_key' => '...'])
    ->withClientRetry(3, fn($attempt, $resp) => 100 * pow(2, $attempt))
    ->write('...');

// Inspect rate limit headers
$limit = $response->rateLimit();
$limit->remaining();  // requests left
$limit->retryAfter(); // seconds until reset

Provider coverage

Here's what's supported for text providers in 0.4:

Provider	structure	translate	write	citations	custom tools	provider tools	thinking budget
Alibaba	yes		yes	-	yes	yes	-
Anthropic	yes		yes	yes	yes	yes	yes
Bedrock	yes		yes	-	yes		yes
Cohere	yes		yes	-	yes		-
Deepseek	yes		yes	-	yes		-
DeepL		yes
Gemini	yes		yes	yes	yes	yes	yes
Google		yes
Groq	yes		yes	-	yes		-
Mistral	yes		yes	-	yes	yes	-
Ollama	beta		beta	-	yes		-
OpenAI	yes		yes	yes	yes	yes	yes
Openrouter	yes		yes	-	yes	yes	-
Perplexity	beta		beta	yes	yes		-
xAI	beta		beta	yes	yes	yes	yes

And that's just text. Prisma also covers 9 audio providers (speak, transcribe, demix, denoise, revoice, describe), 14 image providers (imagine, inpaint, upscale, vectorize, background, erase, and more), and video description via Gemini.

Getting started

composer require aimeos/prisma

Minimal example:

<?php

use Aimeos\Prisma\Prisma;

// Text
echo Prisma::text()
    ->using('openai', ['api_key' => getenv('OPENAI_API_KEY')])
    ->write('What makes PHP great?')
    ->text();

// Image
$binary = Prisma::image()
    ->using('openai', ['api_key' => getenv('OPENAI_API_KEY')])
    ->imagine('a PHP elephant wearing sunglasses')
    ->binary();

file_put_contents('elephant.png', $binary);

No service providers, no config files, no framework dependencies. Just require and use.

Prisma is MIT-licensed and open source. Check it out:

Docs: https://php-prisma.org
GitHub: https://github.com/aimeos/prisma

If you've been looking for a unified way to work with AI providers in PHP — especially beyond just text — give it a try. Feedback, issues, and stars are all welcome.

In case you like Prisma, leave a star in the Github repo :-)

Aimeos: Laravel e-commerce 2026.04

Aimeos — Tue, 12 May 2026 10:38:27 +0000

If you're building e-commerce with Laravel, this one's for you.

What's new

We just shipped Aimeos 2026.04 — here's what landed.

Laravel 13 support

The Laravel integration, the stand-alone shop, and the headless distribution all run on Laravel 13 out of the box. Upgrade and go.

Customer CSV import

Products, catalogs, and suppliers already had CSV import. Now customers do too. Full pipeline with address and property support, regex validation, group filtering, and an admin UI upload. The CSV import story is complete.

Product feed extension

New extension for generating Google Merchant and Idealo product feeds. Drop it in, configure which products and details to export, done.

Security hardening

HTML sanitization in the CMS to prevent XSS
Query depth and complexity limits on GraphQL
Tighter permission checks in the admin API

Ready for PHP 9

Minimum raised to PHP 8.1. Every deprecation removed across the core and 30+ extensions. Fully tested on PHP 8.5. PHPStan static analysis added at level 4 with zero errors.

Wait, what's Aimeos?

Aimeos is an open-source e-commerce framework (LGPLv3) that installs into Laravel as a Composer package. No separate shop system — you add e-commerce to your existing app.

It works like Laravel, not against it. Your routes, middleware, auth, queues, Blade views. You stay in Artisan and Eloquent. Aimeos plugs in rather than taking over.

Headless-first. JSON:API and GraphQL APIs ship out of the box. Build your frontend in Vue, React, Livewire, Inertia — or use the included server-rendered HTML components.

Multi-tenant. Run multiple shops from one Laravel install. Separate catalogs, pricing, languages, and currencies per site.

It scales. Same codebase for a single-product shop or a marketplace with millions of items. ElasticSearch and Solr integrations handle high-volume search.

Extensible. 30+ extensions for payments, shipping, CMS, feeds, Redis caching, search engines, and more. Custom extensions follow the same conventions without touching core code.

No SaaS lock-in. Self-hosted. You own your data. No per-transaction fees.

Get started

One command:

composer create-project aimeos/aimeos

If you like Aimeos, give it a star on GitHub :-)