Queries With Spot

Finders (Mapper)

All these finders require a Mapper instance. Mappers are responsible for finding and updating individual entities.

The main finders used most are all to return a collection of entities, and first or get to return a single entity matching the conditions.


The get method accepts a primary key to load a record with:

// Get Post with 'id' = 58
$mapper = $spot->mapper('Entity\Post');
$post = $mapper->get(58);

If there is no Entity\Post with the primary key provided, boolean false will be returned.


Find all entities and return a Spot\Entity\Collection of loaded Entity\Post objects.

// Get ALL posts
$mapper = $spot->mapper('Entity\Post');
$posts = $mapper->all();


Find all entities that match the given conditions and return a Spot\Entity\Collection of loaded Entity\Post objects.

$mapper = $spot->mapper('Entity\Post');
// Where can be called directly from the mapper
$posts = $mapper->where(['status' => 1]);
// Or chained using the returned `Spot\Query` object - results identical to above
$posts = $mapper->all()->where(['status' => 1]);
// Or more explicitly using using `select`, which always returns a `Spot\Query` object
$posts = $mapper->select()->where(['status' => 1]);
A Spot\Query object is returned with all queries, which means additional conditions and other statements can be chained in any way or order you want. The query will be lazy-executed on interation or count, or manually by ending the chain with a call to execute().

Conditional Variations

# All posts with a 'published' status, descending by date_created
$posts = $mapper->all()
->where(['status' => 'published'])
->order(['date_created' => 'DESC']);
# All posts created before 3 days ago
$posts = $mapper->all()
->where(['date_created <' => new \DateTime('-3 days')]);
# Posts with 'id' of 1, 2, 5, 12, or 15 - Array value = automatic "IN" clause
$posts = $mapper->all()
->where(['id' => [1, 2, 5, 12, 15]]);


Find and return a single Spot\Entity object that matches the criteria.

$post = $mapper->first(['title' => "Test Post"]);

Or first can be used on a previous query with where to fetch only the first matching record.

$post = $mapper->where(['title' => "Test Post"])->first();

A call to first will always execute the query immediately, and return either a single loaded entity object, or boolean false.


To get an instance of the query builder (Spot\Query) with no conditions set on it, use select.

// Get instance of the query builder directly
$query = $mapper->select();

This is effectively the same thing as all(), but without any semantics attached.