<?php
/**
 * Klassen används för att hantera SQL frågor/querys till MySQL.<br />
 * @param String $query Själva SQL frågan som ska ställas till databasen.
 * Parametern är inte obligatorisk, det går att använda funktionen
 * newQuery($query) till att ställa SQL frågan vid ett senare tillfälle.
 * @version 3.2.1
 */
final class MySQLQuery{

    /**
     * Den SQL fråga som har ställts till databasen.
     * @var string
     */
    private $query;

    /**
     * Svaret från databasen efter att frågan är ställd.
     * @var resource
     */
    private $mysqlResource;

    /**
     * Resultatet som kommer från mysql_fetch_array
     * @var Array
     */
    private $result;

    /**
     * Error nr som frågan genererat
     * @var int
     */
    private $errorNr;

    /**
     * Error meddelandet som frågan genererat
     * @var String
     */
    private $errorMessage;

    /**
     * Hur många reder som vart påvärkade
     * @var int
     */
    private $affectedRows;

    /**
     * Returnerar det id nummer som genererades av MySQL AUTO_INCREMENT vid den
     * senaste frågan, vanligtvis INSERT, som ställdes till databasen.<br />
     * Om ingen kolumn har AUTO_INCREMENT så returneras 0 eller om frågan inte
     * genererade något id. Om ingen uppkoppling är ettablerad till databasen så
     * returneras false och en E_WARNING genereras..
     *
     * @var int
     */
    private $generatedId;

    /**
     * Konstruktor<br />
     * SQL frågan kan ställas direkt till databasen i konstruktorn om så önskas.
     *
     * @param string $query Mall för hur vi vill att SQL frågan ska se ut. SQL
     * frågan ska ha nycklar i sig med inledande kolon tecken ':'<br />
     * <br />
     * <b>Exempel:</b><br />
     * UPDATE users<br />
     * SET pass=:password:<br />
     * WHERE user=:user:<br />
     * <br />
     * I ovanstående exempel har vi två nycklar som är: 'password' och 'user'.
     * Dessa kommer vi att byta ut mot de värden som ska vara där med hjälp av
     * parametern $replaceMap.
     *
     * @param array $replaceMap Karta för vad som ska ersätta vad.<br />
     * <br />
     * <b>Exemplet:</b><br />
     * UPDATE users<br />
     * SET pass=:password:<br />
     * WHERE user=:user:<br />
     * <br />
     * ...gav oss nycklarna 'password' och 'user' som båda ska ersättas med
     * data. Vi gör så via denna parameter genom följande exempel:<br />
     * array('password' => 'hemligt',<br />
     * 'user' => 'erik')<br />
     * <br />
     * Detta kommer ersätta nycklarna med befintligt värde.<br />
     * <b>OBS!</b> heltal ska valideras för att bli behandlade som heltal i
     * SQL frågan...<br />
     * <br />
     * Godtagbara typer i fältet:<br />
     * <b>[string , string | int]</b>
     *
     * @param array $escapeWildcardsMap En valfri parameter som ska finnas med
     * om man vill escapa jokertecken som: '_' eller '%'.<br />
     * Dessa jokertecken används bara i vissa delar av MySQL queryn, så som i
     * LIKE t.ex. Det är därför inte alltid man vill escapa dessa tecken.<br />
     * Vill man göra så så så låter man en tredje parameter följa med de
     * nycklarna som key-value som man vill sätta escape till:<br />
     * array('password' => true)<br />
     * Man behöver inte sätta en fullständig karta utan bara berätta var man
     * vill sätta escape tecknen. Alla nycklarna behöver därför inte följa med i
     * denna parameter.
     * <br />
     * Användbara typer i fältet:<br />
     * <b>[string , boolean]</b>
     *
     * @see self::composeSQL
     * @see self::newQuery
     */
    public function __construct($query=null,$replaceMap=null,
            $escapeWildcardsMap=null){

        if(!empty($query))
            $this->newQuery($query,$replaceMap,$escapeWildcardsMap);
    }

    /**
     * Ställer själva frågan till MySQL och sparar svar.
     *
     * @param string $query Mall för hur vi vill att SQL frågan ska se ut. SQL
     * frågan ska ha nycklar i sig med inledande kolon tecken ':'<br />
     * <br />
     * <b>Exempel:</b><br />
     * UPDATE users<br />
     * SET pass=:password:<br />
     * WHERE user=:user:<br />
     * <br />
     * I ovanstående exempel har vi två nycklar som är: 'password' och 'user'.
     * Dessa kommer vi att byta ut mot de värden som ska vara där med hjälp av
     * parametern $replaceMap.
     *
     * @param array $replaceMap Karta för vad som ska ersätta vad.<br />
     * <br />
     * <b>Exemplet:</b><br />
     * UPDATE users<br />
     * SET pass=:password:<br />
     * WHERE user=:user:<br />
     * <br />
     * ...gav oss nycklarna 'password' och 'user' som båda ska ersättas med
     * data. Vi gör så via denna parameter genom följande exempel:<br />
     * array('password' => 'hemligt',<br />
     * 'user' => 'erik')<br />
     * <br />
     * Detta kommer ersätta nycklarna med befintligt värde.<br />
     * <b>OBS!</b> heltal ska valideras för att bli behandlade som heltal i
     * SQL frågan...<br />
     * <br />
     * Godtagbara typer i fältet:<br />
     * <b>[string , string | int]</b>
     *
     * @param array $escapeWildcardsMap En valfri parameter som ska finnas med
     * om man vill escapa jokertecken som: '_' eller '%'.<br />
     * Dessa jokertecken används bara i vissa delar av MySQL queryn, så som i
     * LIKE t.ex. Det är därför inte alltid man vill escapa dessa tecken.<br />
     * Vill man göra så så så låter man en tredje parameter följa med de
     * nycklarna som key-value som man vill sätta escape till:<br />
     * array('password' => true)<br />
     * Man behöver inte sätta en fullständig karta utan bara berätta var man
     * vill sätta escape tecknen. Alla nycklarna behöver därför inte följa med i
     * denna parameter.
     * <br />
     * Användbara typer i fältet:<br />
     * <b>[string , boolean]</b>
     *
     * @return void
     * @see self::composeSQL
     */
    public function newQuery($query,$replaceMap=null,$escapeWildcardsMap=null){

        $query = self::composeSQL($query,$replaceMap,$escapeWildcardsMap);

        $this->mysqlResource    = mysql_query($query);
        $this->query            = $query;
        $this->errorNr          = mysql_errno();
        $this->errorMessage     = mysql_error();
        $this->affectedRows     = mysql_affected_rows();
        $this->generatedId      = mysql_insert_id();
    }

    /**
     * Ställer en enkel fråga till MySQL utan att spara svar.
     *
     * @param string $query Mall för hur vi vill att SQL frågan ska se ut. SQL
     * frågan ska ha nycklar i sig med inledande kolon tecken ':'<br />
     * <br />
     * <b>Exempel:</b><br />
     * UPDATE users<br />
     * SET pass=:password:<br />
     * WHERE user=:user:<br />
     * <br />
     * I ovanstående exempel har vi två nycklar som är: 'password' och 'user'.
     * Dessa kommer vi att byta ut mot de värden som ska vara där med hjälp av
     * parametern $replaceMap.
     *
     * @param array $replaceMap Karta för vad som ska ersätta vad.<br />
     * <br />
     * <b>Exemplet:</b><br />
     * UPDATE users<br />
     * SET pass=:password:<br />
     * WHERE user=:user:<br />
     * <br />
     * ...gav oss nycklarna 'password' och 'user' som båda ska ersättas med
     * data. Vi gör så via denna parameter genom följande exempel:<br />
     * array('password' => 'hemligt',<br />
     * 'user' => 'erik')<br />
     * <br />
     * Detta kommer ersätta nycklarna med befintligt värde.<br />
     * <b>OBS!</b> heltal ska valideras för att bli behandlade som heltal i
     * SQL frågan...<br />
     * <br />
     * Godtagbara typer i fältet:<br />
     * <b>[string , string | int]</b>
     *
     * @param array $escapeWildcardsMap En valfri parameter som ska finnas med
     * om man vill escapa jokertecken som: '_' eller '%'.<br />
     * Dessa jokertecken används bara i vissa delar av MySQL queryn, så som i
     * LIKE t.ex. Det är därför inte alltid man vill escapa dessa tecken.<br />
     * Vill man göra så så så låter man en tredje parameter följa med de
     * nycklarna som key-value som man vill sätta escape till:<br />
     * array('password' => true)<br />
     * Man behöver inte sätta en fullständig karta utan bara berätta var man
     * vill sätta escape tecknen. Alla nycklarna behöver därför inte följa med i
     * denna parameter.
     * <br />
     * Användbara typer i fältet:<br />
     * <b>[string , boolean]</b>
     *
     * @return void
     * @see self::composeSQL
     */
    public static function simpleQuery($query,$replaceMap=null,$escapeWildcardsMap=null){
        // Sätter ihop frågan säkert
        $query = self::composeSQL($query,$replaceMap,$escapeWildcardsMap);
        // Ställer frågan
        $mysqlResource = mysql_query($query);
        // Frigör minnet
        if(is_resource($mysqlResource))
            mysql_free_result($mysqlResource);
    }

    /**
     * Funktionen används för att motverka SQL injections...
     *
     * @param string $query Mall för hur vi vill att SQL frågan ska se ut. SQL
     * frågan ska ha nycklar i sig med inledande kolon tecken ':'<br />
     * <br />
     * <b>Exempel:</b><br />
     * UPDATE users<br />
     * SET pass=:password:<br />
     * WHERE user=:user:<br />
     * <br />
     * I ovanstående exempel har vi två nycklar som är: 'password' och 'user'.
     * Dessa kommer vi att byta ut mot de värden som ska vara där med hjälp av
     * parametern $replaceMap.
     *
     * @param array $replaceMap Karta för vad som ska ersätta vad.<br />
     * <br />
     * <b>Exemplet:</b><br />
     * UPDATE users<br />
     * SET pass=:password:<br />
     * WHERE user=:user:<br />
     * <br />
     * ...gav oss nycklarna 'password' och 'user' som båda ska ersättas med
     * data. Vi gör så via denna parameter genom följande exempel:<br />
     * array('password' => 'hemligt',<br />
     * 'user' => 'erik')<br />
     * <br />
     * Detta kommer ersätta nycklarna med befintligt värde.<br />
     * <b>OBS!</b> heltal ska valideras för att bli behandlade som heltal i
     * SQL frågan...<br />
     * <br />
     * Godtagbara typer i fältet:<br />
     * <b>[string , string | int]</b>
     *
     * @param array $escapeWildcardsMap En valfri parameter som ska finnas med
     * om man vill escapa jokertecken som: '_' eller '%'.<br />
     * Dessa jokertecken används bara i vissa delar av MySQL queryn, så som i
     * LIKE t.ex. Det är därför inte alltid man vill escapa dessa tecken.<br />
     * Vill man göra så så så låter man en tredje parameter följa med de
     * nycklarna som key-value som man vill sätta escape till:<br />
     * array('password' => true)<br />
     * Man behöver inte sätta en fullständig karta utan bara berätta var man
     * vill sätta escape tecknen. Alla nycklarna behöver därför inte följa med i
     * denna parameter.
     * <br />
     * Användbara typer i fältet:<br />
     * <b>[string , boolean]</b>
     *
     * @static
     * @return string
     */
    private static function composeSQL($query,$replaceMap=array(),
            $escapeWildcardsMap=null){

        $keys    = array();
        $replace = array();

        if(count($replaceMap) > 0)
            foreach($replaceMap as $key => $value){
                $keys[] = ':'.$key.':';
                switch(strtolower(gettype($value))){
                    case 'string':
                        // Motverkar dubbel escaping
                        $value = self::antiMagicQuotes($value);

                        // Om användaren vill escapa jokertecken
                        if(isset($escapeWildcardsMap[$key]))
                            if(is_bool($escapeWildcardsMap[$key]))
                                if($escapeWildcardsMap[$key])
                                    $value = self::escapeWildcards($value);

                        // Escapar stringen så att den är säker i databasen
                        $replace[] = "'".mysql_real_escape_string($value)."'";
                        break;
                    case 'integer':
                        $replace[] = (string)$value;
                        break;
                    case 'boolean':
                        if($value)
                            $replace[] = 'true';
                        else
                            $replace[] = 'false';
                        break;
                    case 'null':
                            $replace[] = 'NULL';
                        break;
                    default :
                        exit('ogiltligt värde till SQL fråga');
                }
            }

        return str_replace($keys, $replace, $query);
    }

    /**
     * Om magic_quotes_sybase eller magic_quotes_gpc är påslagan av någon dum
     * anledning så strippas parametern från de backslashes som dessa har
     * genererat...
     * @param string $string Den sträng som ska användas i databasfråga
     * @return string
     */
    private static function antiMagicQuotes($string) {
        if(get_magic_quotes_gpc())
            $string = stripslashes($string);
        return $string;
    }

    /**
     * Escape'ar de jokertecken som är relevanta i vissa frågor i MySQL.
     * @param string $string Den sträng som ska användas i databasfråga
     * @return string
     */
    private static function escapeWildcards($string){
        return str_replace(array('_','%'),array('\\_','\\%'),$string);
    }

    /**
     * Används för att hämta rad för rad från MySQL. Returnerar true om det
     * finns fler rader att hämta och false ifall det inte finns det.
     * @return boolean
     */
    public function fetchArray(){
        return ($this->result = @mysql_fetch_array($this->mysqlResource));
    }

    /**
     * Används för att hämta ett fält från resultatet. <br />
     * OBS! Kalla på funktionen 'fetchArray' först.
     * @param String $key Kolumnnamnet som eftersöks.
     * @return string
     */
    public function field($key){
        return $this->result[$key];
    }

    /**
     * Returnerar den ställda frågan
     * @return string
     */
    public function getQuery(){
        return $this->query;
    }

    /**
     * Returnerar resultatet från den ställda frågan
     * @return array
     */
    public function getResult(){
        return $this->result;
    }

    /**
     * Returnerar eventuellt genererat error nummer
     * @return int
     */
    public function getErrorNr(){
        return $this->errorNr;
    }

    /**
     * Returnerar error medelandet
     * @return string
     */
    public function getErrorMessage(){
        return $this->errorMessage;
    }

    /**
     * Returnerar hur många rader som var påvärkade
     * @return int
     */
    public function getAffectedRows(){
        return $this->affectedRows;
    }

    /**
     * Frigör minnet från resultatet
     * @return void
     */
    public function freeResult(){
        mysql_free_result($this->mysqlResource);
    }

    /**
     * Returnerar en väl beskriven förklaring av
     * vad som har gott fel, om något har gott fel
     * @return string
     */
    public function errorInfo(){
        $errorInfo;
        if(!empty($this->errorMessage) || !empty($this->errorNr)){
            $errorInfo = (nl2br('<pre>
            MySQL query = '.$this->query.'

            MySQL error nr = '.$this->errorNr.'

            MySQL error medelande:
            '.$this->errorMessage.'
            </pre>'));
        }
        else{
            $errorInfo = (nl2br('Inget fel medelande registrerat
            Påvärkade rader = '.$this->affectedRows));
        }

        return $errorInfo;
    }

    /**
     * Returnerar false om det inte har uppstott något fel i MySQL frågan <br />
     * Returnerar annars true om fel uppstod
     * @return boolean
     */
    public function error(){
        return $this->errorNr != 0;
    }

    /**
     * Returnerar det id nummer som genererades av MySQL AUTO_INCREMENT då
     * frågan ställdes, vanligtvis INSERT, till databasen.<br />
     * Om ingen kolumn har AUTO_INCREMENT eller om frågan inte genererade något
     * id så returneras 0...
     * @return int
     * @see mysql_insert_id()
     */
    public function getGeneratedId(){
        return $this->generatedId;
    }

    /**
     * Tömmer eventuell resurce
     */
    public function  __destruct() {
        if(is_resource($this->mysqlResource))
            $this->freeResult();
    }
}