Index Bundle Laravel Package

Getting Started

• Know what you're installing. sitepark/atoolo-index-bundle is a Symfony bundle from the Sitepark atoolo stack, not a Laravel package. There is no service provider, no facade, no config/index.php. You will either run it in a Symfony service alongside Laravel, or hand-wire its services into Laravel's container.
• Install: composer require sitepark/atoolo-index-bundle:^1.0. 1.0.0 is the first stable tag — pin the major, and check composer.json for symfony/* and PHP constraints before committing. Dependency conflicts remain the most common first blocker.
• Look at src/ before any docs. Grep for Interface to find the contracts (indexer, backend, document/resource abstractions). With zero stars and zero dependents, the test suite is the de facto documentation — read tests/ next, and note that 1.0.0 explicitly added coverage for console command failure and selection paths, so those tests now describe real edge-case behaviour.
• Verify what "backend agnostic" means in practice. The bundle ships the indexing core/pipeline; you supply or select the backend. Do not expect an Elasticsearch or Solr client to come for free.
• First use case: wire an in-memory/array-backed test backend, take one Eloquent model, map it to a document, and push it through the indexer from php artisan tinker. That single round-trip teaches you the contracts faster than any README.
• Minimal Laravel bridge: a dedicated AtooloServiceProvider that binds the indexer and backend interfaces to concrete classes, plus manual registration of any bundle service definitions you actually need — and, as of 1.0.0, explicit "which indexer is configured" wiring (see Gotchas).

Implementation Patterns

• Model → document mapping. Implement the bundle's document/resource contract per indexable entity in a dedicated class (App\Indexing\PostDocument), not a trait on the model. The indexer contract will outlive your Eloquent schema.
• Don't assume a field bag. 1.0.0 removed the assumption that an index document "has fields." If you were building documents as setFields([...])-style maps or reading a generic field collection back out of the contract, re-check the interface after upgrading and model your own typed properties instead. Assume nothing about document shape beyond what the contract guarantees.
• Stable document IDs. Use {model}:{id} or a ULID. Reindexing must be idempotent; an upsert is only an upsert if the core can trust the key you give it.
• Event-driven indexing. Hook saved/deleted model events and dispatch a job. Never index synchronously in the request — the pipeline is built for batch work and will add latency you don't want.
• One job per document, batches for rebuilds. Per-document jobs keep retries granular. A php artisan search:reindex command should iterate with chunking and go through the same indexer service, not a parallel code path.
• The backend adapter is the seam. Implement the backend interface once and keep it thin: translate the bundle's document representation into your engine's payload. All engine-specific quirks (analyzers, mappings, refresh intervals) live here and nowhere else.
• Composition over container archaeology. Resolve the indexer via app(IndexerInterface::class) inside jobs; avoid static access so you can swap a fake backend in tests.
• Test with a fake backend. Unit-test document mappers in isolation; feature-test the pipeline against an in-memory backend. Assert on the documents handed to the backend, not on engine state.
• Separate "what to index" from "where to index." Resource loaders decide what; backends decide where. Keeping these apart is what makes a reindex into a new engine a config change instead of a rewrite.
• Expect a console surface. 1.0.0 hardened the failure and selection paths of the bundle's console commands, which tells you indexing is intended to be driven from the CLI. In Laravel, either invoke the Symfony commands from your own artisan command or shell out to a small Symfony console entrypoint — don't reimplement the selection logic, or you'll drift from bug fix b34601d.

Gotchas and Tips

• Indexer selection is CMS-driven, and now strictly so. 1.0.0's headline fix means the bundle only offers an indexer that "the CMS has configured." In Symfony the CMS supplies that config; in Laravel nobody does. If you don't explicitly provide the same configuration, you get no indexer offered rather than a sensible default — which surfaces as a silent no-op, not an exception. Wire this in your service provider and assert it in a test.
• Symfony bundle mechanics don't apply. config/packages/*.yaml, autoconfiguration, and tagged services do nothing in Laravel. Any bundle-provided defaults must be re-declared by hand — budget for that.
• Still zero adoption. 1.0.0 is a stability signal, not a popularity one: no issues to search, no blog posts, no Stack Overflow answers, one maintainer. Read the source and pin the exact version (or commit) in composer.json.
• The document contract changed under you. The 1.0.0 refactor is not purely cosmetic — code written against pre-1.0 documents that assumed a fields collection needs revisiting. Upgrade deliberately, and diff the interface before assuming your mapper still compiles semantically.
• "Backend agnostic" ≠ batteries included. The core indexes into an abstraction. If no adapter matches your engine, you are writing one — scope that as real work, not glue.
• Transitive Sitepark coupling. atoolo packages tend to depend on sibling atoolo packages (common, etc.). Run composer why and confirm you aren't pulling a version graph that conflicts with your Symfony components.
• Serialization assumptions. Documents crossing a queue boundary get serialized. Check whether the document contract is JSON-serializable; if it holds closures, resources, or models, wrap it in a plain DTO before dispatching. This matters more now that documents aren't generic field bags — custom properties must be serializable by construction.
• Debugging. In Symfony, use the profiler and debug:container. In Laravel, log the exact document payload at the backend boundary — that's where mapper/engine mismatches surface. When nothing indexes at all, check indexer selection first, not your mapper.
• Extension points worth knowing: custom resource loaders (what gets indexed), document factories (how models become documents), backend implementations (where it lands), indexer selection/config, and any indexer events for pre/post hooks. Prefer these over forking.
• Partial failures are usually silent. Wrap batch runs in per-document try/catch with structured logging, and record failures so a reindex can retry only what failed. 1.0.0 added test coverage for command failure paths — mirror that discipline in your own reindex command.
• Consider a thin Symfony sidecar if the bridge fights you: run the bundle in a small Symfony app (where CMS-style indexer configuration is natural), expose an HTTP endpoint, and let Laravel call it. More moving parts, far less container archaeology.