Using SQLMap PHP DataMapper

The SQLMap DataMapper API provides four core functions:

1. build a TSqlMapper instance from a configuration file or cache
2. execute an update query (including insert and delete)
3. execute a select query for a single object
4. execute a select query for a list of objects

The API also provides support for retrieving paginated lists and managing transactions.

Building a TSqlMapper instance

An XML document is a wonderful tool for describing a database configuration , but you can't execute XML. In order to use the SQLMap configuration and definitions in your PHP application, you need a class you can call.

The framework provides service methods that you can call which read the configuration file (and any of its definition files) and builds a TSqlMapper object. The TSqlMapper object provides access to the rest of the framework. The following example shows a singleton TMapper that is similar to the one bundled with the framework.

require_once('/path/to/SQLMap/TSqlMapper.php');
class TMapper
{
    private static $_mapper;

    public static function configure($configFile)
    {
        if(is_null(self::$_mapper))
        {
            $builder = new TDomSqlMapBuilder();
            self::$_mapper = $builder->configure($configFile);
        }
        return self::$_mapper;
    }

    public static function instance()
    {
        return self::$_mapper;
    }
}

To obtain the TSqlMapper instance, first configure the mapper once.

TMapper::configure('path/to/sqlmap.config');

The TDomSqlMapBuilder object will go throught the the sqlmap.config file and build a TSqlMapper instance. To use TSqlMapper in your application, specify one of the TSqlMapper methods. Here's an example:

$list = TMapper::instance()->queryForList("PermitNoForYearList", $values);

Multiple Databases

If you need access to more than one database from the same application, create a DataMapper configuration file for that database and another Mapper class to go with it.

TDomSqlMapBuilder Configuration Options

If you find that you already have loaded your DataMapper configuration information as a SimpleXMLElement instance within your application, the TDomSqlMapBuilder provides Configure overloads for those types as well.