Casting - Dates, Blobs and Null
Dealing with Casting, (everything except strings and numbers)
This is experimental!, although it is documented, it currently only supports a limited amount of databases (send me fixes if you want it to support your favorite database), and the internal operations/API may change in the future..
DataObjects is a very easy way to work with databases that are focused on numbers and strings. You can also use it on date fields (although you must format your strings correctly), and you can use it with other types by using raw SQL query(), and the string value "null" is automatically converted to NULL in the database.
In an effort to provide a cleaner way to code to the richer database types, the DB_DataObject_Cast object was created. It's purpose is to simply create an object to represent some of the more unusual types. Below is an example of using it to create a few simple types.
Cast Objects can be used in both building queries, and assigning values
Cast Objects for building and assigning values
<?php
// using Cast Objects for building a query.
$person = DB_DataObject::factory('person');
// assign the value of birthday to a Cast object with a date.
$person->birthday = DB_DataObject_Cast::date(2000,12,30);
$person->find();
while ($person->fetch()) {
echo "{$person->name} has a birthday on 30 december 2002<BR>";
}
// use Cast Objects for assigning values.
$person = DB_DataObject::factory('person');
$person->get(12);
// set the persons's birthday to 30 december 2000
$person->birthday = DB_DataObject_Cast::date(2000,12,30);
// now update the database.
$person->update();
?>
As you can see, This component is in it"s infancy, so if you have any feature requests, ideas, please do not hesitate to contact me at alan_k at php dot net.
The blob and string type
Blobs are fields which can store large amounts of binary data in the databases.
At present only blobs is only supported in postgres using the bytea type. (please email me with code for other databases.)
Inserting a photo and a big text file
<?php
$person = DB_DataObject::factory('person');
$person->name = 'fred'
// use blob for binary data.
$person->photo = DB_DataObject_Cast::blob(file_get_contents('xxx.jpg'));
// use string for textural data into a blob type.
$person->xmldocs = DB_DataObject_Cast::string(file_get_contents('xxx.xml'));
// now insert into the database.
$person->insert();
?>
The date type
Most dates are stored in a database in ISO standard format, this method, allows you to create date types, from either Year,month,day, Human readable day/month/year, or standard iso format year-month-day. It fills in the remaining values based on simple rules.
Inserting a date in various formats
<?php
$person = DB_DataObject::factory('person');
$person->name = 'fred'
// use a human readable date
// full format
$person->birthday = new DB_DataObject_Cast::date('21/12/2003');
// use only a month/year - actually sets to 1 december 2003
$person->expires = DB_DataObject_Cast::date('12/2003');
// use only a year only - actually sets to 1 jan 2003
$person->expires = DB_DataObject_Cast::date(2003);
// use a iso formated
// full formated
$person->birthday = DB_DataObject_Cast::date('2003-12-21');
// use only a year-month - actually sets to 1 december 2003
$person->expires = DB_DataObject_Cast::date('2003-12');
// using array syntax
// full formated
$person->birthday = DB_DataObject_Cast::date(2003,12,21);
// use only a year-month - actually sets to 1 december 2003
$person->expires = DB_DataObject_Cast::date(2003,12);
// the real values are stored in object variables
echo $person->birthday->year; // prints 2003
echo $person->birthday->month; // prints 12
echo $person->birthday->day; // prints 21
// you can do simple date addition (similar to mktime)
$d = DB_DataObject_Cast::date('01/12/2003');
$nextMonth = DB_DataObject_Cast::date($d->year,$d->month+1,1);
?>
The sql type
Some types are sql specific, or may even be database specific, you can use the sql type to put raw strings as part of the sql statement.
using raw sql
<?php
$person = DB_DataObject::factory('person');
$person->get(12);
// set the birthday to null.
$person->birthday = DB_DataObject_Cast::sql('NULL');
// do a sql cast statement (postgres specific)
$data = DB_DataObject_Cast::sql('cast("123123",datetime)');
// now insert into the database.
$person->insert();
?>