ongr/api-bundle
Symfony bundle for exposing ONGR Elasticsearch documents through a configurable REST API. It provides routing, serialization, and endpoint configuration to build search and CRUD APIs with less boilerplate.
A v1.0.0 tag now exists, but its release notes are literally "First major release" — no changelog, no upgrade guide, no constraint changes documented. Treat that tag as an unverified signal, not as proof the package modernised. The project sat without a release from April 2016 until this tag, and nothing published alongside it says PHP 8 or Symfony 5/6/7 is supported. Before you plan any work, open the repository's composer.json on the v1.0.0 tag and confirm:
>=5.6 / ~7.0 unless the tag says otherwise)symfony/symfony or individual Symfony component constraints (historically ~2.8 / ~3.0)ongr/elasticsearch-bundle version, and therefore the Elasticsearch server version (historically ES 1.x/2.x)Compare the v1.0.0 composer.json against the last pre-2016 commit. If the constraints are unchanged, this is a re-tag, not a revival — and the legacy playbook below still applies verbatim. If they did change, re-run this assessment against the new constraints before trusting any of the patterns below.
Minimal install steps (legacy Symfony app):
composer require ongr/api-bundle:^1.0
// app/AppKernel.php
$bundles = [
// ...
new ONGR\ElasticsearchBundle\ONGRElasticsearchBundle(),
new ONGR\ApiBundle\ONGRApiBundle(),
];
# app/config/routing.yml
ongr_api:
resource: "@ONGRApiBundle/Resources/config/routing.yml"
prefix: /api
# app/config/config.yml
ongr_api: ~ # verify the real tree in DependencyInjection/Configuration.php
Then clear the cache and hit an endpoint with curl to confirm routing and container wiring are intact.
Where to look first, in this order:
v1.0.0 diff against the previous tag — this is the single most valuable thing you can read, and it is the only substitute for the missing changelog. If there is no diff beyond a version bump, you have your answer about how much to trust the release.README.md — the bundle's own install and usage notes.DependencyInjection/Configuration.php — the authoritative config tree; every config key you use must exist here.Resources/config/*.yml — service ids, controller wiring, and route definitions. This tells you what the bundle actually exposes.Controller/ — the entry points. Read each action's dependencies and return shape before designing around it.Tests/ — the most reliable source of working examples for a package this old.First use case: expose a read-only endpoint over an existing Elasticsearch document. Wire one controller action that takes the ES document manager/repository, executes a simple query, and returns JSON. Verify with curl before adding write paths, pagination, or serialization groups. Keep the first endpoint deliberately boring; the goal is to prove the container, routing, and ES connection all work together.
Treat it as a thin Symfony bundle, not a framework. The day-to-day model is: controller -> service -> Elasticsearch document manager/repository -> serialized response. Most of your application logic will live in your own services, with this bundle providing routing, controller glue, and configuration conventions.
Read path pattern. Inject the ES document manager (or a repository) into a controller or application service, build the query, and return a JsonResponse or a serialized array:
public function listAction(DocumentManager $dm): JsonResponse
{
$repo = $dm->getRepository(Product::class);
$results = $repo->findBy(['published' => true], ['createdAt' => 'desc'], 20);
return $this->json(['items' => iterator_to_array($results)]);
}
Keep query construction out of the controller when it grows beyond a single filter; move it into a repository or query-builder service so it is testable.
Write path pattern. If the bundle exposes write actions, validate input with the Symfony Validator before persisting. If it only exposes read endpoints, implement writes in your own service layer and use the bundle's routing conventions only where useful. Either way, keep the HTTP layer thin and the persistence logic in services.
Serialization discipline. Identify early whether the bundle leans on JMS Serializer annotations or the Symfony Serializer (check composer.json and any serializer service config). Once you know, define explicit serialization groups per endpoint and never expose raw ES documents. ES documents often include internal fields (_id, _score, _source wrappers, timestamps) that should not leak to clients.
Routing and versioning. Use a versioned prefix from day one:
ongr_api:
resource: "@ONGRApiBundle/Resources/config/routing.yml"
prefix: /api/v1
This costs nothing now and saves you when the bundle's route shapes inevitably change (or when you replace it). It also means that if a future release does modernise the bundle, your URLs survive the swap.
Pagination and limits. ES makes it trivial to request size: 10000. Enforce a maximum page size in a shared request parser or controller base class. Return total, page, per_page, and items consistently across endpoints.
Error handling. ES exceptions (index missing, mapping conflict, connection refused) should not become 500s. Add a kernel exception listener or wrap repository calls to map:
Testing workflow. Use Symfony's KernelTestCase/WebTestCase for functional tests. For the ES layer, either run a real local ES instance matching the bundle's supported version, or mock the document manager and assert the query shape. For every new endpoint, write one functional test that hits the route and asserts the JSON contract; this is your safety net when you later patch legacy code.
Day-to-day loop for a new resource:
The release notes tell you nothing, so keep assuming the worst. A 1.0.0 tag with a one-line changelog is not evidence of maintenance. The safe default remains: do not introduce this into a new project, and if you inherit it, plan an exit. Keep your controllers and services as thin adapters so you can replace the bundle with API Platform or plain Symfony controllers without rewriting business logic. Record in your README the exact commit SHA of v1.0.0 you tested against, so the next person knows which "1.0" you mean.
Major-version bumps on unmaintained packages usually mean one of two things, and you should find out which before designing anything: either a maintainer re-tagged historical work with no functional change, or something real changed without a migration guide. Diff the tags (git diff <prev>..v1.0.0 -- composer.json) — that one command resolves it.
Composer will fight you. Expect conflicts between the bundle's pinned symfony/symfony constraint and the rest of your app. Diagnose with:
composer why-not ongr/api-bundle 1.0.0
composer show ongr/api-bundle --all
Options, in order of preference: (1) don't install it; (2) run it in a legacy/isolated app; (3) fork it, bump composer.json, and maintain your fork. Avoid --ignore-platform-reqs in production; it hides real incompatibilities.
PHP 8 breakage is likely, and this tag does not rule it out. Old packages commonly use each(), untyped properties, createMock() signatures that changed, and return types that violate modern interfaces. Run static analysis (phpstan, rector) on the vendored code if you need to keep it alive.
Config keys are not forgiving. Symfony rejects unknown keys at container compile time. Always cross-check against DependencyInjection/Configuration.php; if a key isn't in the tree, the bundle doesn't support it regardless of what a blog post says. If v1.0.0 touched the config tree, re-read it even for keys you already use — a silent rename will fail at compile time with a confusing message. After any config change, clear the cache in the correct environment:
php bin/console cache:clear --env=prod
Service visibility. In Symfony 3.4+ services are private by default, and this bundle was written before that convention settled. If a controller or test cannot fetch a service, check Resources/config/services.yml for public: true, and use debug:container to see the real service ids and aliases:
php bin/console debug:container ongr
Elasticsearch version mismatch is a hard stop. The bundle targets an old ES release. A modern ES 7/8 cluster will reject the client's requests or return incompatible response shapes. Pin the ES server version to whatever ongr/elasticsearch-bundle supports, and record that in your README.
Serialization pitfalls. Lazy-loaded relations, circular references, and DateTime formatting are the usual failure points. Use explicit groups, a custom normalizer if needed, and test the actual JSON output rather than trusting annotations.
Debugging workflow. Use the Symfony profiler for request/service inspection, Xdebug for stepping through controller actions, and ES query logging (enable the ES bundle's logger or a Monolog channel) to see what queries are actually sent. Most "empty response" bugs are query-shape or index-name bugs, not routing bugs.
Extension points. Prefer overriding service definitions in your app's services.yml, decorating services, or subclassing controllers over editing vendor code. If the bundle's classes are final or lack interfaces, fork the one class you need rather than forking the whole bundle. Keep a short PATCHES.md listing every override so the next developer can find them.
Treat the bundle's route file as a contract, not a black box. Copy it into your own app configuration if you need to customize prefixes, requirements, or methods; depending on the vendor file directly makes upgrades — and this is the first real one in a decade — harder to reason about.
How can I help you explore Laravel packages today?