# Laravel package
`datalumo/laravel` connects your Laravel app to Datalumo. Add a trait to a model and it stays in sync, search it from PHP and get Eloquent models back, and drop the search or chat widget into a Blade view.
If you have used Laravel Scout, this will feel familiar.
Requirements: PHP 8.2 or newer, Laravel 11 or 12.
## Install
```bash
composer require datalumo/laravel
php artisan datalumo:install
```
`datalumo:install` publishes the config file and, once your credentials are set, checks them for you. It prints the organisation it reached, the permissions on your API key, and the sources you can write to, and it warns when something is missing.
## Configure
In Datalumo, create a **source** of type *API* and an **API key** (see [Authentication](/docs/authentication)). Then fill in your `.env`:
```env
DATALUMO_ORG=your-organisation-id
DATALUMO_TOKEN=your-api-key
DATALUMO_SOURCE=docs
DATALUMO_SEARCH_WIDGET={organisation-id}/{search-widget-id}
DATALUMO_CHAT_WIDGET={organisation-id}/{chat-widget-id}
```
`DATALUMO_ORG` is your organisation's id, not its name. `DATALUMO_SOURCE` is the slug of the source your models are pushed into.
Search and chat are separate widgets in Datalumo, so set the one (or both) you use. Their keys are safe to render in a page; your API key never leaves the server.
Which permissions your key needs:
| Permission | Needed for |
|---|---|
| `pages.write` | Syncing models, importing, flushing |
| `search` | Searching from PHP with `datalumoSearch()` |
| `pages.read` | Cleaning up orphans with `datalumo:reconcile --prune` |
Self-hosting Datalumo? Point `DATALUMO_BASE_URL` at your own install.
## Make a model searchable
Add the `Searchable` trait and describe what should be indexed:
```php
use Datalumo\Laravel\Searchable;
use Illuminate\Database\Eloquent\Model;
class Article extends Model
{
use Searchable;
public function toDatalumoArray(): array
{
return [
'external_id' => (string) $this->getKey(),
'name' => $this->title,
'content' => $this->body,
'content_mime' => 'text/markdown',
'source_url' => route('articles.show', $this),
'meta' => ['author' => $this->author->name],
];
}
}
```
| Field | What it is |
|---|---|
| `external_id` | Your own id for the record. Defaults to the primary key, and is what makes a re-sync update instead of duplicate. |
| `name` | Title shown in results |
| `content` | The text to index |
| `content_mime` | `text/plain`, `text/markdown`, or `text/html` |
| `source_url` | Where the result links to |
| `meta` | Anything else you want stored with the page |
That is all the setup. From here on, saving a model pushes it and deleting one removes it. The work is queued by default, so requests never wait on the API. Set `DATALUMO_QUEUE=false` to run it inline (handy in tests and small apps).
### Only index some records
```php
public function shouldBeSearchable(): bool
{
return $this->published_at !== null;
}
```
Unpublish an article and it is removed from Datalumo on the next save. Soft deleted models are removed too, and come back when restored.
### Sync by hand
```php
$article->searchable(); // push this one
$article->unsearchable(); // remove this one
Article::where('type', 'guide')->get()->searchable();
```
### More than one model
Point each model at its own source, either in `config/datalumo.php`:
```php
'model_sources' => [
\App\Models\Article::class => 'articles',
\App\Models\Product::class => 'products',
],
```
or by overriding `datalumoSource()` on the model. Anything not listed uses `DATALUMO_SOURCE`.
## Import what you already have
```bash
php artisan datalumo:import "App\Models\Article"
```
Rows are pushed in batches of 50. Remember that pushing is not indexing: Datalumo reads and embeds everything it received afterwards, so a large import keeps making progress on the source page in your dashboard after the command finishes.
Two more commands for keeping things tidy:
```bash
# Push only what changed since last time
php artisan datalumo:reconcile "App\Models\Article"
# See what would happen, without writing anything
php artisan datalumo:reconcile "App\Models\Article" --dry-run
# Also delete pages whose model is gone
php artisan datalumo:reconcile "App\Models\Article" --prune
# Remove every page for a model
php artisan datalumo:flush "App\Models\Article"
```
Reconcile remembers a fingerprint of each record, so a second run pushes almost nothing. Pass `--force` to push everything again. Only use `--prune` on a source that nothing else writes to, since it deletes anything it does not recognise.
## Search from PHP
```php
$articles = Article::datalumoSearch('how to deploy')->get();
```
You get an Eloquent collection back, in Datalumo's relevance order, loaded from your own database. Everything you normally do with models still works: relationships, accessors, policies, your Blade partials.
```php
Article::datalumoSearch('refund policy')
->where('author', 'jane') // match on meta you sent
->limit(10)
->get();
// Simple pagination
$results = Article::datalumoSearch($request->input('q'))->paginate(15);
// The raw response, with snippets and scores
$result = Article::datalumoSearch('refunds')->raw();
$result->sessionId; // pass this to the analytics component
$result->data[0]->name;
$result->data[0]->snippet;
$result->data[0]->score;
```
Search goes through your search widget, so the key must be set and the widget must cover the sources your models live in.
## Blade components
```blade
```
Add the stack once in your layout, just before ``:
```blade
@stack('datalumo-scripts')
```
Both components use the widget keys from your config, and accept a `widget` attribute when one page needs a different one:
```blade