Modlr Bundle Laravel Package

Getting Started

• Confirm you actually want this. as3/modlr-bundle is a Symfony bundle (2.x/3.x era) wrapping the standalone as3/modlr REST ODM. It has 2 stars and 0 dependents. If you are in Laravel, the realistic "getting started" is: install the core as3/modlr library (not the bundle) and wire it by hand — see Implementation Patterns.
• Install with Composer: composer require as3/modlr-bundle. If you are on a Symfony app, register As3\ModlrBundle\As3ModlrBundle in AppKernel (or bundles.php on later Symfony versions).
• Read these first, in order:
  1. The bundle README (thin — mostly config examples).
  2. DependencyInjection/As3ModlrExtension.php and Resources/config/services.yml — this is the authoritative list of services, aliases, and config keys. Trust the extension over the README.
  3. The upstream as3/modlr README for the ODM concepts (Manager, Connection, Adapter, metadata drivers, persisters) — the bundle is mostly DI glue around these.
• Configure a connection (shape expected under as3_modlr: — verify keys against the extension, since they shift between versions):

  as3_modlr:
      connections:
          default:
              base_url: "%modlr_api_url%"
              adapter:  { type: guzzle, ... }   # whatever adapters the bundle registers
      managers:
          default:
              connection: default
              mappings:
                  AppBundle: { type: annotation, dir: Entity }
  

• First use case — read-only remote catalog. Define one entity (Product), map its metadata to the REST payload, inject the Modlr manager into a Symfony controller/service, and call find() / findAll() against the remote API. Do this before attempting persistence; reads are where this package is least surprising.

Implementation Patterns

• Entity-as-POPO. Modlr entities are plain PHP objects; mapping lives in metadata (annotations via doctrine/annotations, or a driver configured in mappings). Keep entities dumb, keep transport concerns in the connection/adapter.
• Inject the manager, not the connection. Register a thin ProductRepository service that depends on the Modlr manager/repository and exposes domain methods (activeProducts(), bySku()). Do not let controllers talk to the manager directly — you want a seam to swap it out later.
• Thin repository over query translation. Modlr querying maps to REST query params/filters rather than SQL. Keep filtering/sorting logic in the repository so it stays testable and so you can mock it.
• Cache aggressively at the edge. Because every read is an HTTP round-trip, put a Symfony cache decorator (or Laravel cache) around the repository. Treat the REST API as the system of record and your app as a read-through cache.
• Write path, if you must. Persistence goes through a persister that issues POST/PUT/PATCH. Wrap it in your own service that catches transport errors and returns domain results — never let raw HTTP exceptions leak into controllers.
• Laravel bridging (the honest pattern). You cannot register a Symfony bundle in Laravel cleanly. Instead:
  1. composer require as3/modlr (core library only).
  2. Build a ModlrServiceProvider that constructs the Manager/Connection/adapter yourself, using Laravel config and a Guzzle client bound in the container.
  3. Bind a singleton per connection and inject repositories via the container.
  4. Skip the bundle entirely — its value is DI wiring you can replicate in ~40 lines.
• Testing. Mock the underlying HTTP client (Guzzle handler stack) rather than the Modlr manager. Test your repository against recorded fixtures; test controllers against a fake repository. The ODM itself is thin and doesn't need its own mock layer.
• Console sync jobs are a common pattern: a scheduled command walks a REST collection, hydrates entities, and writes to your own DB. This turns Modlr into an ingestion tool rather than a live ODM and is far more robust than live remote queries in request paths.

Gotchas and Tips

• Maintenance reality. The package is effectively abandoned (2 stars, 0 dependents, Apache-2.0, pre-PHP-8). Expect Guzzle 3/5/6-era constraints, missing type declarations, and no PHP 8 compatibility. Pin PHP and dependency versions, or vendor a fork.
• Config key drift. The as3_modlr config schema is not documented well; read As3ModlrExtension and any Configuration.php. Copying examples from old blog posts will silently fail or throw InvalidConfigurationException.
• Annotation autoloading. The annotation driver requires doctrine/annotations and correct PSR-4 paths in mappings. If entities hydrate as empty objects, the metadata driver is almost certainly not finding your classes — check the bundle's mapping compiler pass output.
• Identity map / stale objects. Like Doctrine, the manager keeps an identity map; long-running workers will serve stale entities. Reset the manager per job or per request in queue workers.
• HTTP errors surface late. REST failures often appear as incomplete hydration or null fields rather than exceptions. Add explicit response-status assertions in the adapter (or a logging middleware) so 4xx/5xx are loud.
• Pagination is manual. Do not assume findAll() paginates. Inspect the returned collection type; iterate pages explicitly and guard against unbounded loops.
• Credentials in config. base_url/auth tokens belong in environment variables and Symfony secrets, not config.yml. The bundle has no credential redaction in error logs — verify before shipping.
• Debugging tip: enable the HTTP client's debug/log middleware first; 90% of "the ODM is broken" issues are transport or metadata, not ODM logic.
• Extension points worth knowing before you customize: the adapter (swap HTTP client), the persister (write behavior), and the metadata driver (YAML/annotation/XML). Forking the bundle to change DI wiring is usually less work than fighting its compiler passes — but if you are on Laravel, skip the bundle and use the core library directly.