Associative Array Conversion Methods (array)

To enable these methods, add 'array' to DataMapper's config, under 'extensions'.

Converts an object to and from associative arrays. The to_array method can be used directly with $_POST for rapid saving of HTML forms. When combined with the HTML Form Generation Methods, this extension can make creating simple content mangement tools very easy.

to_array($fields)

$fields: (Optional) If provided, only these fields will be included. If empty or not provided, only the database columns will be included.
Returns: An associative array containing the specified fields.

Converts the $object into an associative array. If $fields includes any related objects, the ids from the objects are collected into an array and stored on that key. This method does not recursively add objects.

Usage

$u = new User();
$u->get_by_id($user_id);
$u_array = $u->to_array(array('id', 'name', 'email'));

all_to_array($fields)

$fields: (Optional) If provided, only these fields will be included. If empty or not provided, only the database columns will be included.
Returns: An array of associative arrays of $object->all.

Converts $object->all into an array of associative arrays, using the to_array method.

all_to_single_array($field)

$field: (Required) field who's value has to be added to the array. If empty or not provided, an empty array is returned. The id value of the objects in the resultset will be used a key of the array.
Returns: An array of $field valuues in $object->all.

Converts the value of the column $field in $object->all into an array, using the id value as key. One possible use of this method is to generate HTML select dropdowns.

from_array($data, $fields, $save)

$data: An associative array of key/value pairs to set on the object.
$fields: (Optional) If provided, only these fields will be saved. If empty or not provided, only the database columns will be saved.
$save: (Optional) If set to TRUE, the object will be immediately saved. The result of the save will be returned. Defaults to FALSE.
Returns: The result of the save, or an array of newly related objects.

Example Application

A usage example of from_array can be found in the examples section.

Stores values from an associative array back on the $object.

The function works very differently if $fields is provided. If $fields is provided, it is assumed that every field should be in the $data array. If a field is missing, it is assumed to be FALSE (like an HTML checkbox), or an empty array (for related items).

You can include $has_one or $has_many relationships. In this case, the data should be one or more ids (multiple items should be in an array). The method will delete any missing items, and either return or save the new items.

Warning: This method assumes you are going to save immediately afterward. When including related objects in the fields array, please make sure you are inside a transaction, to prevent data loss if an error occurs.

Simple Usage

$data = array(
    'message' => 'Hello World',
    'date' => time()
);

// create a blank note
$n = new Note();

// save the new note automatically
if($n->from_array($data, '', TRUE))
{
    // redirect after save
}
else
{
    show_error('Invalid input');
}

Quickly Saving Form Data

$n = new Note();
// It is highly recommended you load the note before saving.
$n->get_by_id($this->input->post('id'));

$related = $n->from_array($_POST, array('message', 'date', 'category'));
// $related includes any new categories that need to be saved.  At this point, $n may have had some old categories deleted.

// add a related editor
$related['editor'] = $logged_in_user;

// save with the related objects
if($n->save($related))
{
    // redirect after save
}
else
{
    show_error('Invalid input');
}

DataMapper ORM