Download the PHP package jmf/crud-engine-bundle without Composer

jmf/crud-engine-bundle

A Symfony bundle that automates CRUD (Create, Read, Update, Delete) controllers and routes for Doctrine entities based on configuration, eliminating repetitive boilerplate code.

Requirements

• PHP 8.3+
• Symfony 7.0 or 8.0
• Doctrine ORM 3.0+

Installation

Register the bundle in config/bundles.php if not using Symfony Flex:

Quick Start

1. Configure the bundle

Create config/packages/jmf_crud_engine.yaml:

2. Load the routes

In config/routes.yaml:

3. Create templates (optional)

Out of the box, any action whose template is missing renders a built-in bare template, so the bundle works immediately. To customize a view, create a Twig template at the configured path (e.g., templates/article/index.html.twig, templates/article/create.html.twig, etc.) and it takes precedence automatically.

Prefer to fail loudly instead of falling back? Set schema.view.fallback: fail (see Missing templates).

That's it: the bundle automatically registers routes and wires up controllers for all configured actions.

Actions

The bundle provides five actions, each mapped to a controller:

Route paths and names are derived from the entity class name by default and can be overridden via configuration.

Configuration Reference

Template Placeholders

Configuration values and default patterns support the following placeholders:

Examples use the entity App\Entity\BlogPost: a two-word name, so the casing and pluralization differences are actually visible (with a single-word entity like Article they'd all look the same):

(Actions are always single words: index, read, create, update, delete, so their case variants only differ in capitalization; the actionKeys/actiondashkey/… variants exist for symmetry with the entity keys.)

Overriding placeholders (schema.keys)

These placeholders are not hard-coded: they are themselves defined as Twig patterns under schema.keys, and you can override them or add your own:

The contract:

• Overrides are merged over the defaults: declare only the keys you change.
• A key pattern may reference exactly two source variables: entityClass (the FQCN) and action (the action name, e.g. create), using Twig and the String component u.* filters.
• A key cannot reference another key (keys resolve only against the source variables). Doing so fails at container build time with a clear error.
• An unknown placeholder anywhere (a typo such as {{ entity_keyz }}) also fails loudly at build time rather than silently rendering empty.

The runtime placeholder {{ _entity.id }} used in redirection.parameters is not a key: it is resolved later, per request, against the actual entity, so it is unavailable in key/pattern definitions.

Per-entity configuration files (paths)

Instead of listing every entity under entities, you can keep one file per entity in a directory. Each file holds just the entity body (the actions: block); the entity FQCN is derived from the filename prefixed by a base namespace, so there is no jmf_crud_engine: / entities: / App\Entity\X: wrapper to repeat.

By default, this is enabled with zero configuration: the bundle loads <config-dir>/packages/<bundle-alias>/ (i.e. config/packages/jmf_crud_engine/) with the base namespace App\Entity. Just drop files in:

The filename (without .yaml) is appended to the namespace, so Article.yaml → App\Entity\Article. Subdirectories map to sub-namespaces (Blog/Post.yaml → App\Entity\Blog\Post).

Customizing the directories

Override paths to point elsewhere or to scan several directories (each with its own base namespace). A leading empty namespace makes the directory layout mirror the full FQCN (App/Entity/Article.yaml).

Setting paths explicitly replaces the default. paths and inline entities can be used together, but a given entity class must be defined in exactly one place: declaring it both via a file and inline (or across two scanned directories) throws CrudEngineDuplicateEntityException at container build time.

Notes

• Files support !php/const ... (e.g. a route requirements value) and the empty-action shorthand (read: with no body), exactly like inline config.
• As with inline config, the result is compiled into the container, so adding/editing/removing a file requires a container rebuild (cache:clear) to take effect.

Action Helpers

Action helpers allow you to customize behavior at specific lifecycle hooks without replacing the entire controller. Create a class extending the matching *ActionHelperBase and register it as a Symfony service. Each base implements the full interface with sensible defaults (the same behavior the bundle uses when no helper is configured), so you override only the hooks you actually need.

If the class name matches a configured default pattern (e.g., App\Controller\Article\CreateActionHelper), it is picked up automatically. Otherwise, set helper explicitly in the action configuration.

The configuration (route names/paths, form type and helper auto-discovery, view paths, etc.) is resolved once, at container build time, and cached in the compiled container. As with routes, adding a helper/form-type class that matches a discovery pattern requires a container rebuild (cache:clear) to be picked up.

Create Helper

The base also provides persist() (Doctrine persist + flush) and hookAfterPersist(). Override them only to change persistence or run post-save side effects.

Update Helper

Same hooks as the create helper, minus createEntity (the entity already exists). The default persist() here only flushes the already-managed entity; hookAfterPersist() is also available for post-save side effects.

Index Helper

Read Helper

Delete Helper

The base also provides remove() (Doctrine remove + flush), hookAfterRemove(), and onFailure() (re-throws the failure). Override them as needed.

Templates

Templates receive the entity (or collection) as a variable. The variable name is derived from the entity key (e.g., article for App\Entity\Article, articles for the index action).

Forms are passed as form (a FormView instance).

Example: templates/article/index.html.twig

Example: templates/article/create.html.twig

Missing templates

When the resolved template for an action does not exist, the behavior is controlled by schema.view.fallback:

The built-in templates are intentionally minimal: they exist to get pages rendering immediately and to be overridden. Providing your own template at the configured path always takes precedence over the built-in one.

Missing form types

For create/update, when no form type is configured (form.type) or discovered (via the schema.form.type patterns), the behavior is controlled by schema.form.fallback:

The generic form is a scaffold to be overridden: it maps scalar columns and enumType fields, and renders to-one associations as a choice of related entities; it skips identifiers, embeddables, to-many associations, and unmappable column types. Configuring or discovering a real form type always takes precedence.

To make the fallback visible wherever it renders (including under a custom template), the generated form prepends a disabled, read-only "Generated fallback form" field naming the form type class to implement to replace it.

License

MIT