Major overhaul

.gitignore

@@ -5,4 +5,5 @@ composer.lock
 .DS_Store
 Thumbs.db
 /phpunit.xml
-/build
+/build
+/.idea

.travis.yml

@@ -2,9 +2,14 @@ language: php
 php:
   - 7.0
   - 5.6
+
+branches:
+  only:
+  - master
+  - /^v\d+\.\d+(\.\d+)?(-\S*)?$/
 
 before_script:
   - travis_retry composer self-update
   - travis_retry composer install --prefer-source --no-interaction --dev
 
-script: vendor/phpunit/phpunit/phpunit --verbose
+script: vendor/phpunit/phpunit/phpunit --verbose

README.md

@@ -1,6 +1,8 @@
 # Laravel Scout Elasticsearch Driver
 
-[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)
+[![Software License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+[![Travis](https://img.shields.io/travis/thomasjsn/laravel-scout-elastic.svg)](https://travis-ci.org/thomasjsn/laravel-scout-elastic)
+[![Packagist](https://img.shields.io/packagist/v/thomasjsn/laravel-scout-elastic.svg)](https://packagist.org/packages/thomasjsn/laravel-scout-elastic)
 
 This package makes is the [Elasticsearch](https://www.elastic.co/products/elasticsearch) driver for Laravel Scout.
 
@@ -16,7 +18,7 @@ This package makes is the [Elasticsearch](https://www.elastic.co/products/elasti
 You can install the package via composer:
 
 ``` bash
-composer require tamayo/laravel-scout-elastic
+composer require thomasjsn/laravel-scout-elastic
 ```
 
 You must add the Scout service provider and the package service provider in your app.php config:
@@ -31,34 +33,148 @@ You must add the Scout service provider and the package service provider in your
 ],
 ```
 
-### Setting up Elasticsearch configuration
-You must have a Elasticsearch server up and running with the index you want to use created
+Then you should publish the Elasticsearch configuration using the `vendor:publish` Artisan command.
 
-If you need help with this please refer to the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)
+```
+php artisan vendor:publish --provider="ScoutEngines\Elasticsearch\ElasticsearchProvider"
+```
+
+### Setting up Elasticsearch configuration
+You must have a Elasticsearch server up and running, indices can be created with an Artisan command; see below.
 
 After you've published the Laravel Scout package configuration:
 
 ```php
 // config/scout.php
 // Set your driver to elasticsearch
     'driver' => env('SCOUT_DRIVER', 'elasticsearch'),
+```
+
+## Usage
+
+### Creating Elasticsearch indexes with proper mapping
+
+You may define custom mappings for Elasticsearch fields in the config. See examples in the [config file](config/elasticsearch.php).
+If you prefer storing mappings in models, you may create a static public method `mapping()` in each particular model:
+
+```php
+class Article extends Model
+{
+    // ...
+    public static function mapping() {
+        return [
+            'location' => [
+                'type' => 'geo_point'
+            ],
+        ];
+    }
+    // ...
+}
+```
+And then use it in the config file:
+```php
+ 'indices' => [
 
-...
-    'elasticsearch' => [
-        'index' => env('ELASTICSEARCH_INDEX', 'laravel'),
-        'hosts' => [
-            env('ELASTICSEARCH_HOST', 'http://localhost'),
+    'realestate' => [
+        'settings' => [
+            "number_of_shards" => 1,
+            "number_of_replicas" => 0,
+        ],
+        'mappings' => [
+            'articles' => \App\Article::mapping(),
         ],
     ],
-...
+ ]
 ```
+The document type, in this example `articles` must match `searchableAs()` for the respective model.
 
-## Usage
+Elasticsearch can set default types to model fields on the first insert if you do not explicitly define them. 
+However; sometimes the defaults are not what you're looking for, or you need to define additional mapping properties.
+
+In that case, we strongly recommend creating indices with proper mappings before inserting any data.
+For that purpose, there is an Artisan command, called `elastic:make-indices {index}` which creates an index based on
+the settings in your configuration file.
+
+To create all indices from your config just ignore the `{index}` parameter and run:
+
+```
+php artisan elastic:make-indices
+```
+
+If the index exists you will be asked if you want to delete and recreate it, or you can use the `--force` flag.
+
+To get information about your existing Elasticsearch indices you may want to use the following command:
+
+```
+php artisan elastic:indices
+```
+
+### Indexing data
+
+You may follow instructions from the [official Laravel Scout documentation](https://laravel.com/docs/5.3/scout)
+to index your data.
+
+### Search
+
+The package supports everything that is provided by Laravel Scout.
+
+The Scout `search` method used the default query method defined in the config file.
+
+Sorting with `orderBy()` method:
+
+```php
+$articles = Article::search($keywords)
+            ->orderBy('id', 'desc')
+            ->get();
+```
+
+#### Elastic specific
+
+However, to use the extra Elasticsearch features included in this package, use trait `ElasticSearchable` 
+by adding it to your model instead of `Searchable`:
+
+```php
+class Article extends Model
+{
+    // use Searchable;
+    use ElasticSearchable;
+    // ...
+}
+```
+
+The package features:
+
+1) The `elasticSearch` method, `elasticSearch($method, $query, array $params = null)`:
+
+```php
+$articles = Article::elasticSearch('multi_match', $q, [
+    'fields' => ['title', 'content', 'tags'],
+    'fuzziness' => 'auto',
+    'prefix_length' => 2,
+    'operator' => 'AND'
+])->get();
+```
+
+Parameters are taken from the configuration, for the specific query method, if not supplied. But you may override them.
+
+2) A separate Elasticsearch index for each model.
+
+If you have defined several indices in your [config file](config/elasticsearch.php), 
+you may choose which index a model belongs to by overriding `searchableWithin()` method in your model:
+
+```php
+public function searchableWithin()
+{
+    return 'foobar';
+}
+```
+
+If you do not override `searchableWithin()` in your model, the first index from the config will be used.
 
-Now you can use Laravel Scout as described in the [official documentation](https://laravel.com/docs/5.3/scout)
 ## Credits
 
 - [Erick Tamayo](https://github.com/ericktamayo)
+- [Thomas Jensen](https://github.com/thomasjsn)
 - [All Contributors](../../contributors)
 
 ## License

composer.json

@@ -1,6 +1,8 @@
 {
-    "name": "tamayo/laravel-scout-elastic",
+    "name": "thomasjsn/laravel-scout-elastic",
     "description": "Elastic Driver for Laravel Scout",
+    "homepage": "https://github.com/thomasjsn/laravel-scout-elastic",
+    "license": "MIT",
     "keywords": ["laravel", "scout", "elasticsearch", "elastic"],
     "require": {
         "php": ">=5.6.4",

config/elasticsearch.php

@@ -0,0 +1,93 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Elasticsearch host
+    |--------------------------------------------------------------------------
+    |
+    | Your Elasticsearch servers go here, by default it will use localhost. But
+    | you can change that here or in your environment file.
+    */
+
+    'hosts' => [
+        env('ELASTICSEARCH_HOST', 'http://localhost'),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Queries and query parameters
+    |--------------------------------------------------------------------------
+    |
+    | Here you can specify different search methods, and their parameters.
+    | The scout "search" method uses the default query type, with its parameters.
+    | If you use the "elasticSearch" method you can specify the query type and
+    | override the search parameters when performing the search.
+    |
+    */
+
+    'queries' => [
+        'default' => 'query_string',
+
+        'query_string' => [
+            'default_operator' => "AND"
+        ],
+        'multi_match' => [
+            'fields' => '_all',
+            'fuzziness' => 'auto'
+        ]
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Elasticsearch indices
+    |--------------------------------------------------------------------------
+    |
+    | Here you can define your indices, with separate settings and mappings.
+    | You can choose which index a model belongs to my overriding the
+    | searchableWithin() method. A model will, by default, belong to the first
+    | index listed here.
+    |
+    | You may specify your mappings in the model if you like that approach,
+    | just make a static method, e.g. mapping() and refer to it here, like:
+    |
+    | 'mappings' => [
+    |     'articles' => \App\Article::mapping()
+    | ]
+    |
+    */
+
+    'indices' => [
+
+        'laravel' => [
+            'settings' => [
+                "number_of_shards" => 1,
+                "number_of_replicas" => 0,
+            ],
+            'mappings' => [
+                'articles' => [
+                    'title' => [
+                        'type' => 'string'
+                    ]
+                ]
+            ]
+        ],
+
+        'another_index' => [
+            'settings' => [
+                "number_of_shards" => 1,
+                "number_of_replicas" => 0,
+            ],
+            'mappings' => [
+                'articles' => [
+                    'title' => [
+                        'type' => 'string'
+                    ]
+                ]
+            ]
+        ]
+
+    ]
+
+];

src/Console/ElasticIndicesCommand.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace ScoutEngines\Elasticsearch\Console;
+
+use Elasticsearch\ClientBuilder;
+use Illuminate\Console\Command;
+
+class ElasticIndicesCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'elastic:indices';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Show Elasticsearch indices (cat command)';
+
+    /**
+     * Create a new command instance.
+     *
+     * @return void
+     */
+    public function __construct()
+    {
+        parent::__construct();
+    }
+
+    /**
+     * Execute the console command.
+     *
+     * @return mixed
+     */
+    public function handle()
+    {
+        $host = config('elasticsearch.hosts');
+
+        $client = ClientBuilder::create()->setHosts($host)->build();
+
+        $indices = $client->cat()->indices();
+
+        if(count($indices) > 0) {
+            $headers = array_keys(current($indices));
+            $this->table($headers, $indices);
+        } else {
+            $this->warn('No indices found.');
+        }
+
+    }
+
+}