Allegro Redis Odm Bundle Laravel Package

Getting Started

Read this first: the framework mismatch. phillarmonic/allegro-redis-odm-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no config/*.php publish tag, no facade. If you are working in a Laravel codebase, this is not the dependency you install — you would reach for a Laravel-native Redis document mapper or just use Illuminate\Support\Facades\Redis with your own serialization. This assessment is therefore written from the perspective of a Laravel developer who has to evaluate, integrate, or maintain a Symfony service (or a mixed/legacy stack) where this bundle is the candidate.

Minimal steps once you've confirmed the framework fit:

1. composer require phillarmonic/allegro-redis-odm-bundle and check composer.json in the repo for the supported PHP and Symfony version range before installing — this is the single highest-risk constraint.
2. Register the bundle in config/bundles.php.
3. Create config/packages/<bundle_alias>.yaml with your Redis DSN/connection and mapping paths. Open DependencyInjection/Configuration.php in the repo to get the real config tree — it is the authoritative documentation, not the README.
4. Put your connection string in .env (REDIS_URL=redis://...) and reference it in the YAML.
5. Define one document class, write a smoke test that persists and retrieves it, and run it against a local Redis (docker run -p 6379:6379 redis:7-alpine).

Where to look first, in order: composer.json (version constraints) → DependencyInjection/Configuration.php (config surface) → DependencyInjection/*Extension.php (what services are actually registered and their IDs) → Resources/config/*.xml|yaml (service definitions and aliases) → the ODM package it wraps, since the bundle is thin and the real API lives there.

First use case that justifies the bundle: a Redis-backed store for high-write, low-query data — session/activity records, analytics counters, ephemeral job payloads, cached API response snapshots — where you want typed document objects and repositories rather than raw hset/json.set calls scattered through services. If your data is relational, needs joins, or needs multi-document transactions, stop here.

Implementation Patterns

Prefer injected repositories over the document manager. The bundle's value is autowiring; use it. Inject a specific repository into the service that owns that aggregate rather than injecting a global DocumentManager and calling getRepository() everywhere — the latter recreates the service-locator problem you adopted a DI container to avoid. Use the manager only at boundaries where the document type is genuinely dynamic.

Wrap the package behind one of your own interfaces. With 5 stars and a single maintainer, this is not a package to let leak into 40 files. Define App\Persistence\DocumentStoreInterface and implement it with the ODM manager. That interface is your escape hatch, your test seam, and the thing you rewrite if the bundle is abandoned.

Environment-specific configuration. Keep the connection block identical across config/packages/{dev,test,prod} and vary only the DSN and database index. Give each environment (and each parallel test worker) a distinct Redis logical DB or key prefix — see gotchas.

Testing pattern. Use a dedicated Redis database (e.g. redis://localhost:6379/15) in config/packages/test/, flush it in setUp, and assert against documents rather than raw keys. Because there are no migrations and no schema, a dirty test keyspace produces failures that look like logic bugs. Prefer FLUSHDB on the test DB only, or namespace every key with the test's name and delete by prefix in tearDown.

Multiple connections / managers. If the bundle exposes more than one manager (verify in the extension class), use the pattern: one manager for volatile data with a TTL, one for durable documents. Do not mix TTL'd and permanent documents in the same repository — the "why did my record vanish" bug is always an inherited TTL from a key prefix collision.

Consistent key naming. Agree a convention up front — {env}:{domain}:{document}:{id} — and encode it in one place (a base document class or a key-building service), not in each document. Redis keyspace is the database; treat it like a schema you cannot migrate.

Integration points worth wiring: Symfony Messenger for persisting message payloads or dead-letter records; the Serializer for normalizing API responses into documents; a console command for periodic key auditing/cleanup (SCAN + TTL report) rather than ad-hoc redis-cli sessions.

If you are bridging into Laravel (mixed stack, shared Redis, data written by a Symfony service and read by a Laravel app): never share configuration. The Laravel side should talk to the same Redis keyspace through an explicit, versioned serialization contract you own, not by trying to instantiate Symfony services. Treat the document format as an API between the two applications.

Gotchas and Tips

• No Laravel integration, and none coming. The assessment-pm.md in the repo reads like generic Laravel-ecosystem boilerplate (migrations, Blade/Inertia scaffolding, config publishing). None of that applies to this bundle. Discount that document almost entirely when making a technical decision; use composer.json and the DependencyInjection directory instead.
• Abandonment risk is the dominant risk. 5 stars, one maintainer. Pin the exact version in composer.json, commit the lockfile, and record the bundle in your upgrade plan alongside your Symfony/PHP major upgrades. If the package stops tracking Symfony releases, you fork or replace — which is why the interface wrapper above is not optional.
• Symfony version lag is the silent failure mode. A bundle that hasn't been tagged against the Symfony version you're on may still install and then fail at container compile time with a service-definition error. Check the constraints before the spike, not after.
• Config alias discovery. Symfony bundle config keys are derived from the extension alias, which is often not the vendor name. If your YAML is silently ignored, run bin/console config:dump-reference <alias> and bin/console debug:container | grep -i redis to find the actual alias and the registered service IDs.
• No migrations, no schema, no rollback. Index creation, key renames, and document shape changes are manual operations. Write them as idempotent console commands in your app and check them in — otherwise the first data-model change becomes a one-off redis-cli session nobody can reproduce.
• Serialization is where documents break. Dates, enums, nested documents, and nulls all round-trip differently from a relational ORM. Test a full persist→load cycle for every field type in a document the day you add it, including the empty-string vs. null distinction.
• TTL and prefix collisions. If the bundle applies a global key prefix or a default expiry, documents you believe are permanent will disappear. Verify with TTL <key> on a freshly persisted document during the spike.
• Debugging workflow: redis-cli MONITOR to see exactly what commands the ODM emits (invaluable for understanding what the manager actually does), SCAN 0 MATCH prefix:* COUNT 100 instead of KEYS * on anything shared, and bin/console debug:container <service_id> --show-arguments to confirm what was injected. Log the DSN host/db at boot in dev — pointing the test suite at production Redis is a classic.
• Connection specifics need explicit handling: TLS (rediss://), ACL usernames, cluster mode, and selecting a logical database are the four things that most often silently differ between your local Redis and production. Confirm each is configurable through the bundle's config tree; if not, that's a fork.
• Extension points to look for before forking: decorate the document manager service, register a custom repository class per document, and hook whatever event/listener mechanism the ODM exposes. Decorating a service in services.yaml is a two-line change and survives upgrades better than patching vendor code.
• Budget the spike honestly. A timeboxed day: install, one document with three field types, persist/load/delete, one repository injected into a service, one test asserting round-trip against a containerized Redis. If that doesn't work cleanly, the answer is to build the narrow slice yourself — for a single document type, raw Redis plus a small serializer is maybe 200 lines you fully control.