Queries

Use getAll() to fetch all rows of a specific entity. For information on how to define entities, check schema.

$posts = getAll('blog/post');
$posts = /Application/Blog/Models/Post::getAll(); // Alternate option

Use get() to fetch a single row. It optionally takes an ID as argument, returning the row corresponding to said ID.

$post = get('blog/post', 12);
$post = /Application/Blog/Models/Post::get(12); // Alternate option

Conditions

Use where() to filter the results. The first parameter takes a valid SQL clause. Be sure to use field names as they are defined in your schema, not actual database fields. Saturn will translate these names to any appropriate database fields.

$posts = getAll('blog/post')->where('is_active = 1');

// Chaining is supported
$post = get('blog/post')
    ->where('is_active = 1')
    ->where('spotlight = 1');

Note that any function in the call chain returns a copy of the query. The original query is not modified.

// if neither get or getAll is called, getAll is assumed
$active_posts = Post::where('is_active = 1');

// $active_posts is not modified
$spotlight_posts = $active_posts->where('spotlight = 1');

Never provide input within the SQL string. The where() function supports string formatting as available through sprintf. Any data provided this way will be escaped safely.

// Bad idea
$post = get('blog/post')->where("slug = '$slug'");

// Do this instead
$post = get('blog/post')->where('slug = %s', $slug);

// Multiple parameters are supported
$post = Post::where('slug LIKE %s AND date > %s', $slug.'%', $date)->get();

// Using a single parameter multiple times
$post = get('blog/post')->where('(slug = %1$s AND category = 1) OR (slug = %1$s AND category = 2)', $slug);

Using models

Models will contain properties corresponding to fields in the schema. These are always available through the schema name, not the database field name.

$post = get('post')->where('slug = %s', $slug);
echo $post->title;
echo $post->content;

Queries that return multiple results (getAll) can be traversed using foreach().

$posts = Post::where('is_active = 1');
foreach ($posts as $post) {
    echo $post->title;
    echo $post->content;
}

$post = Post::where('slug = %s', $slug)->get();
foreach ($post->comment as $comment) {
    echo $comment->content;
}