xref: /plugin/sqlite/helper.php (revision d0a5ba7ae2c780ae7f13d185722582499bff7c71)

<?php

/**
 * @noinspection SqlNoDataSourceInspection
 * @noinspection SqlDialectInspection
 * @noinspection PhpComposerExtensionStubsInspection
 */

use dokuwiki\plugin\sqlite\SQLiteDB;
use dokuwiki\plugin\sqlite\Tools;


/**
 * DokuWiki Plugin sqlite (Helper Component)
 *
 * @license GPL 2 http://www.gnu.org/licenses/gpl-2.0.html
 * @author  Andreas Gohr <gohr@cosmocode.de>
 * @deprecated 2023-03-15
 */
class helper_plugin_sqlite extends DokuWiki_Plugin
{
    /** @var SQLiteDB|null */
    protected $adapter = null;

    /** @var array result cache */
    protected $data;

    /**
     * constructor
     */
    public function __construct()
    {
        if (!$this->existsPDOSqlite()) {
            msg('PDO SQLite support missing in this PHP install - The sqlite plugin will not work', -1);
        }
    }

    /**
     * Get the current Adapter
     * @return SQLiteDB|null
     */
    public function getAdapter()
    {
        return $this->adapter;
    }

    /**
     * Keep separate instances for every call to keep database connections
     */
    public function isSingleton()
    {
        return false;
    }

    /**
     * check availabilty of PHP PDO sqlite3
     */
    public function existsPDOSqlite()
    {
        if (class_exists('pdo')) {
            return in_array('sqlite', \PDO::getAvailableDrivers());
        }
        return false;
    }

    /**
     * Initializes and opens the database
     *
     * Needs to be called right after loading this helper plugin
     *
     * @param string $dbname
     * @param string $updatedir - Database update infos
     * @return bool
     */
    public function init($dbname, $updatedir)
    {
        if(!DOKU_UNITTEST) { // for now we don't want to trigger the deprecation warning in the tests
            dbg_deprecated(SQLiteDB::class);
        }

        try {
            $this->adapter = new SQLiteDB($dbname, $updatedir, $this);
        } catch (Exception $e) {
            msg('SQLite: ' . $e->getMessage(), -1);
            return false;
        }
        return true;
    }

    /**
     * This is called from the adapter itself for backwards compatibility
     *
     * @param SQLiteDB $adapter
     * @return void
     */
    function setAdapter($adapter)
    {
        $this->adapter = $adapter;
    }

    /**
     * Registers a User Defined Function for use in SQL statements
     */
    public function create_function($function_name, $callback, $num_args)
    {
        $this->adapter->pdo()->sqliteCreateFunction($function_name, $callback, $num_args);
    }

    // region query and result handling functions

    /**
     * Convenience function to run an INSERT OR REPLACE operation
     *
     * The function takes a key-value array with the column names in the key and the actual value in the value,
     * build the appropriate query and executes it.
     *
     * @param string $table the table the entry should be saved to (will not be escaped)
     * @param array $entry A simple key-value pair array (only values will be escaped)
     * @return bool
     */
    public function storeEntry($table, $entry)
    {
        try {
            $this->adapter->saveRecord($table, $entry);
        } catch (\Exception $e) {
            msg('SQLite: ' . $e->getMessage(), -1);
            return false;
        }

        return true;
    }

    /**
     * Execute a query with the given parameters.
     *
     * Takes care of escaping
     *
     *
     * @param string ...$args - the arguments of query(), the first is the sql and others are values
     */
    public function query()
    {
        // get function arguments
        $args = func_get_args();
        $sql = array_shift($args);

        try {
            return $this->adapter->query($sql, $args);
        } catch (\Exception $e) {
            msg('SQLite: ' . $e->getMessage(), -1);
            return false;
        }
    }


    /**
     * Closes the result set (and it's cursors)
     *
     * If you're doing SELECT queries inside a TRANSACTION, be sure to call this
     * function on all your results sets, before COMMITing the transaction.
     *
     * Also required when not all rows of a result are fetched
     *
     * @param \PDOStatement $res
     * @return bool
     */
    public function res_close($res)
    {
        if (!$res) return false;

        return $res->closeCursor();
    }

    /**
     * Returns a complete result set as array
     *
     * @param \PDOStatement $res
     * @return array
     */
    public function res2arr($res, $assoc = true)
    {
        if (!$res) return [];

        // this is a bullshit workaround for having res2arr and res2count work on one result
        if (!$this->data) {
            $mode = $assoc ? PDO::FETCH_ASSOC : PDO::FETCH_NUM;
            $this->data = $res->fetchAll($mode);
        }
        return $this->data;
    }

    /**
     * Return the next row from the result set as associative array
     *
     * @param \PDOStatement $res
     * @param int $rownum will be ignored
     */
    public function res2row($res, $rownum = 0)
    {
        if (!$res) return false;

        return $res->fetch(\PDO::FETCH_ASSOC);
    }

    /**
     * Return the first value from the next row.
     *
     * @param \PDOStatement $res
     * @return mixed
     */
    public function res2single($res)
    {
        if (!$res) return false;

        $data = $res->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_ABS, 0);
        if (empty($data)) {
            return false;
        }
        return $data[0];
    }

    /**
     * fetch the next row as zero indexed array
     *
     * @param \PDOStatement $res
     * @return array|bool
     */
    public function res_fetch_array($res)
    {
        if (!$res) return false;

        return $res->fetch(PDO::FETCH_NUM);
    }

    /**
     * fetch the next row as assocative array
     *
     * @param \PDOStatement $res
     * @return array|bool
     */
    public function res_fetch_assoc($res)
    {
        if (!$res) return false;

        return $res->fetch(PDO::FETCH_ASSOC);
    }

    /**
     * Count the number of records in result
     *
     * This function is really inperformant in PDO and should be avoided!
     *
     * @param \PDOStatement $res
     * @return int
     */
    public function res2count($res)
    {
        if (!$res) return 0;

        // this is a bullshit workaround for having res2arr and res2count work on one result
        if (!$this->data) {
            $this->data = $this->res2arr($res);
        }

        return count($this->data);
    }

    /**
     * Count the number of records changed last time
     *
     * @param \PDOStatement $res
     * @return int
     */
    public function countChanges($res)
    {
        if (!$res) return 0;

        return $res->rowCount();
    }

    // endregion

    // region quoting/escaping functions

    /**
     * Join the given values and quote them for SQL insertion
     */
    public function quote_and_join($vals, $sep = ',')
    {
        $vals = array_map([$this->adapter->pdo(), 'quote'], $vals);
        return join($sep, $vals);
    }

    /**
     * Quotes a string, by escaping it and adding quotes
     */
    public function quote_string($string)
    {
        return $this->adapter->pdo()->quote($string);
    }

    /**
     * Similar to quote_string, but without the quotes, useful to construct LIKE patterns
     */
    public function escape_string($str)
    {
        return trim($this->adapter->pdo()->quote($str), "'");
    }

    // endregion

    // region speciality functions

    /**
     * Split sql queries on semicolons, unless when semicolons are quoted
     *
     * Usually you don't need this. It's only really needed if you need individual results for
     * multiple queries. For example in the admin interface.
     *
     * @param string $sql
     * @return array sql queries
     * @deprecated
     */
    public function SQLstring2array($sql)
    {
        if(!DOKU_UNITTEST) { // for now we don't want to trigger the deprecation warning in the tests
            dbg_deprecated(Tools::class . '::SQLstring2array');
        }
        return Tools::SQLstring2array($sql);
    }

    /**
     * @deprecated needs to be fixed in stuct and structpublish
     */
    public function doTransaction($sql, $sqlpreparing = true) {
        throw new \Exception(
            'This method seems to never have done what it suggests. Please use the query() function instead.'
        );
    }

    // endregion
}