Custom Type Handlers

A custom type handler allows you to extend the DataMapper's capabilities in handling types that are specific to your database provider, not handled by your database provider, or just happen to be part of your application design. The SQLMap for PHP DataMapper provides an interface, ITypeHandlerCallback, for you to use in implementing your custom type handler.

interface ITypeHandlerCallback
{
    public function getParameter($object);

    public function getResult($string);

    public function createNewInstance();
}

The getParameter method allows you to process a <statement> parameter's value before it is added as an parameter. This enables you to do any necessary type conversion and clean-up before the DataMapper gets to work.

The getResult method allows you to process a database result value right after it has been retrieved by the DataMapper and before it is used in your resultClass, resultMap, or listClass.

The createNewInstance method allows the DataMapper to create new instance of a particular type handled by this callback.

One scenario where custom type handlers are useful are the when you want to use date time values in the database. First, consider a very basic TDateTime class.

class TDateTime
{
    private $_datetime;

    public function __construct($datetime=null)
    {
        if(!is_null($datetime))
            $this->setDatetime($datetime);
    }

    public function getTimestamp()
    {
        return strtotime($this->getDatetime());
    }

    public function getDateTime()
    {
        return $this->_datetime;
    }

    public function setDateTime($value)
    {
        $this->_datetime = $value;
    }
}

We can use a custom type handler to intercept result and parameter mapping that uses the say "data" as one of its property type. The handler can be written as follows.

class TDateTimeHandler implements ITypeHandlerCallback
{
    public function getResult($string)
    {
        return new TDateTime($string);
    }

    public function getParameter($parameter)
    {
        if($parameter instanceof TDateTime)
            return $parameter->getTimestamp();
        else
            return $parameter;
    }

    public function createNewInstance()
    {
        return new TDateTime;
    }
}

With our custom type handler we can use the handler in our SqlMaps. To do that, we specify it as a basic <typeHandler> for all date types mapped in our SqlMap files

[Our SqlMap.config]

<typeHandlers>
 <typeHandler type="date" callback="TDateTimeHandler"/>
</typeHandlers>


[One of our SqlMap.xml files]
 <parameterMap id="boc-params">
  <parameter property="releasedDate" type="date"/>
 </parameterMap>

 <resultMap id="boc-result"  class="BudgetObjectCode">
  <result property="releasedDate" column="BOC_DATE" type="date"/>
 </resultMap>