Download the PHP package tomwalder/php-appengine-search without Composer

Full Text Search for PHP on Google App Engine

This library provides native PHP access to the Google App Engine Search API.

At the time of writing there is no off-the-shelf way to access the Google App Engine full text search API from the PHP runtime.

Generally this means developers cannot access the service without using Python/Java/Go proxy modules - which adds complexity, another language, additional potential points of failure and performance impact.

ALPHA This library is in the very early stages of development. Do not use it in production. It will change.

Table of Contents

• Examples
• Install with Composer
• Queries
• Geo Queries
• Autocomplete
• Creating Documents - includes location (Geopoint) and Dates
• Facets
• Deleting Documents
• Local Development
• Best Practice, Free Quotas, Costs
• Google Software

Examples

I find examples a great way to decide if I want to even try out a library, so here's a couple for you.

In this example, I've used the Alternative Array Syntax for creating Documents - but you can also do it like this:

Now let's do a simple search and display the output

Demo Application

Search pubs!

Application: http://pub-search.appspot.com/

Code: https://github.com/tomwalder/pub-search

Getting Started

Install with Composer

To install using Composer, use this require line in your composer.json for bleeding-edge features, dev-master

"tomwalder/php-appengine-search": "v0.0.4-alpha"

Or, if you're using the command line:

composer require tomwalder/php-appengine-search

You may need minimum-stability: dev

Queries

You can supply a simple query string to Index::search

For more control and options, you can supply a Query object

Query Strings

Some simple, valid query strings:

• price:2.99
• romeo
• dob:2015-01-01
• dob < 2000-01-01
• tom AND age:36

For much more information, see the Python reference docs: https://cloud.google.com/appengine/docs/python/search/query_strings

Sorting

Limits & Offsets

Return Fields

Expressions

The library supports requesting arbitrary expressions in the results.

These can be accessed from the Document::getExpression() method on the resulting documents, like this:

Get Document by ID

You can fetch a single document from an index directly, by it's unique Doc ID:

Scoring

You can enable the MatchScorer by calling the Query::score method.

If you do this, each document in the result set will be scored by the Search API "according to search term frequency" - Google.

Without it, documents will all have a score of 0.

And the results...

Multiple Sorts and Scoring

If you apply score() and sort() you may be wasting cycles and costing money. Only score documents when you intend to sort by score.

If you need to mix sorting of score and another field, you can use the magic field name _score like this - here we sort by price then score, so records with the same price are sorted by their score.

Helper Queries & Tools

Distance From

A common use case is searching for documents that have a Geopoint field, based on their distance from a known Geopoint. e.g. "Find pubs near me"

There is a helper method to do this for you, and it also returns the distance in meters in the response.

This will return results, nearest first to the supplied Lat/Lon, and there will be an expression returned for the distance itself - prefixed with distance_from_:

Autocomplete

Autocomplete is one of the most desired and useful features of a search solution.

This can be implemented fairly easily with the Google App Engine Search API, with a little slight of hand!

The Search API does not natively support "edge n-gram" tokenisation (which is what we need for autocomplete!).

So, you can do this with the library - when creating documents, set a second text field with the output from the included Tokenizer::edgeNGram function

Then you can run autocomplete queries easily like this:

You can see a full demo application using this in my "pub search" demo app

Creating Documents

Schemas & Field Types

As per the Python docs, the available field types are

• Atom - an indivisible character string
• Text - a plain text string that can be searched word by word
• HTML - a string that contains HTML markup tags, only the text outside the markup tags can be searched
• Number - a floating point number
• Date - a date with year/month/day and optional time
• Geopoint - latitude and longitude coordinates

Dates

We support DateTime objects or date strings in the format YYYY-MM-DD (PHP date('Y-m-d'))

Geopoints - Location Data

Create an entry with a Geopoint field

Batch Inserts

It's more efficient to insert in batches if you have multiple documents. Up to 200 documents can be inserted at once.

Just pass an array of Document objects into the Index::put() method, like this:

Alternative Array Syntax

There is an alternative to directly constructing a new Search\Document and setting it's member data, which is to use the Search\Schema::createDocument factory method as follows.

Namespaces

You can set a namespace when constructing an index. This will allow you to support multi-tenant applications.

Facets

The Search API supports 2 types of document facets for categorisation, ATOM and NUMBER.

ATOM are probably the ones you are most familiar with, and result sets will include counts per unique facet, kind of like this:

For shirt sizes

• small (9)
• medium (37)

Adding Facets to a Document

Getting Facets in Results

Deleting Documents

You can delete documents by calling the Index::delete() method.

It support one or more Document objects - or one or more Document ID strings - or a mixture of objects and ID strings!

Local Development Environment

The Search API is supported locally, because it's included to support the Python, Java and Go App Engine runtimes.

Best Practice, Free Quotas, Costs

Like most App Engine services, search is free... up to a point!

• Free quota information
• Search API pricing

And some best practice that is most certainly worth a read

• Best practice for the Google App Engine Search API

Google Software

I've had to include 2 files from Google to make this work - they are the Protocol Buffer implementations for the Search API. You will find them in the /libs folder.

They are also available directly from the following repository: https://github.com/GoogleCloudPlatform/appengine-php-sdk

These 2 files are Copyright 2007 Google Inc.

As and when they make it into the actual live PHP runtime, I will remove them from here.

Thank you to @sjlangley for the assist.

Other App Engine Software

If you've enjoyed this, you might be interested in my Google Cloud Datastore Library for PHP, PHP-GDS