[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  *
   4  * This file is part of the phpBB Forum Software package.
   5  *
   6  * @copyright (c) phpBB Limited <https://www.phpbb.com>
   7  * @license GNU General Public License, version 2 (GPL-2.0)
   8  *
   9  * For full copyright and license information, please see
  10  * the docs/CREDITS.txt file.
  11  *
  12  */
  13  
  14  namespace phpbb\db\migration;
  15  
  16  /**
  17  * Abstract base class for database migrations
  18  *
  19  * Each migration consists of a set of schema and data changes to be implemented
  20  * in a subclass. This class provides various utility methods to simplify editing
  21  * a phpBB.
  22  */
  23  abstract class migration
  24  {
  25      /** @var \phpbb\config\config */
  26      protected $config;
  27  
  28      /** @var \phpbb\db\driver\driver_interface */
  29      protected $db;
  30  
  31      /** @var \phpbb\db\tools */
  32      protected $db_tools;
  33  
  34      /** @var string */
  35      protected $table_prefix;
  36  
  37      /** @var string */
  38      protected $phpbb_root_path;
  39  
  40      /** @var string */
  41      protected $php_ext;
  42  
  43      /** @var array Errors, if any occurred */
  44      protected $errors;
  45  
  46      /** @var array List of queries executed through $this->sql_query() */
  47      protected $queries = array();
  48  
  49      /**
  50      * Constructor
  51      *
  52      * @param \phpbb\config\config $config
  53      * @param \phpbb\db\driver\driver_interface $db
  54      * @param \phpbb\db\tools $db_tools
  55      * @param string $phpbb_root_path
  56      * @param string $php_ext
  57      * @param string $table_prefix
  58      */
  59  	public function __construct(\phpbb\config\config $config, \phpbb\db\driver\driver_interface $db, \phpbb\db\tools $db_tools, $phpbb_root_path, $php_ext, $table_prefix)
  60      {
  61          $this->config = $config;
  62          $this->db = $db;
  63          $this->db_tools = $db_tools;
  64          $this->table_prefix = $table_prefix;
  65  
  66          $this->phpbb_root_path = $phpbb_root_path;
  67          $this->php_ext = $php_ext;
  68  
  69          $this->errors = array();
  70      }
  71  
  72      /**
  73      * Defines other migrations to be applied first
  74      *
  75      * @return array An array of migration class names
  76      */
  77  	static public function depends_on()
  78      {
  79          return array();
  80      }
  81  
  82      /**
  83      * Allows you to check if the migration is effectively installed (entirely optional)
  84      *
  85      * This is checked when a migration is installed. If true is returned, the migration will be set as
  86      * installed without performing the database changes.
  87      * This function is intended to help moving to migrations from a previous database updater, where some
  88      * migrations may have been installed already even though they are not yet listed in the migrations table.
  89      *
  90      * @return bool True if this migration is installed, False if this migration is not installed (checked on install)
  91      */
  92  	public function effectively_installed()
  93      {
  94          return false;
  95      }
  96  
  97      /**
  98      * Updates the database schema by providing a set of change instructions
  99      *
 100      * @return array Array of schema changes (compatible with db_tools->perform_schema_changes())
 101      */
 102  	public function update_schema()
 103      {
 104          return array();
 105      }
 106  
 107      /**
 108      * Reverts the database schema by providing a set of change instructions
 109      *
 110      * @return array Array of schema changes (compatible with db_tools->perform_schema_changes())
 111      */
 112  	public function revert_schema()
 113      {
 114          return array();
 115      }
 116  
 117      /**
 118      * Updates data by returning a list of instructions to be executed
 119      *
 120      * @return array Array of data update instructions
 121      */
 122  	public function update_data()
 123      {
 124          return array();
 125      }
 126  
 127      /**
 128      * Reverts data by returning a list of instructions to be executed
 129      *
 130      * @return array Array of data instructions that will be performed on revert
 131      *     NOTE: calls to tools (such as config.add) are automatically reverted when
 132      *         possible, so you should not attempt to revert those, this is mostly for
 133      *         otherwise unrevertable calls (custom functions for example)
 134      */
 135  	public function revert_data()
 136      {
 137          return array();
 138      }
 139  
 140      /**
 141      * Wrapper for running queries to generate user feedback on updates
 142      *
 143      * @param string $sql SQL query to run on the database
 144      * @return mixed Query result from db->sql_query()
 145      */
 146  	protected function sql_query($sql)
 147      {
 148          $this->queries[] = $sql;
 149  
 150          $this->db->sql_return_on_error(true);
 151  
 152          if ($sql === 'begin')
 153          {
 154              $result = $this->db->sql_transaction('begin');
 155          }
 156          else if ($sql === 'commit')
 157          {
 158              $result = $this->db->sql_transaction('commit');
 159          }
 160          else
 161          {
 162              $result = $this->db->sql_query($sql);
 163              if ($this->db->get_sql_error_triggered())
 164              {
 165                  $this->errors[] = array(
 166                      'sql'    => $this->db->get_sql_error_sql(),
 167                      'code'    => $this->db->get_sql_error_returned(),
 168                  );
 169              }
 170          }
 171  
 172          $this->db->sql_return_on_error(false);
 173  
 174          return $result;
 175      }
 176  
 177      /**
 178      * Get the list of queries run
 179      *
 180      * @return array
 181      */
 182  	public function get_queries()
 183      {
 184          return $this->queries;
 185      }
 186  }