<?php

/**
 * @file DatajarEngineBase.php
 *
 * @brief Basic implementation and utilities to create datajar drivers.
 *
 * Copyright © 2012 Guillaume Pasquet
 *
 * This file is part of Datajar.
 *
 * Datajar is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of
 * the License, or (at your option) any later version.
 *
 * Datajar is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Datajar.  If not, see <http://www.gnu.org/licenses/>.
 */

abstract class DatajarEngineBase
{
    /**
     * Creates the datajar object (table) associated to the object.
     */
    abstract public function create($object);

    /**
     * Saves the object into its datajar.
     */
    abstract public function save($object);

    /**
     * Escapes a string to secure it.
     */
    public static function escape($data)
    {
        return $data;
    }

    /**
     * Deletes the object from its datajar.
     */
    abstract public function delete($object);

    /**
     * Loads up the data corresponding to the object in the datajar.
     */
    abstract public function load($object, array $cond);

    /**
     * Loads objects from datajar.
     */
    abstract public function select($objecttype, array $cond, $order = false, $desc = false);

    /**
     * Runs the provided query object.
     */
    abstract public function run($query);

    /**
     * Deletes the datajar associated to the object.
     */
    abstract public function drop($object);

    /**
     * Closes the connection.
     */
    abstract public function close();

    /**
     * Logs or prints the query depending on the status of the constant
     * DB_DEBUG.
     */
    protected function log($query)
    {
        if(defined('DB_DEBUG')) {
            $logstr = date("Y-m-d H:i:s :: ") . $query . "\n";
            if(strtolower(DB_DEBUG) == 'on') {
                echo $logstr;
            }
            else if(defined('DB_LOGFILE')) {
                $fh = fopen(DB_LOGFILE, 'a');
                fwrite($fh, $logstr);
                fclose($fh);
            }
        }
    }

    /**
     * Checks that object is a storable object.
     */
    protected function is_datajar($object)
    {
        return DatajarEngineBase::does_extend($object, "DatajarBase");
    }

    /**
     * Checks that object is storable or throw an exception.
     */
    protected function require_datajar($object)
    {
        if(!DatajarEngineBase::does_extend($object, "DatajarBase")) {
            throw new DatajarException(t("Provided object is not storable."));
        }
    }

    /**
     * Determines if the given object extends DatajarTypeBase.
     */
    public static function does_extend($object, $par_name)
    {
        if(!is_object($object)) {
            return false;
        }

        $refl = null;
        try {
            $refl = new ReflectionClass($object);
        }
        catch(ReflectionException $e) {
            return false;
        }

        while($refl = $refl->getParentClass()) {
            if($refl->getName() == $par_name) {
                return true;
            }
        }

        return false;
    }

    /**
     * Convenience helper that wraps a reflection class call.
     */
    protected function obj_name($object)
    {
        $refl = new ReflectionClass($object);
        return $refl->getName();
    }

    /**
     * Parses a connection string
     */
    protected function parse_conn_string($string)
    {
        $matches = array();
        preg_match('%^[^/]+?://(?:([^/@]*?)(?::([^/@:]+?)@)?([^/@:]+?)(?::([^/@:]+?))?)?/(.+)$%',
                   $string, $matches);
        return array('username' => $matches[1],
                     'password' => $matches[2],
                     'host'     => $matches[3],
                     'port'     => $matches[4],
                     'database' => $matches[5]);
    }

    /**
     * Checks for a usable backend.
     * @returns TRUE if the backend is ready, FALSE otherwise
     */
    abstract function test_backend();
}

?>