lib/dtl/database_exporter.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * General database export class
  19  *
  20  * @package    core_dtl
  21  * @copyright  2008 Andrei Bautu
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 /**
  28  * Base class for database export operations. This class defines basic callbacks
  29  * for export operations and implements the @see export_database and
  30  * @export_table methods generic export processing. In general, subclasses will
  31  * override callback methods to provide specific output and (optionally)
  32  * @see export_database to add functionality.
  33  * Between a single pair of calls to @see begin_database_export and
  34  * @see finish_database_export, multiple non-overlapping pairs of calls may
  35  * be made to @see begin_table_export and @see finish_database_export for
  36  * different tables. Between one pair of calls to @see begin_table_export and
  37  * @see finish_database_export multiple calls may be made to
  38  * @see export_table_data for the same table.
  39  */
  40 abstract class database_exporter {
  41     /** @var moodle_database Connection to the source database (a @see moodle_database object). */
  42     protected $mdb;
  43     /** @var database_manager Database manager of the source database (a @see database_manager object). */
  44     protected $manager;
  45     /** @var xmldb_structure Source database schema in XMLDB format (a @see xmldb_structure object). */
  46     protected $schema;
  47     /**
  48      * Boolean flag - whether or not to check that XML database schema matches
  49      * the RDBMS database schema before exporting (used by
  50      * @see export_database).
  51      * @var bool
  52      */
  53     protected $check_schema;
  54
  55     /**
  56      * Object constructor.
  57      *
  58      * @param moodle_database $mdb Connection to the source database (a
  59      * @see moodle_database object).
  60      * @param boolean $check_schema - whether or not to check that XML database
  61      * schema matches the RDBMS database schema before exporting (used by
  62      * @see export_database).
  63      */
  64     public function __construct(moodle_database $mdb, $check_schema=true) {
  65         $this->mdb          = $mdb;
  66         $this->manager      = $mdb->get_manager();
  67         $this->schema       = $this->manager->get_install_xml_schema();
  68         $this->check_schema = $check_schema;
  69     }
  70
  71     /**
  72      * Callback function. Should be called only once database per export
  73      * operation, before any other export operations. Subclasses should export
  74      * basic database information (version and timestamp).
  75      *
  76      * @param float $version the version of the system which generating the data
  77      * @param string $release moodle release info
  78      * @param string $timestamp the timestamp of the data (in ISO 8601) format.
  79      * @param string $description a user description of the data.
  80      * @return void
  81      */
  82     public abstract function begin_database_export($version, $release, $timestamp, $description);
  83
  84     /**
  85      * Callback function. Should be called only once per table export operation,
  86      * before any other table export operations. Subclasses should export
  87      * basic database information (name and schema's hash).
  88      *
  89      * @param xmldb_table $table - XMLDB object for the exported table
  90      * @return void
  91      */
  92     public abstract function begin_table_export(xmldb_table $table);
  93
  94     /**
  95      * Callback function. Should be called only once per table export operation,
  96      * after all other table export operations.
  97      *
  98      * @param xmldb_table $table - XMLDB object for the exported table
  99      */
 100     public abstract function finish_table_export(xmldb_table $table);
 101
 102     /**
 103      * Callback function. Should be called only once database per export
 104      * operation, after all database export operations.
 105      */
 106     public abstract function finish_database_export();
 107
 108     /**
 109      * Callback function. Should be called only once per record export operation,
 110      * only between @see begin_table_export and @see finish_table_export calls.
 111      * It will insert table data. Subclasses should export basic record
 112      * information (data values).
 113      *
 114      * @param xmldb_table $table - XMLDB object of the table from which data was retrieved
 115      * @param object $data - data object (fields and values from record)
 116      * @return void
 117      */
 118     public abstract function export_table_data(xmldb_table $table, $data);
 119
 120     /**
 121      * Generic method to export the database. It checks the schema (if
 122      * @see $check_schema is true), queries the database and calls
 123      * appropriate callbacks.
 124      *
 125      * @throws dbtransfer_exception if any checking (e.g. database schema) fails
 126      *
 127      * @param string $description a user description of the data.
 128      */
 129     public function export_database($description=null) {
 130         global $CFG;
 131
 132         $options = array('changedcolumns' => false); // Column types may be fixed by transfer.
 133         if ($this->check_schema and $errors = $this->manager->check_database_schema($this->schema, $options)) {
 134             $details = '';
 135             foreach ($errors as $table=>$items) {
 136                 $details .= '<div>'.get_string('tablex', 'dbtransfer', $table);
 137                 $details .= '<ul>';
 138                 foreach ($items as $item) {
 139                     $details .= '<li>'.$item.'</li>';
 140                 }
 141                 $details .= '</ul></div>';
 142             }
 143             throw new dbtransfer_exception('exportschemaexception', $details);
 144         }
 145         $tables = $this->schema->getTables();
 146         $this->begin_database_export($CFG->version, $CFG->release, date('c'), $description);
 147         foreach ($tables as $table) {
 148             $rs = $this->mdb->export_table_recordset($table->getName());
 149             if (!$rs) {
 150                 throw new ddl_table_missing_exception($table->getName());
 151             }
 152             $this->begin_table_export($table);
 153             foreach ($rs as $row) {
 154                 $this->export_table_data($table, $row);
 155             }
 156             $this->finish_table_export($table);
 157             $rs->close();
 158         }
 159         $this->finish_database_export();
 160     }
 161 }