Symfony Aggregated Queries Laravel Package

Getting Started

Because v1.0.2 ships no API or behavior changes, there is no migration step — if you are already on a 1.0.x release, composer update is the whole upgrade. If you are adopting the package fresh:

1. composer require the package and confirm the service provider is auto-discovered (Laravel) or registered manually (Lumen / older skeletons).
2. Publish any config with php artisan vendor:publish --tag=... and read the config file before touching code — the defaults are usually the intended production path.
3. Open the README's quick-start example and the new benchmark section side by side. The benchmark is the fastest way to understand the intended call shape and the cost profile of a realistic workload.
4. Run the shipped benchmark (or the closest equivalent in your app) against your own dataset size before wiring it into a request path.

Where to look first: the README quick start, the package's benchmark harness added in v1.0.2, and the config file. Skip the source until one of those three leaves a question unanswered.

First use case: take the single highest-frequency call in your app that this package covers, implement it behind the benchmark's suggested configuration, and measure it in a staging environment. The benchmark exists precisely so you can decide "is this fast enough for my traffic shape" without building your own harness.

Implementation Patterns

• Benchmark-first adoption. Use the Symfony benchmark in the repo as a template, not just a number. Copy its dataset shape (row counts, payload sizes, concurrency) into a local script so your measurements are comparable across releases. This matters more than the published absolute figures, which will not match your app.
• Wrap the package behind a thin application service. Even with a stable 1.0 API, route calls through a small service or repository class. It gives you a single place to add caching, swap implementations, and instrument timings without touching call sites.
• Feature-flag the rollout. Ship behind a config flag or Laravel Pennant feature so you can compare old and new paths in production on real traffic, and roll back without a deploy.
• Pair with Laravel's tooling. Register the package's calls in Telescope or a custom middleware for local debugging, and lean on Octane compatibility checks if you run RoadRunner/Swoole — long-lived workers change the cost profile of anything with static state.
• Treat benchmarks as a regression gate. If CI is cheap enough, add a lightweight version of the benchmark as a non-blocking job. Compare against the previous release on the same runner rather than absolute thresholds; runner variance will drown out small regressions otherwise.
• Integration tip: when combining with queues, benchmark the job payload serialization cost too. The Symfony benchmark covers the library path, not your job wrapper or Eloquent hydration around it.

Gotchas and Tips

• Benchmark numbers are not your numbers. The v1.0.2 figures come from a Symfony application with a curated dataset. Laravel's container, Eloquent hydration, and middleware stack add overhead the benchmark does not model. Reproduce the shape locally before quoting any figure internally.
• "No behavior changes" still means re-run your tests. Patch releases can carry dependency bumps. Diff composer.lock after updating and run your suite plus one smoke test against staging.
• Watch for hidden state under Octane. Any package that caches aggressively will show different numbers in a long-lived worker. If the benchmark looks great in a CLI script but disappoints in the app, worker lifetime is the usual culprit.
• Debugging slow paths: isolate the package call from your surrounding code first — a microbenchmark of the single call, with your real payload, will tell you whether the cost is the package or your dataset. Only then reach for a profiler.
• Config quirks: published config files drift from package defaults across releases. If you published config in an earlier 1.0.x, diff it against the vendor copy after updating; stale config is the most common cause of surprising behavior after a patch.
• Extension points: prefer the package's documented interfaces and events over subclassing internals. With a stable 1.0 API surface, extension points are the part most likely to be formally supported going forward.
• Don't over-index on one release of benchmarks. Track the numbers across versions; a single data point is a marketing claim, a trend line is engineering evidence.