DataMapper ORM

Writing an Extension

It is incredibly simple to write your own extension. This will walk you through the basic process, by recreating the included extension for JSON encoding and decoding.

Sharing Your Extension

If you'd like to share your own extensions with others, please add them to the repository!

Planning an Extension

An extension is simply a class with one or more exposed methods. These methods have a few minor rules.

You can include private methods simply by prepending the method with an underscore (_). These methods will not be exposed in the DataMapper model, but will be available for your use.

Creating the Extension Class

The class is a normal PHP class. The file should follow the same naming rules as a CodeIgniter Library, naming the file the lowercase form of the extension name, ending with .php. Store the class definition in application/datamapper.

The name of the extension class can be exactly like the extension (ie: Json), or you can use a prefix to prevent naming collisions, which is highly recommended.

The prefixes can be Datamapper ORM_, DataMapper_, MY_ (the CodeIgniter 'subclass_prefix' config parameter), or CI_. The last two should only be used for libraries. The order given is the order they are checked. If you use the MY_ prefix, Datamapper ORM will load the library it is based on, as well.

The recommended prefix is DMZ_, simply because it is short.

application/datamapper/json.php

 1
 2
 3
 4
 5
 6
 7
<?php
class DMZ_Json {

}

/* End of file json.php */
/* Location: ./application/datamapper/json.php */

Adding Public Methods

We want to be able to easily convert a DataMapper model into a JSON object. We'll use PHP5's json_encode for the heavy lifting, but we need to get the data out of the large and complex DataMapper model first.

The first argument to each public method is always the $object in use.

application/datamapper/json.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<?php
class DMZ_Json {
    function to_json($object)
    {
        $fields = $object->fields;
        $result = array();
        foreach($fields as $f)
        {
            $result[$f] = $object->{$f};
        }
        $json = json_encode($result);
        if($result === FALSE)
        {
            return FALSE;
        }
        return $json;
    }
}

/* End of file json.php */
/* Location: ./application/datamapper/json.php */

Now we can call $object->to_json(), and we'll get a JSON encoded view of $object.

Creating Custom Validation Rules

Extensions can also be used to collect custom validation rules.

See Validation - Custom Validation for more information about custom validation rules.

application/datamapper/custom_rules.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<?php
class DMZ_Custom_Rules {
    function __construct()
    {
        $CI =& get_instance();
        // load in the custom rules language file.
        $CI->lang->load('custom_rules');
    }

    // Validation prepping function to encrypt passwords
    function rule_exact_length($object, $field, $param)
    {
        // Check if field value is the required length
        if (strlen($object->{$field}) == $param)
        {
            return TRUE;
        }

        // Field value is not the required length
        return FALSE;
    }
}

/* End of file custom_rules.php */
/* Location: ./application/datamapper/custom_rules.php */

To use this rule, we have to add 'custom_rules' to our config or $extensions variable on a specific class. Then simply add 'exact_length' to a field's rules.

Accepting Load-Time Options

If you want to allow load-time options, simple accept a value in the constructor.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?php
// $options contains the options passed when the extension is loaded, or NULL if no options are defined
// $object contains the object that is loading this extension. it allows access to the objects properties
class DMZ_Custom_Rules {
    function __construct($options, $object)
    {
        foreach($options as $k => $v)
        {
            $this->{$k} = $v;
        }
        $CI =& get_instance();
        // load in the custom rules language file.
        $CI->lang->load('custom_rules');
    }
    // ...

 

To learn more, take a look a the included extensions.