VoodOrm 2.x.x

A simple micro-ORM that stays out of your way

---

Name: VoodOrm

License: MIT

Author: Mardix

Version : 2.x.x

Requirements: PHP >= 5.4, PDO

---

About Voodoo!

VoodOrm is a micro-ORM which functions as both a fluent select query API and a CRUD model class.

VoodOrm is built on top of PDO and is well fit for small to mid-sized projects, where the emphasis is on simplicity and rapid development rather than infinite flexibility and features. VoodOrm works easily with table relationship. And offers api that gets SQL out of your way

---

Features

• PDO and prepared statements
• Fluent Query
• Relationship
• Joins
• Aggregation
• Query debugger and query profiler
• Active Record pattern

Requirements

• PHP >= 5.4
• PDO

Error Reporting

VoodOrm does not escalate errors. Non-existing table produces SQL error that is reported by PDO conforming to PDO::ATTR_ERRMODE. Non-existing columns produces the same E_NOTICE as an attempt to access non-existing key in array.

What it doesn't do.

We believe it's best if certain stuff is kept to the developer to do, like caching or data validation. Also data validation can be done at the database level.

• No models or entities generation
• No data validation
• No caching
• No database migration

Install VoodOrm

You can just download VoodOrm as is, or with Composer.

To install with composer, add the following in the require key in your composer.json file

"voodoophp/voodorm": "2.*"

composer.json

{
    "name": "voodoophp/myapp",
    "description": "My awesome Voodoo App",
    "require": {
        "voodoophp/voodorm": "2.*"
    }
}

---

Working with VoodOrm

---

new VoodOrm( PDO $pdo )

To get started with VoodOrm, you have to setup the PDO connection. We'll be using the variable $DB as the database connection, $users as the table, $friends as another table throughout this whole tutorial

$pdo = new PDO("mysql:host=localhost;dbname=$dbname", $username, $password);
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$DB = new VoodOrm($pdo);

---

VoodOrm VoodOrm::table( string $tablename )

To connect to a table is straight forward by calling the method VoodOrm::table()

$users = $DB->table('users');

You can also set the table by calling the table as a method. The above can be also written like this

$users = $DB->users();
$friends = $DB->friends();

From there you will be able able to do any CRUD on the table with VoodOrm fluent query interface

---

##Data Modification

VoodOrm supports data modification (insert, update and delete). No data validation is performed by VoodOrm but all database errors are reported by the standard PDO error reporting. For data validation, we believe it's best to validate your data at the database level or application level

---

mixed VoodOrm::insert( Array $data )

To insert data in the table, use the insert(Array $data) where $data can be a one dimentional array to insert just one entry, or a muliple arrays to do mass insert.

If a single row was inserted, it will return the active record of the created object. Otherwise it will return the total entries inserted

For a single entry:

$user = $users->insert(array(
	 			"name" => "Mardix",
				"age" => 30, 
	 			"city" => "Charlotte",
     			"state" => "NC",
				"device" => "mobile",
	 			"timestamp" => $DB->NOW()
			));

Returns the VoodOrm active record instance of this entry where you can use $user->name or $user->city. We'll be able to do more later.

For a mass insert:

$massInserts = $users->insert(array(
					array(
						 "name" => "Mardix",
						 "city" => "Charlotte",
					     "state" => "NC",
					     "device" => "mobile",
						 "timestamp" => $DB->NOW()
					),
					array(
						 "name" => "Cesar",
						 "city" => "Atlanta",
					     "state" => "GA",
						 "device" => "mobile",
						 "timestamp" => $DB->NOW()
					),
					array(
						 "name" => "Gaga",
						 "city" => "Port-au-Prince",
					     "state" => "HT",
						 "device" => "computer",
						 "timestamp" => $DB->NOW()
					),
				));

returns the total entries that were inserted

---

mixed VoodOrm::update(Array $data)

There are two ways to update entries in VoodOrm, 1) by using the active record pattern for a fetched row, or 2) by using a where query to specify where to update. Also the method VoodOrm::set($key, $value) can be use to set the data before updating.

For single entry

$user->update(array(
					"city" => "Raleigh"
				));

it's the same as

$user->city = "Raleigh";
$user->update();

You can also use save() instead of update()

$user->save();

or with Voodoo::set(Array $data) or Voodoo::set($key, $value)

$user->set('city','Raleigh')->update();

For multiple entries:

For multiple entries we'll use VoodOrm::set() and VoodOrm::where() to specify where to update.

Voodoo::set(Array $data) or Voodoo::set($key, $value)

For mass update, we'll set the data to update using set(Array $data) and where($k, $v)

$user->set(array(
				"country_code" => "US"
		))
		->where("device", "mobile")
		->update();

*There are more fluent where aliases under Fluent Query Interface

---

mixed VoodOrm::save()

Save() is a shortcut to VoodOrm::insert() or VoodOrm::update()

To insert new data:

$user = $DB->users();
$user->name = "Mardix";
$user->city = "Charlotte";
$user->save(); 

To update:

$user = $users->findOne(123456);
$user->city = "Atlanta";
$user->save();

---

int VoodOrm::delete()

To delete entries we'll use the VoodOrm::delete() method

For single entries, by invoking the delete() method it will delete the current entry

$user = $users->reset()->findOne(1234);
$user->delete();

For multiple entries, we will use the VoodOrm::where() method to specify where to delete

$users->where("city", "Charlotte")->delete();

---

Aggregation

VoodOrm gives you access to aggregation methods on your table

---

int VoodOrm::count()

To count all the entries based on where clause

$allUsers = $users->count();

$count = $voodorm->where($x, $y)->count();

or for a specific column name

$count = $users->where($x, $y)->count($columnName);

float VoodOrm::max( string $columnName )

To get the max of a $columnName based on where() clause

$max = $users->where($x, $y)->max($columnName);

float VoodOrm::min( string $columnName )

To get the min of a $columnName based on where() clause

$min = $users->where($x, $y)->min($columnName);

float VoodOrm::sum( string $columnName )

To get the sum of a $columnName based on where() clause

$sum = $users->where($x, $y)->sum($columnName);

float VoodOrm::avg( string $columnName )

To get the average of a $columnName based on where() clause

$avg = $users->where($x, $y)->avg($columnName);

mixed VoodOrm::aggregate( string $function )

To run any aggregation function

$agg = $users->where($x, $y)->aggregate('GROUP_CONCAT $columnName');

---

Querying

VoodOrm provides a fluent interface to enable simple queries to be built without writing a single character of SQL.

Tow methods allow you to get a single entry or multiple entries: findOne() and find(). And fromArray() that load a raw data to the object.

---

FindOne

VoodOrm VoodOrm::findOne()

findOne() returns VoodOrm instance of a single entry if found, otherwise it will return FALSE.

$user = $users->where('id', 1234)
			  ->findOne();

The primary key can be set in the findOne(int $primaryKey) to get the same result as the above query. Meaning no need to have a where() clause.

$user = $users->findOne(1234);

Let's get the entry found:

if ($user) {
	echo " Hello $user->name!";

// On a retrieved entry you can perform update and delete
	$user->last_viewed = $users->NOW();
	$suer->save();
}

---

Find

ArrayIterator VoodOrm::find()

find() returns an ArrayIterator of the rows found which are instances of VoodOrm, otherwise it will return False.

$allUsers = $users->where('gender', 'male')
				  ->find();

foreach ($allUsers as $user) {
	echo "{$user->name}";

// On a retrieved entry you can perform update and delete
	$user->last_viewed = $users->NOW();
	$user->save();
}

find() also contains a shortcut when it's called in an iteration such as foreach:

$allUsers = $users->where('gender', 'male');

foreach ($allUsers as $user) {
	echo "{$user->name}";

// On a retrieved entry you can perform update and delete
	$user->last_viewed = $users->NOW();
	$suer->save();
}
				  

mixed VoodOrm::find( Closure $callback )

VoodOrm::find() also accept a Closure as a callback to do your own data manipulation. Upon execution, VoodOrm will pass the data found from the query to the closure function.

	$users->where('gender', 'male');

	$results = $users->find(function($data){
		$newResults = array();

		foreach ($data as $d) {
			$d["full_name"] = ucwords("{$data["first_name"]} {$data["last_name"]}");
			$newResults[] = $d;
		}

		return $newResults;
	});	

---

FromArray

VoodOrm VoodOrm::fromArray( Array $data )

Unlike find() and findOne() which make a query to the database to retrieve the data, fromArray() loads raw data and returns it as a VoodOrm object. It can be data that is cached into Redis/Memcached, but not coming directly from the database.

$data = [
		"id" => 916,
		"name" => "Jose",
		"last_name" => "Martinez"
		];

$anotherUser = $users->fromArray($data);

Now you can operate on it

$anotherUse->update(
					["name" => "Yolo"]
				);

---

Fluent Query Builder

---

Select

VoodOrm ***VoodOrm::s