Useful Bundle Laravel Package

Getting Started

Decide which context you are in before writing code. This is a Symfony 2 bundle, not a Laravel package, and there is no path to composer require inside a Laravel app — Laravel 9+ ships Symfony 6/7 components and the resolver will fail on the bundle's symfony/*: ~2.x constraints. "Getting started" therefore has two distinct shapes:

• Legacy Symfony 2 app (the only install path). composer require shtumi/useful-bundle, then register new Shtumi\UsefulBundle\ShtumiUsefulBundle() in app/AppKernel.php. There is no auto-discovery; Symfony 2 has no Flex. Clear the cache (bin/console cache:clear) and dump the container to confirm services exist.
• Laravel / modern Symfony (the realistic path). Do not install. Clone the repo into a scratch directory and read it as a reference for a port.

Where to look first — the README is thin, the DI config is the API. Read the code in this order:

1. composer.json — require block. If php is ~5.x or symfony/symfony is ~2.x, stop and decide whether you are reading code or installing it.
2. DependencyInjection/ and Resources/config/services.yml — the service IDs, tags, and constructor arguments tell you what is actually wired. The bundle is a bag of small services; the DI file is its real table of contents.
3. Twig/, Form/Type/, Doctrine/, Validator/Constraints/ — one directory per feature family. Each file is small and self-contained.

First use case — validate the cheapest thing. The Twig extensions are the least coupled pieces (pluralization, HTML-safe truncation, word wrapping) and are the easiest to verify. In a Symfony 2 app, register the bundle and immediately try one filter in a template to confirm it is active. In a Laravel context, the analogous first step is to copy a single filter into a Blade @directive or a global helper, add one test, and confirm the behavior matches — that is the whole "spike."

Implementation Patterns

Adopt piecemeal, not wholesale. Every feature family is independent. Enabling the bundle costs nothing extra, but there is no reason to wire up DQL functions if you only want the form types. Treat the DI config as a menu; each service is opt-in at the point of use (a ->add('startDate', 'shtumi_datepicker') call, a |pluralize filter, a DQL function registration), not a framework you build on top of.

Form types follow the "extend a base type, add JS" pattern. Symfony 2 form types like shtumi_datepicker and shtumi_daterange wrap the built-in date type and attach a JavaScript widget; shtumi_autocomplete takes an entity class and a query-builder callback; shtumi_dependent_filtered_entity chains one field's options to another's value over AJAX. In a Symfony 2 codebase they are used as string type names in FormBuilder and configured via setDefaults options — treat them as third-party form types, not primitives, and read each type's configureOptions before assuming the option shape.

DQL functions are registered on the ORM config, then used inline in DQL. In Symfony 2 the registration lives under doctrine.orm.dql in config.yml (or the entity manager config). After that a function like DATE(field) becomes callable in DQL. The value is real only if the corresponding native SQL dialect gap actually exists in your app — a lot of these helpers predate Doctrine gaining an equivalent, so check before porting.

Twig extensions are the portable surface. Filters here are pure string functions; they have no Symfony 2 dependency in spirit (only the Twig_Extension base class in letter). In Laravel the translation is trivial: a Str-backed helper class registered via composer.json "files", or a Blade directive for the templating form.

Port to Laravel by mapping the four families to four idioms, not by copying code:

Treat one file at a time, with attribution and a test. The bundle is small — a few hundred lines total — so the practical porting pattern is: read one class, reimplement it in app/Support/, write the test that defines its expected behavior, and cite the source in a comment. Do not vendor the whole bundle; the coupling will cost more than it saves.

Gotchas and Tips

The composer install failure is your first diagnostic, not a bug. If requirements conflict, you have just confirmed the package targets a Symfony 2 dependency set. Do not try to --ignore-platform-reqs your way past it — the code will fatal on PHP 8 deprecated syntax (each(), curly-brace string offsets, Twig_Extension class names removed in Twig 2/3) long before it runs usefully.

Bundle auto-discovery does not exist here. In Symfony 2 you must add the bundle to AppKernel::registerBundles(). Forgetting this is the usual reason "the Twig filter isn't found" — the service was simply never loaded. Verify with bin/console debug:container --tag=twig.extension and bin/console debug:twig.

Check the Twig major version before assuming the extension base class. Symfony 2 apps vary between Twig 1 and Twig 2; Twig_Extension (1.x) and AbstractExtension (2.x) are not interchangeable. If you are reading code to port, this is also a signal: Twig_Extension_* class names are a hard break for Twig 3-era projects.

DQL function names can silently shadow Doctrine built-ins. A custom DATE or CONCAT implementation with subtly different semantics produces wrong results without an error. If you use any DQL function from this bundle, add an integration test with a known dataset that asserts the exact output — the bundle itself has no test corpus you can lean on.

No dependents, no tests, single maintainer — treat the repo as read-only source. If you actually copy a non-trivial class (the autocomplete or dependent-filtered-entity types are the only candidates), vendor the file into your repo with a header noting the origin and the commit SHA. Do not depend on Packagist availability.

Verify the license before lifting code. Check LICENSE and the license field in composer.json — attribution requirements vary and this is a copy-paste port, not a link dependency.

Debugging in a live Symfony 2 app is via the profiler, not logs. The Twig and form-type services appear in the profiler's timeline; if a filter renders unexpectedly, look at the resolved service argument chain in var/cache/dev/Container*/. Cache invalidation is the other common failure — after editing anything under DependencyInjection/, bin/console cache:clear --no-warmup is usually what "broken" actually means.

The extension point is Configuration.php, not annotations. If the bundle exposes toggles, they are parameters under DependencyInjection/Configuration.php — configure them in config.yml under the bundle's key and check config:dump-reference for the shape. Do not expect a service-provider-style binding you can override in user code.