Symphony API ideas

Rowan

Revised, and in code at: http://pastie.org/1817582

Create a new entry:

$errors = new ErrorStack();
$entry = new Entry('section');

try {
    $entry->setAll($_POST);
    $entry->validate($errors);
    $entry->save($errors);
}

catch (FieldValidateException $e) {
    
}

catch (FieldSaveException $e) {
    
}

Get one entry by Id:

$entry = Entry::getById(1);

Get many entries by Id:

$enries = Entry::getAllById(1, 2, 3);            // Basically the same thing, one programatic
$enries = Entry::getAllById(array(1, 2, 3));     // and the other not.

Get entries with one filter:

$query = new EntryQuery('section');              // Loads session, basic field info.
$query->where('published', 'yes');               // Only grab entries where checkbox is checked.

$entries = $query->execute();                    // Not sure which style I like.
$entries = Entry::getAll($query);

Get entries with one filter and sort:

$query = new EntryQuery('section');
$query->sort('order-field', 'asc');              // Sort by some pre-defined order field.
$query->where('published', 'yes');

Get entries with many filters and sort:

$query = new EntryQuery('section');
$query->sort('order-field', 'asc');
$query->where()                                  // Returns internal WHERE statement object.
    ->and()                                      // All statements after this are joined by AND.
    ->field('published', 'yes')                  // Only grab entries where checkbox is checked.
    ->field('title-field', array(                // Entries that contain 'hello'.
        'filter'    => 'contains',
        'value'        => 'hello'
    ));

Get entries with complex sorting:

$query = new EntryQuery('section');
$query->sort()                                   // Returns internal ORDER BY statement object.
    ->field('order-field', 'desc')               // Sort by order first, if any entries have the
    ->field('title-field', 'asc');               // same order value then sort them by title second.

Get entries with complex grouping:

$query = new EntryQuery('section');
$query->group()                                  // Returns internal GROUP BY statement object.
    ->field('date-field', array(                 // Return results grouped by year and month.
        'year'        => true,
        'month'        => true
    ));

Notes on complex queries:

The and and or functions can be used either inline or with a closure, this is so developers can properly define their queries. Take the following query as an example:

$query->where()
    ->field('title-field', 'hello')
    ->field('body-field', 'hello');

This would build SQL similar to this:

(
    title-field.handle = 'hello'
    OR title-field.value = 'hello'
)
AND (
    body-field.handle = 'hello'
    OR body-field.value = 'hello'
)

But what if you only wanted the body counted field on entries that are published?

$query->where()
    ->field('title-field', 'hello')
    ->or()
    ->field('body-field', 'hello')
    ->field('published', 'yes');

Which lets any published entry through without passing the other requirements:

(
    title-field.handle = 'hello'
    OR title-field.value = 'hello'
)
AND (
    body-field.handle = 'hello'
    OR body-field.value = 'hello'
)
OR (
    published.value = 'yes'
)

Here's what you actually need to do - nest the last two requirements:

$query->where()
    ->field('title-field', 'hello')
    ->and(function($q) {
        $q->or()
            ->field('body-field', 'hello')
            ->field('published', 'yes');
    })

Which should give you the correct SQL:

(
    title-field.handle = 'hello'
    OR title-field.value = 'hello'
)
AND (
    (
        body-field.handle = 'hello'
        OR body-field.value = 'hello'
    )
    OR (
        published.value = 'yes'
    )
)

Huib

Getting an entry from a section, filtering by the name field (long)

$section = Sections::getById(1);
$entries = $section->getEntries();
$entry   = $entries->getByName('You')->current();

Getting an entry from a section, filtering by tne name field (short)

$entry = Sections::getById(1)->getEntries()->getByName('Nick')->current();

Getting an entry from an entry id without knowing the section

$entry = Entries::getById(1);

Getting the name and body fields from an entry in section 1, filtering by the name field (long)

$section = Sections::getById(1);
$entries = $section->getEntries();
$entry   = $entries->getByName('You');
$fields  = $entry->get('name', 'body');

Getting the name field from an entry in a section, filtering by name. (short)

$field = Sections::getById(1)->getEntries()->getByName('You')->getName();

Getting the name field from entry 12

$field = Entries::getById(12)->getName();

Nick

Class Entry

• setSectionId(int $section_id) sets section ID
• setSectionHandle(string $section_handle) sets section handle
• getFields() returns a collection of field data
• getField(string $handle) returns the data of a field
• setField(string $handle, mixed $value) sets the data of a field
• save(int $section_id) persist Entry in a given section
• save(string $section_handle) persist Entry in a given section
• save(Section $section) persist Entry in a given section
• asXML() return the XML representation of an entry

Class Entries

• get(int $id) returns an Entry object matching the ID
• get(array $filters, array $options) returns a collection of Entry objects matching filters, optional array of extra options (fields, limit, sort, direction)

Class Sections

• get(int $id) returns a Section object matching the ID
• get(string $handle) returns a Section object matching the handle

Get an entry by ID (no section required), two ways:

$entry = Entries::get(123);
$entry = Entries::get(array('system:id' => 123))->current();

If the argument is numeric (ID) then a single Entry is returned. If an array (of filters) then an iterator or collection of Entry objects is returned.

Get an entry by title (section required)

$section = Sections::get(1);
$entry = $section->getEntries(array('title' => 'Lorem ipsum'))->current();

The getEntries() method on a Section object is the equivalent of Entries::get().

Get specific fields of an entry (e.g. data source included elements)

$section = Sections::get(1);
$entry = $section->getEntries(
	array(
		'title' => 'Lorem ipsum'
	),
	array(
		'fields' => array('title', 'description', 'date'),
		'limit' => 20,
		'sort' => 'date',
		'direction' => 'desc'
	)
)->current();

Get the Title field from an entry

$entry = Entries::get(123);
$title = $entry->getField('title');

Create new Entry in section 123

$entry = new Entry();
$entry->setField('title, 'Lorem ipsum');
$entry->save(123);

or

$section = Sections::get(1);
$entry = new Entry();
$entry->setField('title, 'Lorem ipsum');
$entry->save($section);