Archetype Laravel Package

Getting Started

• Treat this as internal infrastructure, not a library you adopt. The repository is a read-only subtree split of the Archetype component that lives in the main Sylius/Sylius monorepo, and it is archived. Do not fork it, open PRs against it, or add it to composer.json as a direct dependency. If it is already installed, find out why with composer why sylius/archetype (it usually arrives transitively through Sylius ResourceBundle / Sylius).
• Look at the component source first — it is tiny. The day-to-day surface is a small set of value objects and collaborators around three concepts: an Archetype (a named bag of templates), a Template (a named artifact with a target path and renderable source), and the manager/factory/renderer that build and render them. Start with ArchetypeInterface, TemplateInterface, then the factory/manager and the renderer. Everything else is glue.
• First real use case: inspect generated output. In a Sylius application, the Archetype component is what sits behind resource/code generation. Run the generator command your Sylius version exposes (for example a sylius:generate:* command wired by ResourceBundle), generate a model or controller, and diff the output against the templates. That teaches you the component's contract faster than reading it abstractly.
• Minimal programmatic shape (class names and signatures vary by version — read the installed source):

$archetype = $archetypeFactory->create('book');

$archetype->addTemplate(
    $templateFactory->create('class', 'src/Entity/Book.php', '@App/generator/entity.php.twig')
);

foreach ($archetype->getTemplates() as $template) {
    $code = $renderer->render($template, [
        'namespace' => 'App\Entity',
        'class'     => 'Book',
    ]);

    $filesystem->dumpFile($template->getPath(), $code);
}

• Configure Twig deliberately. Rendering is template-driven; provide a Twig Environment with a FilesystemLoader pointing at your generator templates and strict_variables: true outside production.

Implementation Patterns

• One archetype per resource, one template per artifact. A typical archetype contains templates for the class, interface, repository, factory, form type, and controller. Keep the archetype name aligned with the resource concept (book, order, invoice) so generated files and service IDs stay predictable.
• Drive archetypes from configuration, not hand-written PHP. Whether your version loads archetypes from YAML, a config array, or a custom loader, treat the archetype definition as data: template name, target path, Twig source, and required context keys. This keeps generation reproducible and lets non-developers add artifacts.
• Centralize the rendering context. Build a context array (namespace, class, resource_name, bundle, entity, repository) in one factory/service. Every template receives the same keys, which prevents the "works for model, breaks for controller" drift that kills code generators.
• Wrap generation in a console command. Accept resource name, target namespace, and a --dry-run / --force flag. Render into memory (or a temp directory) first, validate all outputs, then write. That gives you atomic-ish generation and a readable diff in CI.
• Override in the application, not in vendor. In a Sylius app, copy templates into your own templates directory and point the generator at them; or decorate the archetype manager/renderer service. Never patch vendor/sylius/archetype — the next composer update wipes it.
• Decorate the extension points. The renderer, archetype factory/manager, and name/path resolvers are the intended seams. A custom renderer lets you change templating syntax; a decorated manager lets you inject extra archetypes; a custom path resolver lets you emit into bundle-specific directories.
• Test generation as output, not as internals. Use snapshot/fixture tests on rendered code, and vfsStream or a temp directory for filesystem assertions. Unit-test the context builder separately; it is where most generation bugs hide.
• Pipeline hygiene. Treat generated files as source: run PHP-CS-Fixer and static analysis on them, add a generated-file header, and either commit them or regenerate deterministically in CI — never both inconsistently.

Gotchas and Tips

• Read-only and archived means no upstream support here. Issues and pull requests belong in Sylius/Sylius. If you rely on a fix, carry a patch (Composer patch plugin) until the monorepo change lands, and plan to drop it.
• Version drift between the split and the monorepo is real. The subtree split's tags can lag or differ from what sylius/sylius ships. Trust the version resolved in your lock file (composer show sylius/archetype) and the source under vendor/, not the GitHub repository's default branch.
• There is no bundle here. No DI extension, no config tree, no routes, no autoload magic for templates. The Symfony/Sylius integration lives in the consuming bundle; don't expect sylius_archetype: YAML to work unless that bundle is installed and wired.
• Undefined Twig variables fail silently. In non-strict mode, a missing namespace or class renders as an empty string and produces subtly broken PHP. Enable strict_variables in dev/CI and assert required context keys before rendering.
• Overwrite semantics are your responsibility. Most generators simply dump files. Without an existence check plus an explicit --force, you either clobber hand-edited code or silently skip regeneration. Decide the policy and test it.
• Path resolution surprises. Relative target paths resolve against the process working directory, which differs between CLI, tests, and CI. Prefer absolute paths or %kernel.project_dir%-anchored configuration.
• Sanitize names used in paths. Templates are code and target filesystem paths; validate resource names against a whitelist to prevent path traversal or accidental overwrites.
• Debug by dumping the contract. Before rendering, log the archetype name, each template name, its resolved path, and the full context array. Most "generator is broken" bugs are wrong paths or missing context keys, not rendering failures.
• Low adoption signal is a design constraint. With very few stars, zero GitHub dependents, and an archived status, expect no tutorials, no Stack Overflow answers, and no community plugins. The source is small enough to read end-to-end — do that before inventing workarounds, and prefer Symfony Maker or a standalone code-generation library for greenfield non-Sylius projects.