Statamic Loupe Laravel Package

Getting Started

1. Install and configure
   composer require <package> then publish the config (php artisan vendor:publish --tag=<package>-config). Set your search backend connection (e.g. Elasticsearch/Meilisearch/Algolia) and index prefix in .env or config/<package>.php.

2. Make a model searchable
   Add the package’s Searchable trait to the Eloquent model. If the model uses a non‑id primary key, set the package’s key name method (e.g. getScoutKeyName() or equivalent) so 4.2.0’s consistent primary-key handling kicks in.

3. Create the index and import
   Run the package’s index-creation command (e.g. php artisan search:index / scout:index) and then import existing records (php artisan search:import or a custom batch command).

4. First use case
   Perform a basic search from a controller: Model::search('term')->get(). Confirm results come back and that the index is queryable while a reimport is running — 4.2.0 keeps the index searchable during updates, so you can reindex in the background without taking search offline.

Implementation Patterns

• Observer-driven sync
  Let the package’s model observers push create/update/delete events to the search index. Keep writes synchronous only for low-volume models; use the package’s queue option for high-traffic models to avoid request latency.

• Zero‑downtime reindex (4.2.0)
  Use the package’s alias/swap flow: build a new concrete index, import data, then atomically point the read alias to the new index. Because 4.2.0 keeps the index searchable while it is being updated, you can run a full reimport without a maintenance window. Day-to-day, schedule reindexes during low traffic and monitor alias swap completion.

• Custom primary keys
  4.2.0 makes the configured primary key consistent across indexing and retrieval. For models with UUIDs or composite-ish keys, explicitly set the key name in the model and verify that search results hydrate correctly (Model::find($hit->id) should use the same key). Avoid assumptions about id in custom result mapping.

• Batch imports and chunking
  Use chunkById (with your configured key) or the package’s batch import command. This pairs well with the new primary-key consistency: chunking by the correct key prevents skipped or duplicated records during large imports.

• Integration tips

  • Wrap search calls behind a repository or scope so you can swap drivers in tests.
  • Use the package’s fake/Null driver in tests to assert searchable behaviour without a live backend.
  • Keep index names environment-specific (app_production_users, app_staging_users) to avoid cross-environment contamination.
  • If you use Laravel Horizon or queues, ensure index jobs run on a queue that is restarted after config changes.

Gotchas and Tips

• Primary key mismatch
  The most common failure is a model whose getKeyName() differs from the package’s configured key. After upgrading to 4.2.0, re-check models with custom keys — the package now uses the configured key consistently, but your code must configure it correctly. Search hits may return the wrong record if the key mapping is off.

• Alias vs concrete index
  When using zero‑downtime reindexing, always query the alias, never the concrete index. Querying a concrete index during a swap can return stale or partial results. Confirm your package config points reads at the alias and writes at the active concrete index.

• Queue workers and config cache
  After changing index names, keys, or queue settings, run php artisan config:clear and restart queue workers. Cached config can silently keep old index names, causing writes to the wrong index.

• Searchable during update ≠ fully consistent
  4.2.0 keeps the index searchable while updating, but reads may briefly hit the old index until the swap completes. Design for eventual consistency: avoid read-after-write assertions in the same request unless you force a refresh or use synchronous indexing.

• Debugging tips

  • Inspect the raw index (via the backend’s CLI/API) to confirm documents and key fields.
  • Enable the package’s debug logging to see indexing payloads and alias operations.
  • Use the package’s index status command to check alias targets and document counts.
  • If search returns nothing after a reindex, verify the alias points at the new index and that the primary key field matches your model’s configured key.

• Extension points
  Most packages allow customising the searchable array, index settings (analyzers, mappings), and the engine/connection. Use these to add fields for filtering and to keep index settings under version control. When overriding the searchable payload, always include the configured primary key so result hydration remains reliable.