Archetype Bundle Laravel Package

Getting Started

First, the honest read: this is a Symfony bundle. It will not boot in Laravel — no service provider, no config/archetypes.php, no Composer auto-discovery. composer require sylius/archetype-bundle will either fail resolution against laravel/framework/PHP 8.x or install a package that does nothing. Do not put it in composer.json.

What you actually do on day one:

1. Read the source as a spec, not a dependency. Clone it to a scratch directory (outside vendor/) and read, in this order:
   • DependencyInjection/Configuration.php — the archetype config shape (attributes, properties, options attached to a parent template).
   • Resources/config/services.xml — the service IDs that reveal the domain seams: a builder (constructs an archetype from a parent + overrides), a resolver (product → archetype lookup), and a registry (archetype lookup by name/type).
   • Model/ and Resources/config/doctrine/ — the actual entity relationships, which are the only part you will port.
2. Write a one-page domain note mapping its entities to Eloquent: Archetype → product_archetypes, plus pivot tables for archetype↔attribute, archetype↔property, archetype↔option, and a nullable archetype_id on products.
3. Pick your first use case from a real gap in your app: "when an editor creates a T-shirt, prefill size/color options and fabric attributes from a template, then generate the variant matrix." If you don't have that gap, close the ticket.

Where to look in your own codebase first: whatever currently duplicates attribute or option setup across product creation — admin form defaults, import mappers, and seeders are the three usual offenders. That duplication is the thing the archetype pattern removes.

Only install it if you are maintaining a live Sylius 0.x install and need to read schema/behaviour before migrating off. Even then you read it; you do not add it to a Laravel project.

Implementation Patterns

Native Laravel reimplementation (the recommended path). The bundle's four pieces map cleanly onto Laravel primitives:

• Archetype as a template model. ProductArchetype with hasMany/belongsToMany to your existing attributes, properties, and options tables. Keep the pivots dumb (id pairs + a position column); keep behaviour in services.
• Product → archetype link. Nullable archetype_id on products with nullOnDelete() so an archetype can be retired without orphaning catalog data. Children read the archetype's collections only for defaults; they must own their finalised values so editing an archetype later doesn't retroactively rewrite live products.
• Builder service (App\Catalog\ArchetypeBuilder). Signature roughly build(ProductArchetype $archetype, array $overrides = []): Product. It copies attributes/options/properties onto the new product and applies overrides last. This is the single place inheritance logic lives — mirroring the bundle's builder instead of scattering $product->fill($archetype->toArray()) across controllers.
• Resolver (ArchetypeResolver). resolveFor(Product|string $subject): ?ProductArchetype, backed by an explicit column in the common case and by a strategy/chain for custom rules (category → archetype, SKU prefix → archetype). Inject the resolver; never hard-code ProductArchetype::find(3) in a controller.
• Registry (ArchetypeRegistry). A keyed collection populated from a config file (config/archetypes.php) so product families have stable string handles ('apparel.tshirt') usable in importers, seeders, and admin dropdowns without coupling to database IDs.
• Option → variant matrix. The bundle's core value is combinatorial expansion. Keep it as an explicit service (VariantMatrixGenerator::expand(Product $product): Collection) that materialises one variant per option-value combination, with a uniqueness guard on the combination key. Port the idea; the Sylius implementation won't run.

Workflow and integration tips:

• Admin (Filament/Nova/custom). Add an "Archetype" select to the product create form; on selection, resolve defaults and prefill the repeater fields. Do the prefill server-side on validation failure too, or editors lose the template the moment they hit a validation error.
• Importers. Accept an archetype column and run imports through the builder, so bulk-created products are structurally identical to admin-created ones. This is where the pattern pays for itself most.
• Seeders/fixtures. Seed archetypes before products, and make archetype seeders idempotent (updateOrCreate on the registry key) so re-seeding doesn't duplicate templates or detach products.
• API resources. Expose archetype as a reference (archetype: {id, key, name}) on product responses rather than inlining its attributes — clients that need the template can fetch it, and you avoid stale snapshots.
• Events. Emit ProductCreatedFromArchetype when the builder runs so search indexing, pricing rules, and third-party syncs can react to the template that produced the product.
• Legacy Sylius bridge (if forced). If a Sylius system must keep feeding a Laravel app, keep the boundary at data: export archetypes via a read-only endpoint/DB view and materialise them through the same builder. Never let Sylius service IDs or entity classes leak into Laravel code.

Gotchas and Tips

• Archived means you own every bug. 4 stars, 0 dependents, no maintainers, no PHP 8 or modern Symfony support. composer audit will flag it; architecture review will reject it. Treat any adoption as a permanent fork with an owner and an exit date.
• It cannot be "lightly" used in Laravel. There is no adapter path — the bundle is DI container, compiler passes, and Doctrine mappings. Any "let's just use the model classes" attempt drags in Sylius core (ProductBundle, AttributeBundle, OptionBundle, ResourceBundle) and collapses under modern PHP.
• Naming drift is the real trap. "Archetype" was superseded by ProductAttribute / ProductOption / ProductVariant in later Sylius. Grep exhaustively for Archetype before estimating a migration; you'll find it in fixtures, admin templates, form types, and serialized payloads, not just entities. Missing one leaves you chasing phantom data after the port.
• Retroactive mutation. The most common design bug in any archetype port: children referencing the archetype live instead of copying at creation. Decide explicitly — copy-on-create (recommended) vs. live reference — and write a test that edits an archetype and asserts existing products are untouched.
• Combinatorial explosion. Options multiply variants fast (3 sizes × 5 colors × 4 materials = 60 SKUs). Guard the generator with a max-combination config value and fail loudly rather than creating 10,000 variants inside a request.
• N+1 in admin listings. Archetype → attributes → options is three extra queries per product in a table view. Eager-load (with('archetype.attributes', 'archetype.options')) and consider a cached, flattened "defaults" payload if the list is large.
• Deletion semantics. Archetype deletes should null out products.archetype_id (or be blocked), never cascade into products. Enforce it at the FK level, not just in the model, so an importer bug can't wipe a catalog.
• Config quirks in the original. Its defaults come from bundle config merged through the Symfony container; there is no Laravel equivalent. When porting, make archetype config an explicit PHP array or a config/archetypes.php and validate registry keys at boot — silent missing keys are how you end up with a null archetype in production.
• Extension points are the only durable takeaway. The builder, resolver, and registry are the interfaces worth copying; the entities are throwaway. If you later swap to a real product-template package, keeping those three services behind interfaces means the swap is a binding change, not a rewrite.
• Debugging. There is no debugging path for the bundle itself in a Laravel app because it never runs. When porting, instrument the builder with a log line per copied attribute/option — mismatches between Sylius and Laravel output are almost always positional pivot data or option-code casing.