davewid/cactus

A lightweight ORM using the DataMapper pattern, PHP 5.3+

Cactus

Cactus is a ORM using the DataMapper pattern for PHP 5.3+, _(*1)

Example

We will walk through a quick example on how to use Cactus. First we will start with a table called user that we will build our example around., _(*2)

``` sql CREATE TABLE IF NOT EXISTS user ( user_id int(10) unsigned NOT NULL AUTO_INCREMENT, email varchar(128) NOT NULL, password varchar(64) DEFAULT NULL, first_name varchar(50) NOT NULL, last_name varchar(50) NOT NULL, status tinyint(3) unsigned NOT NULL DEFAULT '1', create_date timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (user_id) ) ENGINE=MyISAM DEFAULT CHARSET=utf8;, <sub>(*3)</sub>

Working with this structure we can now dive into the model and entity classes.

## Mapper

The mapper classes hold all of the information about the database table it is
mapping, including the table name and primary key.

Here is the model class for our `user` table.

``` php
<?php

class UserMapper extends \Cactus\Mapper
{
    /**
     * Use the init() function so you don't have to mess with handling the
     * adapter injection in the constructor.
     */
    protected function init()
    {
        $this->table = "user";
        $this->primary_key = "user_id";

        $this->columns = array(
            'user_id' => 'integer',
            'email' => 'string',
            'password' => 'string',
            'first_name' => 'string',
            'last_name' => 'string',
            'status' => 'integer'
            'create_date' => 'dateTime'
        );
    }
}

The mapper class has no knowledge of how to connect to your data source so you will have to specify that yourself., <sub>(*4)</sub>

``` php <?php, <sub>(*5)</sub>

$pdo = new PDO($dsn, $username, $password); $adapter = new \Cactus\Adapter\PDO($pdo);, <sub>(*6)</sub>

$mapper = new UserMapper($adapter);, <sub>(*7)</sub>

As you can see the adapter needs to be injected into the class, so it is probably
wise to use a dependency injection container to accomplish this.

_See the [PDO](http://www.php.net/manual/en/class.pdo.php) docs for more
information on creating a PDO connection._

Using a framework or don't have PDO available? You are in luck because you can
easily create adapters to suit your needs. All you need to do is implement the
`\Cactus\Adapter` interface and inject that adapter into Cactus.

## Entity

An entity is a representation of each data row as an object. All validation
and data normalization should be contained within the entity.

Below is a sample entity class for our user.

``` php
<?php

class User extends \Cactus\Entity{}

Pretty simple huh?, <sub>(*8)</sub>

Querying

There are 3 types of queries built in; finding, saving and deleting., <sub>(*9)</sub>

Find

``` php <?php, <sub>(*10)</sub>

// Find the user with a user_id of 1 $user = $mapper->get(1);, <sub>(*11)</sub>

// Get all users $users = $mapper->all();, <sub>(*12)</sub>

// Find user who's email is test@foo.com $found = $mapper->find(array( 'email' => "test@foo.com" ));, <sub>(*13)</sub>

### Save
``` php
<?php

// New user assuming $post is posted form data
$user = new User($post);
$mapper->save($user);

// Existing user, after modifications
$user = $mapper->get(1);
$user->first_name = "Billy";
$mapper->save($user);

echo $user->first_name; // Output: Billy

Delete

``` php <?php, <sub>(*14)</sub>

$user = $mapper->get(1); $mapper->delete($user);, <sub>(*15)</sub>

## Defining Columns

The goal of defining the columns is not to be able to generate the sql to
create your tables, but to convert the string values from the database over to
native php types.

Lets take a look at the example from `UserMapper` above

``` php
<?php

$this->columns = array(
    'user_id' => 'integer',
    'email' => 'string',
    'password' => 'string',
    'first_name' => 'string',
    'last_name' => 'string',
    'status' => 'integer'
    'create_date' => 'dateTime'
);

As you can see the columns array is setup in a $name => $type setup. For a full list of field types you can choose from check the documentation for \Cactus\Converter. Setting a field to false keeps it as a string as well., <sub>(*16)</sub>

Building Queries

You can build queries for custom methods in your model anyway you want. Cactus comes bundled with Peyote if you would like to build your queries in an object oriented way., <sub>(*17)</sub>

Supported Adapters

Below is a list of currently supported adapters. If you don't see your framework in the list, hack the code and send a pull request., <sub>(*18)</sub>

• PDO

Hacking

Cactus is in heavy development and all contributions are welcome and encouraged. Before you start hacking away, make sure you switch over to the develop branch., <sub>(*19)</sub>

Running Tests

Before you send a pull request on any changes, make sure that the phpunit tests pass, adding tests where necessary., <sub>(*20)</sub>

Since this is an ORM, you will need to test a database. To connect to the database you will need to to modify the php section of the phpunit.xml file with your settings. Before you commit changes make sure you run..., <sub>(*21)</sub>

~~~ shell git update-index --assume-unchanged phpunit.xml ~~~, <sub>(*22)</sub>

This way your username/passwords don't get pushed into the repo., <sub>(*23)</sub>

Developed by Dave Widmer, <sub>(*24)</sub>