Source for file changeitem.php

Documentation is available at changeitem.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Libraries
  4.  * @subpackage  Schema
  5.  *
  6.  * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
  7.  * @license     GNU General Public License version 2 or later; see LICENSE
  8.  */
  9.  
  10. defined('JPATH_PLATFORM') or die;
  11.  
  12. /**
  13.  * Each object represents one query, which is one line from a DDL SQL query.
  14.  * This class is used to check the site's database to see if the DDL query has been run.
  15.  * If not, it provides the ability to fix the database by re-running the DDL query.
  16.  * The queries are parsed from the update files in the folder
  17.  * administrator/components/com_admin/sql/updates/<database>.
  18.  * These updates are run automatically if the site was updated using com_installer.
  19.  * However, it is possible that the program files could be updated without udpating
  20.  * the database (for example, if a user just copies the new files over the top of an
  21.  * existing installation).
  22.  *
  23.  * This is an abstract class. We need to extend it for each database and add a
  24.  * buildCheckQuery() method that creates the query to check that a DDL query has been run.
  25.  *
  26.  * @package     Joomla.Libraries
  27.  * @subpackage  Schema
  28.  * @since       2.5
  29.  */
  30. abstract class JSchemaChangeitem
  31. {
  32.     /**
  33.      * Update file: full path file name where query was found
  34.      *
  35.      * @var    string 
  36.      * @since  2.5
  37.      */
  38.     public $file = null;
  39.  
  40.     /**
  41.      * Update query: query used to change the db schema (one line from the file)
  42.      *
  43.      * @var    string 
  44.      * @since  2.5
  45.      */
  46.     public $updateQuery = null;
  47.  
  48.     /**
  49.      * Check query: query used to check the db schema
  50.      *
  51.      * @var    string 
  52.      * @since  2.5
  53.      */
  54.     public $checkQuery = null;
  55.  
  56.     /**
  57.      * Check query result: expected result of check query if database is up to date
  58.      *
  59.      * @var    string 
  60.      * @since  2.5
  61.      */
  62.     public $checkQueryExpected = 1;
  63.  
  64.     /**
  65.      * JDatabaseDriver object
  66.      *
  67.      * @var    JDatabaseDriver 
  68.      * @since  2.5
  69.      */
  70.     public $db = null;
  71.  
  72.     /**
  73.      * Query type: To be used in building a language key for a
  74.      * message to tell user what was checked / changed
  75.      * Possible values: ADD_TABLE, ADD_COLUMN, CHANGE_COLUMN_TYPE, ADD_INDEX
  76.      *
  77.      * @var    string 
  78.      * @since  2.5
  79.      */
  80.     public $queryType = null;
  81.  
  82.     /**
  83.      * Array with values for use in a JText::sprintf statment indicating what was checked
  84.      *
  85.      * Tells you what the message should be, based on which elements are defined, as follows:
  86.      *     For ADD_TABLE: table
  87.      *     For ADD_COLUMN: table, column
  88.      *     For CHANGE_COLUMN_TYPE: table, column, type
  89.      *     For ADD_INDEX: table, index
  90.      *
  91.      * @var    array 
  92.      * @since  2.5
  93.      */
  94.     public $msgElements = array();
  95.  
  96.     /**
  97.      * Checked status
  98.      *
  99.      * @var    integer   0=not checked, -1=skipped, -2=failed, 1=succeeded
  100.      * @since  2.5
  101.      */
  102.     public $checkStatus = 0;
  103.  
  104.     /**
  105.      * Rerun status
  106.      *
  107.      * @var    int   0=not rerun, -1=skipped, -2=failed, 1=succeeded
  108.      * @since  2.5
  109.      */
  110.     public $rerunStatus = 0;
  111.  
  112.     /**
  113.      * Constructor: builds check query and message from $updateQuery
  114.      *
  115.      * @param   JDatabaseDriver  $db     Database connector object
  116.      * @param   string           $file   Full path name of the sql file
  117.      * @param   string           $query  Text of the sql query (one line of the file)
  118.      *
  119.      * @since   2.5
  120.      */
  121.     public function __construct($db, $file, $query)
  122.     {
  123.         $this->updateQuery = $query;
  124.         $this->file = $file;
  125.         $this->db = $db;
  126.         $this->buildCheckQuery();
  127.     }
  128.  
  129.     /**
  130.      * Returns a reference to the JSchemaChangeitem object.
  131.      *
  132.      * @param   JDatabaseDriver  $db     Database connector object
  133.      * @param   string           $file   Full path name of the sql file
  134.      * @param   string           $query  Text of the sql query (one line of the file)
  135.      *
  136.      * @return  JSchemaChangeitem instance based on the database driver
  137.      *
  138.      * @since   2.5
  139.      * @throws  RuntimeException if class for database driver not found
  140.      */
  141.     public static function getInstance($db, $file, $query)
  142.     {
  143.         // Get the class name
  144.         $dbname = $db->name;
  145.  
  146.         if ($dbname == 'mysqli')
  147.         {
  148.             $dbname = 'mysql';
  149.         }
  150.         elseif ($dbname == 'sqlazure')
  151.         {
  152.             $dbname = 'sqlsrv';
  153.         }
  154.  
  155.         $class = 'JSchemaChangeitem' . ucfirst($dbname);
  156.  
  157.         // If the class exists, return it.
  158.         if (class_exists($class))
  159.         {
  160.             return new $class($db, $file, $query);
  161.         }
  162.  
  163.         throw new RuntimeException(sprintf('JSchemaChangeitem child class not found for the %s database driver', $dbname), 500);
  164.     }
  165.  
  166.     /**
  167.      * Checks a DDL query to see if it is a known type
  168.      * If yes, build a check query to see if the DDL has been run on the database.
  169.      * If successful, the $msgElements, $queryType, $checkStatus and $checkQuery fields are populated.
  170.      * The $msgElements contains the text to create the user message.
  171.      * The $checkQuery contains the SQL query to check whether the schema change has
  172.      * been run against the current database. The $queryType contains the type of
  173.      * DDL query that was run (for example, CREATE_TABLE, ADD_COLUMN, CHANGE_COLUMN_TYPE, ADD_INDEX).
  174.      * The $checkStatus field is set to zero if the query is created
  175.      *
  176.      * If not successful, $checkQuery is empty and , and $checkStatus is -1.
  177.      * For example, this will happen if the current line is a non-DDL statement.
  178.      *
  179.      * @return void 
  180.      *
  181.      * @since  2.5
  182.      */
  183.     abstract protected function buildCheckQuery();
  184.  
  185.     /**
  186.      * Runs the check query and checks that 1 row is returned
  187.      * If yes, return true, otherwise return false
  188.      *
  189.      * @return  boolean  true on success, false otherwise
  190.      *
  191.      * @since  2.5
  192.      */
  193.     public function check()
  194.     {
  195.         $this->checkStatus = -1;
  196.         if ($this->checkQuery)
  197.         {
  198.             $this->db->setQuery($this->checkQuery);
  199.             $rows = $this->db->loadObject();
  200.             if ($rows !== false)
  201.             {
  202.                 if (count($rows) === $this->checkQueryExpected)
  203.                 {
  204.                     $this->checkStatus = 1;
  205.                 }
  206.                 else
  207.                 {
  208.                     $this->checkStatus = -2;
  209.                 }
  210.             }
  211.             else
  212.             {
  213.                 $this->checkStatus = -2;
  214.             }
  215.         }
  216.         return $this->checkStatus;
  217.     }
  218.  
  219.     /**
  220.      * Runs the update query to apply the change to the database
  221.      *
  222.      * @return  void 
  223.      *
  224.      * @since   2.5
  225.      */
  226.     public function fix()
  227.     {
  228.         if ($this->checkStatus === -2)
  229.         {
  230.             // At this point we have a failed query
  231.             $this->db->setQuery($this->updateQuery);
  232.             if ($this->db->execute())
  233.             {
  234.                 if ($this->check())
  235.                 {
  236.                     $this->checkStatus = 1;
  237.                     $this->rerunStatus = 1;
  238.                 }
  239.                 else
  240.                 {
  241.                     $this->rerunStatus = -2;
  242.                 }
  243.             }
  244.             else
  245.             {
  246.                 $this->rerunStatus = -2;
  247.             }
  248.         }
  249.     }
  250. }

Documentation generated on Tue, 19 Nov 2013 14:55:39 +0100 by phpDocumentor 1.4.3