Subversion-Projekte lars-tiefland.prado

<com:TContent ID="body">

<h1>Custom Type Handlers</h1>
<p>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,
<tt>ITypeHandlerCallback</tt>, for you to use in implementing your custom type
handler.</p>

<com:TTextHighlighter Language="php" CssClass="source">
interface ITypeHandlerCallback
{
    public function getParameter($object);

    public function getResult($string);

    public function createNewInstance();
}
</com:TTextHighlighter>

<p>The <tt>getParameter</tt> method allows you to process a <tt>&lt;statement&gt;</tt>
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.</p>

<p>The <tt>getResult</tt> 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
<tt>resultClass</tt>, <tt>resultMap</tt>, or <tt>listClass</tt>.</p>

<p>The <tt>createNewInstance</tt> method allows the DataMapper to create new instance
of a particular type handled by this callback.</p>

<p>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.</p>

<com:TTextHighlighter Language="php" CssClass="source">
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;
    }
}
</com:TTextHighlighter>

<p>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.</p>

<com:TTextHighlighter Language="php" CssClass="source">
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;
    }
}
</com:TTextHighlighter>

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

<com:TTextHighlighter Language="xml" CssClass="source">
[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>
</com:TTextHighlighter>

</com:TContent>