Download the PHP package avadim/manticore-query-builder-laravel without Composer

English | Русский

ManticoreSearch Query Builder for Laravel

The easiest way to use the ManticoreSearch Query Builder in your Laravel or Lumen applications. This package allows you to build ManticoreSearch queries using a Laravel-like syntax.

The query builder is a separate package and is where the syntax of a query lives — match(), where(), insert(), the schema of a table. This one adds what only means something inside the framework: the service provider and the config file, named connections, and answers of the shape Laravel expects.

Contents

• Related packages
• Requirements
• Installation
• Configuration
• Quick start
• The alias, the facade and the container
• What the reads return
• When a query fails
• Pagination
• Transactions
• Migrations
• Long-running workers
• Logging
• Documentation
• Testing

Related packages

• avadim/manticore-query-builder-php — the query builder itself, with no dependency on Laravel: the syntax of a query, the schema DSL and the pool of connections live there. That is the one to use outside a Laravel application, and the one a change to match(), where() or insert() belongs to.
• avadim/manticore-laravel-scout — the ManticoreSearch driver for Laravel Scout, built on this package: full-text search of Eloquent models as Post::search('manticore')->get(), with the index kept in step by the observer of Scout.

Requirements

• PHP 7.4 or above with the PDO and JSON extensions
• Laravel 6 — 13, or Lumen
• avadim/manticore-query-builder-php 2.1 or above, installed along with this package
• Manticore Search reachable over its SQL interface, port 9306 by default. The HTTP/JSON API is not used.

A few things need more than the bare server: KNN vector search needs the KNN library, columnar storage the columnar one, rename() needs Manticore Buddy. What needs what is listed in the requirements of the query builder.

Installation

Laravel

The service provider of the package registers itself.

Publish the configuration file:

Lumen

Lumen discovers nothing on its own, so the service provider, the configuration and the alias are registered by hand in bootstrap/app.php:

Copy the configuration file into your application by hand as well.

Configuration

After the configuration file is published, a connection is set up in the .env file of your application (with appropriate values):

All available environment variables

A prefix keeps the tables of an application apart from the rest of a shared server: table('?products') reads the table myapp_products when the prefix is myapp_. With MANTICORE_FORCE_PREFIX=true the ? can be left out — every name is prefixed.

More connections are added to the connections array of config/manticore.php, each with the same set of keys; defaultConnection names the one used when no name is given.

Quick start

Everything between table() and the read — full-text match(), where(), aggregates, faceted search, JOIN, KNN vector search, the schema of a table — belongs to the query builder and is described in its documentation. The sections below cover what this package does differently.

The alias, the facade and the container

The \ManticoreDb alias of the examples is registered by the package itself. It is the shortest way in, but not the only one — the same connection is reachable through the facade and through the container:

All three answer alike: they share the connections, and a query built through any of them returns the collections described below. Manager answers the methods of a connection through __call(), which the @method annotations of the class describe, so an IDE completes them.

What the reads return

The standalone query builder answers with plain arrays — a collection there would mean an extra dependency in a framework-agnostic library. Inside Laravel the framework is a given, so this package answers the way Laravel does:

A Row reads both ways, so the code written against the array answer of the standalone builder keeps working:

Writes are untouched and keep the answers of the builder: insert() returns bool, update() and delete() the number of affected rows, insertGetId() the id.

When a query fails

A rejected read throws avadim\Manticore\QueryBuilder\QueryErrorException — a query with a mistake in it is a bug, not an empty result set, and an exception says so where it happened:

Writes keep answering with a value instead: false from insert(), zero affected rows from update() and delete(). The reason of the last statement, successful or not, is kept in its result set:

A full-text query typed by a visitor is the usual source of a rejected read, so it is worth passing through \ManticoreDb::escapeMatch($text) before it reaches match().

Pagination

Both accept the same arguments as in Laravel: paginate($perPage, $columns, $pageName, $page).

Transactions

Manticore serves BEGIN / COMMIT / ROLLBACK on real-time tables, so a transaction is written the way it is elsewhere in Laravel. Transactions live in the query builder itself, so the static call works too:

The callback receives the connection, and whatever it returns becomes the result of transaction(). An exception rolls the transaction back and is rethrown; a second argument sets how many times to try. Manticore has no savepoints, so a nested transaction() only counts a level deeper — the outermost commit is the one that writes.

Any SQL statement can be run directly:

Migrations

A table of Manticore is created in a Laravel migration like any other:

Manticore has no transactional DDL, so a migration that fails halfway leaves behind whatever it had already created — write down() so that it can be run over a half-built table.

A table already in use is changed the same way:

Three things this differs in from a migration of a SQL database:

• One operation per statement. The server takes no ADD COLUMN a, ADD COLUMN b, so the two columns above are two statements — and the second failing leaves the first one added, since there is nothing to roll back with.
• The rows written earlier keep an empty value in the new column: adding it does not reindex them. A full-text field added this way finds only the rows written after it, so the data has to be written again for the column to mean anything.
• The cache of the schema is dropped for you, but only in the connection that ran the statement — see Long-running workers for the ones that did not.

Long-running workers

A connection remembers the schema of every table it has described, which saves a DESCRIBE before each query and is what casts the values of a row into PHP types. The cache lives as long as the connection does — the length of a request under php-fpm, but much longer under Octane, a queue worker or a scheduled command.

So a table altered from somewhere else needs the cache dropped:

The builder keeps its own cache in step: create(), alter(), addColumn(), dropColumn(), truncate(), rename() and drop() drop the schema of the table they touched. What it cannot know about is a statement of yours — a migration run by another process, an ALTER sent through statement(), a table rebuilt by an indexer.

Logging

You can use logger instance for logging in this package.

Any PSR-3 logger will do, \Log::getLogger() is the one of Laravel. Service queries the builder sends on its own, DESCRIBE among them, are not logged.

Documentation

The syntax of a query, the schema of a table and everything else the builder does is described in the documentation of avadim/manticore-query-builder-php. Manticore Search itself is documented at https://manual.manticoresearch.com/

Testing

Some tests need a running ManticoreSearch server. By default they use 127.0.0.1:9306, this can be changed with the MANTICORE_TEST_HOST and MANTICORE_TEST_PORT environment variables in phpunit.xml.dist. If the server is unreachable those tests are skipped, the rest of the suite still runs. Tables created by the tests are named phpunit_* and are dropped afterwards.