PHPackages                             etrepat/compleet - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. etrepat/compleet

ActiveLibrary[Caching](/categories/caching)

etrepat/compleet
================

Redis-backed service for fast autocompleting

1.0.1(11y ago)31.3k21MITPHPPHP >=5.4.0

Since Oct 8Pushed 11y ago2 watchersCompare

[ Source](https://github.com/etrepat/compleet)[ Packagist](https://packagist.org/packages/etrepat/compleet)[ Docs](https://github.com/etrepat/compleet)[ RSS](/packages/etrepat-compleet/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (2)Versions (3)Used By (1)

Compleet
========

[](#compleet)

[![Latest Stable Version](https://camo.githubusercontent.com/9d61672d293f079ba1ded2e42c2c1e7d9af9a41dd227cf29c70f6450beb62215/68747470733a2f2f706f7365722e707567782e6f72672f657472657061742f636f6d706c6565742f762f737461626c652e737667)](https://packagist.org/packages/etrepat/compleet)[![Total Downloads](https://camo.githubusercontent.com/fe1c8a0551846f2ca9cef7aac4d4d5b466f41d3f8e6d7ec94f7eeef3ba69c241/68747470733a2f2f706f7365722e707567782e6f72672f657472657061742f636f6d706c6565742f646f776e6c6f6164732e737667)](https://packagist.org/packages/etrepat/compleet)[![License](https://camo.githubusercontent.com/dea5be06e07fb4587a114dfd9ac1e028e104a2ef6d64f1a4bd30813425ed790d/68747470733a2f2f706f7365722e707567782e6f72672f657472657061742f636f6d706c6565742f6c6963656e73652e737667)](https://packagist.org/packages/etrepat/compleet)[![Build Status](https://camo.githubusercontent.com/5e5eab767428212c8f475f7ef452605da2411e7329ba5a4c209b9d8bda6d95ed/68747470733a2f2f7472617669732d63692e6f72672f657472657061742f636f6d706c6565742e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/etrepat/compleet)

Compleet is a PHP port of the awesome [Soulmate](https://github.com/seatgeek/soulmate) ruby gem, which was written by Eric Waller. All credit should go to the original library author.

This library will help you solve the common problem of developing a fast autocomplete feature. It uses Redis's sorted sets to build an index of partially completed words and the corresponding top matching items, and provides a simple interface to query them. Compleet finishes your sentences.

Compleet requires [PHP](http://www.php.net) >= 5.4 (or [HHVM](http://www.hhvm.com) >= 3.2) and its only dependencies are [Composer](http://getcomposer.org) itself and the fantastic [Predis](https://github.com/nrk/predis/) PHP client library for Redis.

Getting Started
---------------

[](#getting-started)

Compleet is distributed as a composer package, so kick things off by adding it as a requirement to your `composer.json` file:

```
{
  "require": {
    "etrepat/compleet": "~1.0"
  }
}
```

Then update your packages by running `composer update` or install with `composer install`.

Usage
-----

[](#usage)

Compleet is designed to be simple and fast, and its main features are:

- Provide suggestions for multiple types of items in a single query.
- Sort results by user-specified score, lexycographically otherwise.
- Store arbitrary metadata for each item. You may store url's, thumbail paths, etc.

An *item* is a simple JSON object that looks like:

```
{
  "id": 3,
  "term": "Citi Field",
  "score": 81,
  "data": {
    "url": "/citi-field-tickets/",
    "subtitle": "Flushing, NY"
  }
}
```

Where `id` is a unique identifier (within the specific type), `term` is the phrase you wish to provide completions for, `score` is a user-specified ranking metric (redis will order things lexicographically for items with the same score), and `data` is an optional container for metadata you'd like to return when this item is matched.

### Managing items

[](#managing-items)

Before being able to perform any autocomplete search we must first load some data into our redis database. To feed data into a Redis server instance for later querying, Compleet provides the `Loader` class:

```
require __DIR__ . '/vendor/autoload.php';

$loader = new Compleet\Loader('venues');
```

The constructor parameter is the type of the items we are actually going to add/remove or load. We'll later use this same type for search. This is used so we can add several kinds of completeley differentiated data and index it into Redis separately.

By default a `Compleet\Loader` object will instatiate a connection to a local redis instance as soon as it is needed. If you wish to change this behaviour, you may either provide a connection into the constructor:

```
require __DIR__ . '/vendor/autoload.php';

$redis = new Predis\Client('tcp://127.0.0.1/6379?database=0');

$loader = new Compleet\Loader('venues', $redis);
```

or use the `setConnection` method:

```
require __DIR__ . '/vendor/autoload.php';

$redis = new Predis\Client('tcp://127.0.0.1/6379?database=0');

$loader = new Compleet\Loader('venues');
$loader->setConnection($redis);
```

#### Loading items

[](#loading-items)

Now that we have a loader object in place we probably want to use it to load a bunch of items into our redis database. Imagine we have the following PHP item array (which follows the previous JSON structure):

```
$items = array(
  array(
    'id' => 1,
    'term' => 'Dodger Stadium',
    'score' => 85,
    'data' => array(
      'url' => '/dodger-stadium/tickets',
      'subtitle' => 'Los Angeles, CA'
    )
  ),
  array(
    'id' => 28,
    'term' => 'Angel Stadium',
    'score' => 85,
    'data' => array(
      'url' => '/angel-stadium- tickets/',
      'subtitle' => 'Anaheim, CA'
    )
  )
  ... etc ...
);
```

To load these items into Redis for later querying and previously clearing all existing data we have the `load` method:

```
$loader->load($items);
```

#### Adding items

[](#adding-items)

We may add a single item in a similar fashion with the `add` method:

```
$item = array(
  'id' => 30,
  'term' => 'Chase Field',
  'score' => 85,
  'data' => array(
    'url' => '/chase-field-ticket/',
    'subtitle' => 'Phoenix, AZ'
  )
);

$loader->add($item);
```

The `add` method appends items individually without previously clearing the index.

For both the `load` and `add` methods, each item must supply the `id` and `term` array keys. All other attributes are optional.

#### Removing items

[](#removing-items)

Similarly if we need to remove an individual item, the `remove` method will do just that:

```
$item = array(
  'id' => 30,
  'term' => 'Chase Field',
  'score' => 85,
  'data' => array(
    'url' => '/chase-field-ticket/',
    'subtitle' => 'Phoenix, AZ'
  )
);

$loader->remove($item);
```

Only the `id` key will be used and is actually mandatory.

#### Clearing the index

[](#clearing-the-index)

To wipe out all of the previously indexed data we may use the `clear` method:

```
$loader->clear();
```

### Querying

[](#querying)

Analogous to the `Compleet\Loader` class, Compleet provides the `Matcher` class which will allow us to query against previously indexed data. It works pretty similarly and accepts the same constructor arguments:

```
require __DIR__ . '/vendor/autoload.php';

$redis = new Predis\Client('tcp://127.0.0.1/6379?database=0');

$matcher = new Compleet\Matcher('venues', $redis);
// or:
//  $matcher = new Compleet\Matcher('venues');
//  $matcher->setConnection($redis);
```

Again, the first constructor parameter is the type of the items we are actually going query against.

Then, the `matches` method will allow us to query the supplied term against the indexed data:

```
$results = $matcher->matches('stad');
```

This will perform a search against the index of partially completed words for the `venues` type and it will return an array of matching items for the term `stad`. The resulting array will be sorted by the supplied score or alphabetically if none was given.

The `matches` method also supports passing an array of options as a second argument:

```
$queryOptions = array(
  // resultset size limit (defaults to 5)
  'limit' => 5,

  // whether to cache the results or not (defaults to true)
  'cache' => true

  // cache expiry time in seconds (defaults to 600)
  'expiry' => 600
);

$results = $matcher->matches('stad', $queryOptions);
```

Setting the `limit` option to `0` will return *all* results which match the provided term.

Matching a single term against multiple types of items should be easy enough:

```
$types = array('products', 'categories', 'brands');

$results = array();

foreach($types as $type) {
  $matcher = new Compleet\Matcher($type);
  $results[$type] = $matcher->matches('some term');
}
```

Working with the CLI
--------------------

[](#working-with-the-cli)

Compleet also provides a CLI utility, the `compleet` script, for easy data indexing from JSON documents/files. It may also be used to conduct queries for testing purposes. Like many composer packages which supply a binary, it will probably be placed under the `vendor/bin` folder of your project.

To load data into redis from the CLI, you can pipe items from a JSON file into the `compleet load TYPE` command.

Here's a sample `venues.json` (one JSON item per line):

```
{"id":1,"term":"Dodger Stadium","score":85,"data":{"url":"\/dodger-stadium-tickets\/","subtitle":"Los Angeles, CA"}}
{"id":28,"term":"Angel Stadium","score":85,"data":{"url":"\/angel-stadium-tickets\/","subtitle":"Anaheim, CA"}}
{"id":30,"term":"Chase Field ","score":85,"data":{"url":"\/chase-field-tickets\/","subtitle":"Phoenix, AZ"}}
{"id":29,"term":"Sun Life Stadium","score":84,"data":{"url":"\/sun-life-stadium-tickets\/","subtitle":"Miami, FL"}}
{"id":2,"term":"Turner Field","score":83,"data":{"url":"\/turner-field-tickets\/","subtitle":"Atlanta, GA"}}
```

And here's the load command (The `compleet` utility will assume redis is running locally on the default port, or you can specify a redis connection string with the `--redis` argument):

```
$ vendor/bin/compleet load venues < venues.json

```

Running `compleet -h` will list all the operations which are supported by the CLI and its arguments. All operations that may be performed programatically can be run from the `compleet` utility.

Using Compleet with your framework
----------------------------------

[](#using-compleet-with-your-framework)

Compleet is a standalone composer package and should work out of the box regardless of the PHP framework you use. In fact, none is needed.

### Using Compleet with Laravel

[](#using-compleet-with-laravel)

A Compleet integration for [Laravel](http://www.laravel.com) &gt;= 4.2 is provided in the [Laravel Compleet](https://github.com/etrepat/laravel-compleet.git) package. It will help reduce the amount of boilerplate code needed to make the autocomplete functionality in your project useful and adds several nice integrations such as: global config, artisan commands, redis connection reuse, controller code, routes, etc.

Take a look at the [Laravel Compleet](https://github.com/etrepat/laravel-compleet.git) project page for more information on how to use Compleet with your [Laravel](http://www.laravel.com) applications.

Contributing
------------

[](#contributing)

Thinking of contributing? Maybe you've found some nasty bug? That's great news!

1. Fork &amp; clone the project: `git clone git@github.com:your-username/compleet.git`.
2. Run the tests and make sure that they pass with your setup: `phpunit`.
3. Create your bugfix/feature branch and code away your changes. Add tests for your changes.
4. Make sure all the tests still pass: `phpunit`.
5. Push to your fork and submit new a pull request.

License
-------

[](#license)

Compleet is licensed under the terms of the [MIT License](http://opensource.org/licenses/MIT)(See LICENSE file for details).

---

Coded by [Estanislau Trepat (etrepat)](http://etrepat.com). I'm also [@etrepat](http://twitter.com/etrepat) on twitter.

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity20

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~6 days

Total

2

Last Release

4232d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d344974e819f4fb3cc2c0e78f479345d0ccbbef00957f641e49577b58634c571?d=identicon)[etrepat](/maintainers/etrepat)

---

Top Contributors

[![etrepat](https://avatars.githubusercontent.com/u/148851?v=4)](https://github.com/etrepat "etrepat (32 commits)")

---

Tags

searchautocompleteredis

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/etrepat-compleet/health.svg)

```
[![Health](https://phpackages.com/badges/etrepat-compleet/health.svg)](https://phpackages.com/packages/etrepat-compleet)
```

###  Alternatives

[predis/predis-async

Asynchronous version of Predis

366348.4k](/packages/predis-predis-async)[rhubarbgroup/redis-cache

A persistent object cache backend for WordPress powered by Redis. Supports Predis, PhpRedis, Relay, replication, sentinels, clustering and WP-CLI.

51795.3k1](/packages/rhubarbgroup-redis-cache)[monospice/laravel-redis-sentinel-drivers

Redis Sentinel integration for Laravel and Lumen.

103830.5k](/packages/monospice-laravel-redis-sentinel-drivers)[predis/service-provider

Predis service provider for the Silex microframework

68546.6k1](/packages/predis-service-provider)[jamescauwelier/psredis

Sentinel client for the popular php redis client

77392.9k5](/packages/jamescauwelier-psredis)[cache/predis-adapter

A PSR-6 cache implementation using Redis (Predis). This implementation supports tags

272.6M13](/packages/cache-predis-adapter)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)