Search Bundle Laravel Package

Getting Started

This bundle is an archived Symfony 2-era extension of nelmio/solarium-bundle. Before writing any code, confirm your platform still matches:

1. Verify constraints before installing. Check the archived composer.json for symfony/symfony and nelmio/solarium-bundle version bounds. On anything newer than Symfony 3.x / PHP 7.x you will hit solver conflicts. If you are on a modern stack, do not try to force it — vendor the few classes you actually need or use Solarium directly.
2. Install alongside its parent. You need a running Apache Solr instance, the Solarium PHP client, nelmio/solarium-bundle, and then this bundle. The Nelmio bundle does the client/config plumbing (solarium.client service, config.yml endpoints and cores); rz/search-bundle layers search/index abstractions on top of that service.
3. Where to look first. In the repo, read in this order: Resources/config/services.xml (what services it registers and what it decorates), the DependencyInjection/ extension and Configuration.php (the config tree you can set under rz_search:), then Annotation/ or Document/ (how indexable objects are declared), and finally any Command/ folder for reindex utilities. That tells you the intended entry point faster than the README.
4. Register it. Add both bundles to AppKernel::registerBundles() (Nelmio first, this one after), then expose the config:

   # config.yml
   nelmio_solarium:
       endpoints:
           default: { host: '%solr_host%', port: 8983, path: /solr }
       clients:
           default: { endpoints: [default] }
   rz_search:
       # options as declared in Configuration.php
   

5. First use case — index and query one entity. Define a single small document class with whatever mapping attribute/annotation the bundle expects, run the provided reindex console command (or call the indexer service manually), then resolve the bundle's search service from the container in a controller and run a match-all query. Getting one document in and one result back proves the whole chain: Solr core → Nelmio client → this bundle → your code.

Realistically: allocate a timebox to this. Because the package is archived with zero dependents, treat step 1 as a go/no-go decision rather than a formality.

Implementation Patterns

The intended workflow is annotation/config-driven indexing over Solarium, so most day-to-day work happens in three places: your document classes, the indexer service, and thin controller/repository wrappers.

• Document classes as the unit of mapping. Keep one class per Solr document type and keep it dumb — scalar fields, getters, and the mapping metadata. Do not put business logic or entity relationships in it. If you are indexing Doctrine entities, prefer a separate "document" class projected from the entity over annotating the entity itself; that keeps persistence concerns and search concerns separable and lets you change the index schema without migrations.
• Explicit indexing over magic hooks. Wire indexing into the places where state actually changes (a service method, an event listener on postPersist/postUpdate, or a message handler) rather than relying on lifecycle callbacks in the bundle. Explicit calls are easier to test, easier to replay, and avoid indexing inside uncommitted transactions.
• Write a reindex command early. Even if the package ships one, build a thin wrapper that (a) pages through your source data, (b) batches documents (100–500 per Solr request), and (c) supports --commit / full-vs-partial modes. You will use this command constantly during schema changes, and it decouples you from a bundle you may later have to drop.
• Separate read and write paths. Writes go through the indexer service (add/update/delete by id). Reads go through a small repository class that builds Solarium queries and hydrates results. Controllers should call the repository, not the Solarium client, so you can swap the backend and unit-test query construction without a live Solr.
• Compose the parent bundle rather than fight it. Get the solarium.client service injected and use the bundle only for its indexing/mapping layer. Where the bundle's abstraction is thin or wrong for your case, drop to raw Solarium for that one operation — mixing is fine and normal with these wrapper bundles.
• Keep search config in one file. Endpoints, cores, and the bundle's options should live in a single environment-aware config block, with production and test endpoints parameterized (%solr_host%). Give tests their own core or a mocked client so a flaky Solr socket doesn't fail CI.

Gotchas and Tips

• Archived means frozen. No security patches, no compatibility updates, and zero public dependents to learn from. Budget for the possibility that you replace this within a year; keep the coupling surface small (controllers → your repository → bundle).
• Symfony 2 idioms will bite you. Bundle registration, service definitions in XML with %parameter% substitution, and container-aware base classes are all pre-autowiring. If you are on a newer Symfony, expect manual service wiring and possibly a compiler-pass hack for injection.
• Solr version drift is the classic failure. Solarium and the Solr server negotiate schema/response formats loosely. Pin the Solr version in your dev environment (Docker) to whatever the bundle era targets, and pin it in production. Mismatched versions surface as empty result sets or unknown field exceptions rather than clear errors.
• Commit and optimize semantics. Solr is near-real-time at best; documents are not visible until a commit. If "search after save" is a requirement, either use commitWithin or handle the eventual-consistency window in the UI. Reindex commands should commit once at the end, not per document.
• Debugging checklist, in order: (1) is the Solr core reachable — curl http://host:8983/solr/<core>/admin/ping; (2) is the right client/endpoint injected — dump the solarium.client service config; (3) does the raw Solarium query return what the bundle query returns — if yes, the bug is in hydration, if no, it's in query construction; (4) enable Solarium's event dispatcher logging to see the literal query and response. Nine times out of ten it's a mapping or field-name mismatch, not the bundle.
• Field typing traps. Solr field types are defined in schema.xml / managed schema, not in PHP. A "string" field that gets tokenized, or a date format that doesn't match, will silently return nothing. Keep schema and document class changes in the same commit.
• Extension points are your escape hatch. The useful ones are the client service (swap the endpoint or add Solarium plugins) and any hydrator/result-factory the bundle exposes. Custom Solarium plugins (logging, retry, post-big-commit) are the safest place to add behavior without patching vendor code.
• Do not nest Solr calls in Doctrine transactions or flush loops — an unavailable Solr will roll back saves you did not expect to roll back. Queue indexing if search is non-critical, or guard it with a feature flag.