Solr Bundle Laravel Package

Getting Started

1. Install via Composer and confirm it actually resolves against your Symfony version:

   composer require zicht/solr-bundle
   

   Before committing, inspect composer.json in the package — with a 0-star, 0-dependent package the constraints are the first thing to break on modern Symfony installs. If it only supports older symfony/framework-bundle versions, you may need --ignore-platform-reqs or an override in extra.symfony.require, and that is your signal to evaluate a fork.

2. Register the bundle the Symfony way for your version:

   • Symfony 4/5: add Zicht\SolrBundle\ZichtSolrBundle::class => ['all' => true] to config/bundles.php.
   • Older Symfony: register in app/AppKernel.php. Confirm the exact namespace by looking at the package's src/ and *Bundle.php file — Zicht packages have historically used the Zicht\…Bundle convention, but verify rather than assume.

3. Configure the connection in config/packages/zicht_solr.yaml (or .yml in legacy app/config/). Look first at the bundle's DependencyInjection/Configuration.php — it is the authoritative source of every config key. Expect the usual Solr connection shape:

   zicht_solr:
       host: '%env(SOLR_HOST)%'
       port: 8983
       path: /solr
       core: my_core
       timeout: 5
   

   Copy the keys verbatim from Configuration.php; guessing at names will silently produce an unconfigured client.

4. First use case: index something, then query it. Before touching your domain models, prove the wiring works end-to-end:

   • Run the bundle's console commands (bin/console list solr / list zicht:solr) to see what ships out of the box — reindex, ping, or ping-like utilities are common.
   • Inject the Solr client service (name it from bin/console debug:container --tag= or by grepping the bundle's Resources/config/services.xml for the alias) into a scratch command or test.
   • Issue a trivial *:* query and dump the result. If you get documents back, the connection, core, and auth are correct; everything after that is schema work.

5. Read these files first, in this order: README.md → DependencyInjection/Configuration.php → Resources/config/services.* → src/. Given the sparse documentation surface for this package, the DI configuration and service definitions are the documentation.

Implementation Patterns

Wrap the client behind your own service. Do not scatter the bundle's client through controller and repository code. Define an application-level SearchService that composes the bundle client, owns query construction, and normalizes results into your domain objects. This is the single most valuable pattern with a low-maintenance dependency: it confines your exposure to the package's API to one or two classes, so a fork or replacement stays a contained change.

Index writes via domain events, not inline calls. Rather than calling Solr from your entity lifecycle directly, dispatch a domain event (or a Symfony event via Doctrine listeners) on create/update/delete and let a dedicated indexer subscriber translate the entity into a Solr document. This keeps transactional code clean, lets you batch, and — critically — makes indexing fail softly: a Solr outage should not roll back a database write. Queue the index operation with Symfony Messenger if you already have a worker; the bundle will not do this for you.

Full reindex as a console command. Implement your own app:solr:reindex command that paginates the Doctrine query, builds documents, and pushes in batches (a few hundred per request). Rely on the bundle for the client only; the orchestration and batch sizing are yours. This command is what you run after every schema or mapping change, so build it early and make it idempotent.

Explicit document mapping. Write a dedicated mapper class per indexable entity (Product::toSolrDocument() or a separate ProductDocumentMapper) rather than relying on automatic serialization. Explicit maps survive refactors, make field-name typos a compile-time-ish problem, and are the artifact you diff against schema.xml.

Integration tip — keep queries declarative. Centralize query building (filters, boosting, facets, sorting) in query-object or repository classes. The bundle likely exposes a low-level query API; wrapping it means you can unit-test query shape by asserting on the generated string/structure without a live Solr instance.

Testing. Point integration tests at a real Solr in CI (container or embedded) — mocking the client tends to hide schema mismatches and commit-visibility bugs, which are the two failure modes that actually bite.

Gotchas and Tips

• Maintenance risk is the headline gotcha. Zero stars and zero dependents means essentially no community canary for breakage. Pin the exact version in composer.lock, and when it breaks against a Symfony upgrade, be prepared to vendor a fork (repositories: { type: vcs }) or drop the dependency. Budget for this at adoption time, not at upgrade time.

• Schema drift is silent. The bundle can send documents all day without error if your fields do not match schema.xml — depending on Solr's configuration, unknown fields either error or are dropped. Validate your mapping against a checked-in schema.xml (or managed-schema) kept in the repo, and assert field names in a test.

• Commit vs. soft commit. Writes are not visible until a commit. If "I indexed it but search returns nothing" appears in testing, it is almost always the commit policy, not your code. Check the bundle's commit behavior and any auto-commit interval in solrconfig.xml; do not add hard commits per document in production.

• Config key guessing wastes hours. The bundle will not warn you about unknown config keys in older Symfony versions. If the client is silently unconfigured, re-read Configuration.php and run bin/console debug:config zicht_solr.

• Service visibility and version skew. Older Zicht bundles define services as public in XML; newer Symfony deprecates that and will drop them into debug:container --show-private. Grep Resources/config/ when an injection "should work" but the alias doesn't exist.

• Extension points: prefer overriding service definitions in your app's services.yaml (alias substitution, decorator) and compiler passes over editing vendor code. This is the practical insurance policy for an unsupported package — a decorator around the client lets you swap it later without touching call sites.

• Debugging: the Solr admin UI (/solr/<core>/select?q=*:*&wt=json) is a faster oracle than the bundle for distinguishing "my app sent nothing" from "Solr indexed nothing." Compare its document count against your database count after every reindex.

• Check for abandoned dependencies. Inspect the lockfile for the Solr HTTP client the bundle pulls in; if it is an unmaintained library, your real maintenance exposure is larger than the bundle itself.