Artisan Commands

CLI tools for managing your Elasticsearch connection, indices, and models. Inspect cluster health, list indices, show mappings, scaffold models, and safely re-index with updated mappings.

All commands that interact with Elasticsearch support the --connection= option for non-default connections.

elastic:status

Version 5.5+

Connection health check with cluster info and license details.

php artisan elastic:status

Displays connection configuration (host, auth type, index prefix), cluster info (name, UUID, version), and license status.

# With a named connection
php artisan elastic:status --connection=my_es_connection

elastic:indices

Version 5.5+

List all Elasticsearch indices with health, document count, and store size.

php artisan elastic:indices

By default, only indices matching your configured prefix are shown. Health is color-coded: green, yellow, or red.

# Show all indices on the cluster, not just prefixed ones
php artisan elastic:indices --all

elastic:show

Version 5.5+

Inspect a specific index: overview, field mappings, settings, and analysis config.

php artisan elastic:show {index}

php artisan elastic:show user_logs

Displays:

Overview — UUID, document count, deleted docs, store size, status, health
Mappings — all fields with types, sub-fields indented (e.g., name.keyword)
Settings — shards, replicas, creation date
Analysis — custom analyzers, filters, and normalizers (if configured)

elastic:make

Version 5.5+

Scaffold a new Elasticsearch model with the correct base class and connection.

php artisan elastic:make {name}

php artisan elastic:make UserLog

This generates app/Models/UserLog.php:

class UserLog extends Eloquent
{
    protected $connection = 'elasticsearch';

    public $timestamps = true;

    public static function mappingDefinition(Blueprint $index): void
    {
        $index->date('updated_at');
        $index->date('created_at');
    }
}

Supports subdirectories:

php artisan elastic:make ES/UserLog
# Creates app/Models/ES/UserLog.php with namespace App\Models\ES

elastic:re-index

Version 5.5+

Safely re-index an Elasticsearch index with updated field mappings. This automates the manual re-indexing process described in the Re-indexing guide with built-in verification, rollback, and resume capability.

php artisan elastic:re-index {model}

Prerequisites

Your model must define a mappingDefinition() method that declares the desired field mappings:

use PDPhilip\Elasticsearch\Schema\Blueprint;

class UserLog extends Eloquent
{
    protected $connection = 'elasticsearch';

    public static function mappingDefinition(Blueprint $index): void
    {
        $index->keyword('status');
        $index->text('title', hasKeyword: true);
        $index->geoPoint('location');
        $index->date('created_at');
    }
}

Usage

Pass the model class name — short names, App\Models\ prefixed, or fully qualified:

php artisan elastic:re-index UserLog
php artisan elastic:re-index "App\Models\ES\UserLog"

How it works

The command runs a 9-phase process with confirmation prompts between each phase:

Validate — Checks the index exists, counts documents, and compares current mappings against your mappingDefinition(). Shows which fields need updating and which fields exist in the index but aren’t defined in the model.
Create Temp Index — Creates {index}_temp with the new mapping from your model.
Copy to Temp — Uses the Elasticsearch reindex API to copy all documents from the original index to the temp index.
Verify Temp — Compares document counts between original and temp (within configurable tolerance).
Drop Original — Drops the original index. This is the danger zone — a dedicated confirmation prompt warns you before proceeding.
Create Original — Recreates the original index with the new mapping.
Copy Back — Copies documents from temp back to the original. Retries automatically on failure (configurable max retries).
Verify Final — Confirms the final document count matches. Runs a catch-up reindex if needed.
Cleanup — Drops the temp index.

Options

# Skip all confirmation prompts
php artisan elastic:re-index UserLog --force

Before the process starts, you can edit the tolerance (default 0.1%) and max retries (default 3) interactively.

Mapping analysis

The command detects both type mismatches and sub-field changes. For example, changing a field from keyword to text, or adding a keyword sub-field with hasKeyword: true, will both be detected:

Fields to Update
  device_type      text → text [+keyword]
  location         text → geo_point

Unmapped Fields
  browser_version  keyword
  raw_data         object

Fields to Update shows fields where the current mapping differs from your mappingDefinition(). Unmapped Fields shows fields that exist in the index but aren’t declared in the model — these are left as-is and carried over during re-indexing.

Resume capability

If the process is interrupted, running the command again will detect the state and resume from the appropriate phase:

Temp index exists with matching data → resumes at verification
Original missing, temp has data → resumes in the danger zone (temp is treated as source of truth)
Partial or empty temp → drops it and starts fresh