Contao Developer Convenience Bundle Laravel Package

Getting Started

What you're getting. oneup/contao-developer-convenience-bundle is a dev-only helper bundle for Contao from 1up-lab, now archived with 5 stars and zero dependents. Treat it as a reference implementation and a local-development nicety, not a production dependency. Expect it to target the Contao 4 / Symfony 3–4 era.

1. Install as a dev dependency.

composer require --dev oneup/contao-developer-convenience-bundle

If Composer refuses to resolve, inspect the constraint before fighting it:

composer why-not oneup/contao-developer-convenience-bundle

2. Register it for the dev environment only. In a Flex-style Contao 4 app, config/bundles.php:

return [
    // ...
    Oneup\ContaoDeveloperConvenienceBundle\OneupContaoDeveloperConvenienceBundle::class => ['dev' => true],
];

Confirm the exact FQCN and any bundle alias from the repo's src/ and README.md — that's the first place to look after install. The second place is src/DependencyInjection/ for the configuration tree, and Resources/config/ for the services and tags it registers.

3. First use case. Clear the cache and load any Contao page in the browser:

bin/console cache:clear

Then look for its additions in the rendered output or the Symfony web debug toolbar (template names, container/request hints, block annotations — whatever the README advertises). The canonical workflow is: enable hints → render a page → read the annotation → jump straight to the exact Contao template or fragment that produced that markup.

4. Sanity check the version. Look at composer.json in the package for contao/core-bundle and symfony/* constraints. If you're on Contao 4.13+/Symfony 5+, this is the step most likely to fail before anything else does.

Implementation Patterns

Environment scoping is the whole pattern. The bundle is useful precisely because it's never loaded in prod:

• Flex: the ['dev' => true] entry in config/bundles.php above.
• Legacy AppKernel: wrap new OneupContaoDeveloperConvenienceBundle() in a $this->getEnvironment() === 'dev' check, or use the registerBundles environment switch.
• Put any package config in config/packages/dev/ so it can't leak into staging/prod.

Template-override hunting. The highest-value daily use is when a Contao template isn't doing what you expect and you can't tell which template is being rendered after inheritance and block overrides. Turn the bundle's hints on, render the page, read the HTML comments/attributes it injects, then diff that path against your templates/ overrides. This replaces the usual archaeological dig through Resources/views/ and app/Resources/Contao/.

Paired with the Symfony profiler. This bundle's usefulness scales with symfony/web-profiler-bundle + symfony/debug-bundle installed in dev. You get the toolbar, the request/container panels, and — via symfony/var-dumper — dump()/dd() inside Contao templates and controllers. Install all three together; the bundle alone is thin.

Workflow: hint-off default, hint-on demand. Wire the hints behind a dev config flag rather than leaving them permanently enabled. When you need them, flip the flag and hit cache:clear; when you're doing anything that asserts on markup, flip it back.

Extending it. Since it's archived, don't expect upstream hooks. If you want an additional hint or panel, the clean move is to copy the relevant service definition/compiler pass into a small in-house dev bundle and decorate the same tags, rather than subclassing a service that will never be updated.

CI. Use composer install --no-dev in CI and keep it out of your test suite entirely — the injected markup is exactly the kind of thing that makes HTML assertions flaky.

Gotchas and Tips

• Archived = frozen constraints. The most common failure is a Composer conflict on contao/core-bundle or symfony/config, not a runtime bug. Check constraints before composer require --dev; if it won't resolve, stop there rather than overriding with --ignore-platform-reqs.
• Never enable outside dev. The bundle injects markup into rendered pages. That leaks internal template paths and can corrupt output types (JSON, XML, plain-text emails). If you ever see stray comments in a JSON response, this is why.
• Cache is aggressive. Contao caches templates, DI, and translations hard. After toggling anything, bin/console cache:clear and, when in doubt, rm -rf var/cache/dev. Half the "the bundle does nothing" reports are stale cache.
• AJAX and email templates break. Hints that are harmless in HTML are fatal in Content-Type: application/json responses and in mailer templates. The classic symptom is a frontend fetch that suddenly JSON.parse-fails while the page looks fine in the browser.
• No profiler, no panel. If you expected a toolbar entry and see nothing, check that the web profiler bundle is installed and that APP_ENV=dev. The bundle's panel (if it ships one) hangs off the profiler.
• Debugging the bundle itself. When something isn't working and the README is silent, run bin/console debug:container | grep -i oneup and bin/console debug:config <alias> to see what actually got registered and which config keys exist. That answers more than the docs will.
• Vendor-lock it or copy it. With 5 stars, 0 dependents, and no maintenance, pin the exact version in composer.json, commit composer.lock, and consider vendoring the one or two classes you actually use into your own repo. That way a future Contao upgrade won't strand you on a dead package.
• Don't build a dependency on its output. No CI parsing, no test fixtures generated from its hints, no custom code that regex-matches its comments — you're depending on an unmaintained format that will change if you ever drop it or fork it.