README

Combines Elasticsearcher with PHP League's Fractal package for easier document management.

This package is compliant with PSR-1, PSR-2, PSR-4 and PSR-11. If you notice compliance oversights, please send a patch via pull request.

Install

Via Composer

$ composer require yucadoo/elasticsearcher-fractal

Usage

This package provides the YucaDoo\ElasticSearcher\Managers\DocumentManager class which can be used instead of the original ElasticSearcher\Managers\DocumentsManager class. It actually wraps the original manager, providing the same functionality in a more reusable and object friendly way.

The original document manager handles raw documents, which are arrays. You always have to specify the Elasticsearch index name and id alongside the document. The new document manager is capable of taking any type of input, for example database models. The Elasticsearch index name and id are determined by the given input, while PHP League's Fractal package is used to convert the input to a document. If you like what you see below, this package is what you were looking for!

<?php

use App\Models\User;

// Implementation of the functions createWrappedDocumentManager() and createNewDocumentManager() is discussed later.
// $originalDocumentManager = createWrappedDocumentManager();
$newDocumentManager = createNewDocumentManager($frameworkContainer);

$user = new User(['id' => 123, 'name' => 'Administrator']);

// Move transformation to fractal transformer
// $data = ['id' => $user->id, 'name' => $user->name];

// $originalDocumentManager->index('users', '_doc', $data);
$newDocumentManager->create($user);
//$originalDocumentManager->bulkIndex('users', '_doc', [$data, $data, $data]);
$newDocumentManager->bulkCreate([$user, $user, $user]);
//$originalDocumentManager->update('users', '_doc', 123, ['name' => 'Moderator']);
$user->name = 'Moderator';
$newDocumentManager->update($user);
//$originalDocumentManager->updateOrIndex('users', '_doc', 123, ['name' => 'Super User']);
$user->name = 'Super User';
$newDocumentManager->updateOrCreate($user);
//$originalDocumentManager->delete('users', '_doc', 123);
$newDocumentManager->delete($user);
//$originalDocumentManager->exists('users', '_doc', 123);
$newDocumentManager->exists($user);
//$originalDocumentManager->get('users', '_doc', 123);
$newDocumentManager->get($user);

The new document manager requires an adapter, which extends the YucaDoo\ElasticSearcher\Managers\DocumentAdapter interface. The adapter is used to obtain the Elasticsearch index name and id. Below is a sample implementation for Eloquent models.

<?php

namespace App\ElasticSearcher;

use YucaDoo\ElasticSearcher\Managers\DocumentAdapter;

class EloquentDocumentAdapter implements DocumentAdapter {
    /**
     * Get Elasticsearch id for Eloquent model.
     * @param \Illuminate\Database\Eloquent\Model $item Eloquent model.
     * @return string|int Elasticsearch id.
     */
    public function getId($item)
    {
        return $item->getKey();
    }

    /**
     * Get index name for Eloquent model.
     * @param \Illuminate\Database\Eloquent\Model $item Eloquent model.
     * @return string Elasticsearch index name.
     */
    function getIndexName($item): string
    {
        // Elasticsearch index has the same name as database table.
        return $item->getTable();
    }
}

Then implement the transformers for Elasticsearch. An example is given below.

<?php

namespace App\ElasticSearcher\Transformers;

use App\Models\User;
use League\Fractal\TransformerAbstract;

class UserElasticsearchTransformer extends TransformerAbstract
{
    /**
     * Transform user into Elasticsearch document.
     *
     * @param User $user User to be converted into Elasticsearch document.
     * @return array Generated Elasticsearch document.
     */
    public function transform(User $user)
    {
        return [
            'id' => $user->id,
            'name' => $user->name,
        ];
    }
}

It's time now to put things together. To do so we need a PSR-11 compatible container, which exists in most modern PHP frameworks. Most containers return an instance of the class when given the full class name.

The document manager needs the container to obtain the transformer instance to be used for the handled input. When handling a User a UserElasticsearchTransformer instance is needed, when handling a Post model the PostElasticsearchTransformer instance is needed, and so on. The document manager doesn't know the class name of the transformer. The container is expect to resolve the transformer based on the index name. To do so the AliasContainer can be used (version 2.0 or later).

I also recommend using the SingletonContainer to cache the resolved transformers.

First add the packages.

$ composer require mouf/alias-container yucadoo/singleton-container

Then compose the new document manager using the AliasContainer.

<?php

use App\ElasticSearcher\EloquentDocumentAdapter;
use App\ElasticSearcher\Transformers\PostElasticsearchTransformer;
use App\ElasticSearcher\Transformers\UserElasticsearchTransformer;
use ElasticSearcher\Environment;
use ElasticSearcher\ElasticSearcher;
use ElasticSearcher\Managers\DocumentsManager as WrappedDocumentManager;
use League\Fractal\Manager as FractalManager;
use Mouf\AliasContainer\AliasContainer;
use Psr\Container\ContainerInterface;
use YucaDoo\ElasticSearcher\Managers\DocumentManager;
use YucaDoo\SingletonContainer\SingletonContainer;

/**
 * Resolve old document manager. This function is shown for completeness.
 * @return WrappedDocumentManager Document manager handling raw documents.
 */
function createWrappedDocumentManager(): WrappedDocumentManager
{
    $env = new Environment(
      ['hosts' => ['localhost:9200']]
    );
    $searcher = new ElasticSearcher($env);
    return $searcher->documentsManager();
}

/**
 * Resolve new document manager.
 * @param ContainerInterface $container Container providing transformer instances.
 * @return DocumentManager Document manager handling models instead of raw documents.
 */
function createNewDocumentManager(ContainerInterface $container): DocumentManager
{
    // Wrap container with singleton container to cache resolved transformers.
    $singletonContainer = new SingletonContainer($container);
    // Map index names to transformers.
    $transformerRepository = new AliasContainer($singletonContainer, [
        'posts' => PostElasticsearchTransformer::class,
        'users' => UserElasticsearchTransformer::class,
    ]);

    // Compose document manager.
    return new DocumentManager(
        createWrappedDocumentManager(),
        new FractalManager(),
        new EloquentDocumentAdapter(),
        $transformerRepository
    );
}

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email hrcajuka@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

yucadoo / elasticsearcher-fractal

Maintainers

Details