Config Bundle Laravel Package

Getting Started

This bundle is not a standalone configuration manager — it exists to expose Doctrine-backed configuration entities inside the KunstmaanCMS admin. If you are not already running Kunstmaan bundles (kunstmaan/admin-bundle, node-bundle, page-bundle, …), it adds little: the value is the editor-facing settings screen, not the entity base class.

Minimal path:

1. Confirm the stack first. Check the bundle's composer.json against your Symfony, PHP and Kunstmaan versions before composer require kunstmaan/config-bundle. This is legacy-suite code (Symfony 2.8/3.x era); on a modern Symfony app you will hit dependency resolution problems.
2. Register the bundle. Legacy Symfony: new Kunstmaan\ConfigBundle\KunstmaanConfigBundle() in AppKernel. Symfony 3.4+/4: add it to config/bundles.php.
3. Read the bundle end to end before integrating. It is small. Start in Entity/ (the abstract config base class you extend, plus its internal-name/timestamp fields), AdminList/ (how config entities are listed and edited in the CMS settings UI), Resources/config/ (services, routing, admin menu registration), and Form/ (the form type used for editing).
4. Check routing and the admin menu are imported — the settings screen is usually the first thing that 404s if the bundle's routing file was never pulled in.
5. First use case: a single "Site Settings" record holding values editors change without a deploy — support email, social URLs, analytics ID, footer copy. Extend the abstract config entity, add your columns, surface it in Twig so templates read from the managed row instead of hard-coded literals.

Representative entity (verify the base-class FQCN against the bundle's Entity/ directory):

namespace AppBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use Kunstmaan\ConfigBundle\Entity\AbstractConfigEntity; // confirm the exact FQCN

/**
 * @ORM\Entity
 * @ORM\Table(name="app_site_settings")
 */
class SiteSettings extends AbstractConfigEntity
{
    /** @ORM\Column(type="string", nullable=true) */
    private $supportEmail;

    /** @ORM\Column(type="string", nullable=true) */
    private $analyticsId;

    // getters / setters
}

Then update the schema (bin/console doctrine:schema:update --dump-sql, review, apply), clear the cache, and confirm the record appears in the CMS settings area. Finally expose it to Twig:

// Twig extension — fetch once per request
$settings = $this->settingsRepository->findOneBy([]);
$twig->addGlobal('site_settings', $settings);

Implementation Patterns

Singleton vs. collection configs. Two shapes dominate. A singleton entity (one row, e.g. SiteSettings) is the natural fit for global values — enforce "one row" in your fixture/console seeder and in the admin list. A collection config (many rows of the same type, e.g. redirects, office locations, banner entries) reuses the same base class; rely on the internal-name field for human-readable identification and add sorting/enabled columns yourself.

Never let templates see null. Seed a default row on deploy with a console command or Doctrine fixture so Twig accessors never explode on a fresh environment. This is also the cleanest place to encode "factory defaults" for every setting.

Cache at the request/service layer, invalidate on save. Config is read on every page, so don't hit the DB per template render. Fetch once into a request-scoped service or Twig global and reuse it. If you cache more aggressively (APCu, filesystem), hook a Doctrine postPersist/postUpdate listener on the config entity to bust the cache — otherwise editors save a change and see the old value until you clear the cache manually.

Validation lives on the entity. Because the admin form is largely introspected from Doctrine metadata, Symfony validation annotations/attributes on your properties are your primary lever for constraints (email format, URL, required-ness). Write a custom form type when a column type isn't rendered sensibly by the auto-generated form.

Multilingual and multi-site decisions come early. Kunstmaan supports multiple domains from one CMS and translatable content. Decide per setting whether it is global, per-locale (editor sees a tab per language) or per-site (key records by host/site). Retrofitting this after editors have entered data is painful.

Consume it everywhere, not just templates. Expose a SiteSettingsProvider service and inject it into PagePart controllers, sitemap generation, transactional email builders and sitemap/SEO code. This keeps one source of truth instead of three copies of an analytics ID.

Respect the deployment boundary. Config rows are content in the database, not code. They don't travel with a git deploy, so staging and production drift. If you need parity, add an export/import command (serialize rows to YAML fixtures) — but never let it overwrite production edits silently.

Lock down the admin. Config screens are often the only place editors can change site-wide behaviour. Add role checks / ACLs in the admin menu and controller so a content editor can't rewrite the mailer address.

Gotchas and Tips

• Treat it as dormant. One star and zero dependents is the signal: this is suite-internal, not a widely adopted package. Pin an exact tag, expect no upstream fixes, and be prepared to fork or vendor-patch rather than wait for a release.
• Symfony version cliff. The code predates Symfony 4/5 conventions. Dropping it into a current application is usually a dead end; the effort is better spent moving the entity definitions into your own bundle (they're plain Doctrine entities, and the tables/rows survive the move untouched).
• Entity changes ≠ data changes. Adding a column gives existing rows NULL. Every schema change needs a migration and a plan for existing data (default value, backfill command, or null-tolerant templates).
• Cache-clear is not automatic. In dev, editing the entity or admin list frequently requires bin/console cache:clear before the settings screen reflects the change; in prod, remember that config caching layers can serve stale values after an editor saves.
• Auto-generated forms only cover the column types the bundle knows about. Custom Doctrine types, JSON blobs and relations often render poorly or not at all — write an explicit form type for those fields.
• Don't put secrets here. The CMS admin and every database dump expose config rows. API keys, SMTP passwords and similar belong in environment variables/parameters.yml, with the config entity holding only non-sensitive values.
• Debugging checklist: bin/console debug:container | grep -i config and debug:router | grep -i config to confirm services and routes registered; the Symfony profiler's Doctrine panel to see the queries; and the bundle's Resources/views/ to confirm which template is actually rendering if you've overridden it. A 404 on the settings screen is almost always missing routing or a firewall rule, not a code bug.
• Overrides before forks. Template overrides (app/Resources/KunstmaanConfigBundle/... or templates/bundles/...) and service decoration cover most customisation; the bundle is small enough that a local fork is also viable if you need real behavioural changes.
• Know the exit. If the bundle becomes untenable, the migration is mechanical: copy the entity classes into your application bundle, point templates/services at your own provider, and keep the existing tables. Plan that exit before you build a lot of admin UI on top of it.