Download the PHP package etrepat/compleet without Composer
On this page you can find all versions of the php package etrepat/compleet. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download etrepat/compleet
More information about etrepat/compleet
Files in etrepat/compleet
Package compleet
Short Description Redis-backed service for fast autocompleting
License MIT
Homepage https://github.com/etrepat/compleet
Informations about the package compleet
Compleet
Compleet is a PHP port of the awesome 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 >= 5.4 (or HHVM >= 3.2) and its only dependencies are Composer itself and the fantastic Predis PHP client library for Redis.
Getting Started
Compleet is distributed as a composer package, so kick things off by adding it as a requirement to your composer.json
file:
Then update your packages by running composer update
or install with composer install
.
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:
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
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:
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:
or use the setConnection
method:
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):
To load these items into Redis for later querying and previously clearing all existing data we have the load
method:
Adding items
We may add a single item in a similar fashion with the add
method:
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
Similarly if we need to remove an individual item, the remove
method will do just that:
Only the id
key will be used and is actually mandatory.
Clearing the index
To wipe out all of the previously indexed data we may use the clear
method:
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:
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:
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:
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:
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):
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
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
A Compleet integration for Laravel >= 4.2 is provided in the Laravel Compleet 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 project page for more information on how to use Compleet with your Laravel applications.
Contributing
Thinking of contributing? Maybe you've found some nasty bug? That's great news!
- Fork & clone the project:
git clone [email protected]:your-username/compleet.git
. - Run the tests and make sure that they pass with your setup:
phpunit
. - Create your bugfix/feature branch and code away your changes. Add tests for your changes.
- Make sure all the tests still pass:
phpunit
. - Push to your fork and submit new a pull request.
License
Compleet is licensed under the terms of the MIT License (See LICENSE file for details).
Coded by Estanislau Trepat (etrepat). I'm also @etrepat on twitter.