lib/xmldb/classes/XMLDBStructure.class.php

   1 <?php // $Id$
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 //                                                                       //
   5 // NOTICE OF COPYRIGHT                                                   //
   6 //                                                                       //
   7 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   8 //          http://moodle.com                                            //
   9 //                                                                       //
  10 // Copyright (C) 1999 onwards Martin Dougiamas        http://dougiamas.com  //
  11 //           (C) 2001-3001 Eloy Lafuente (stronk7) http://contiento.com  //
  12 //                                                                       //
  13 // This program is free software; you can redistribute it and/or modify  //
  14 // it under the terms of the GNU General Public License as published by  //
  15 // the Free Software Foundation; either version 2 of the License, or     //
  16 // (at your option) any later version.                                   //
  17 //                                                                       //
  18 // This program is distributed in the hope that it will be useful,       //
  19 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  20 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  21 // GNU General Public License for more details:                          //
  22 //                                                                       //
  23 //          http://www.gnu.org/copyleft/gpl.html                         //
  24 //                                                                       //
  25 ///////////////////////////////////////////////////////////////////////////
  26
  27 /// This class represent one XMLDB structure
  28
  29 class XMLDBStructure extends XMLDBObject {
  30
  31     var $path;
  32     var $version;
  33     var $tables;
  34     var $statements;
  35
  36     /**
  37      * Creates one new XMLDBStructure
  38      */
  39     function XMLDBStructure($name) {
  40         parent::XMLDBObject($name);
  41         $this->path = NULL;
  42         $this->version = NULL;
  43         $this->tables = array();
  44         $this->statements = array();
  45     }
  46
  47     /**
  48      * Returns the path of the structure
  49      */
  50     function getPath() {
  51         return $this->path;
  52     }
  53
  54     /**
  55      * Returns the version of the structure
  56      */
  57     function getVersion() {
  58         return $this->version;
  59     }
  60
  61     /**
  62      * Returns one XMLDBTable
  63      */
  64     function &getTable($tablename) {
  65         $i = $this->findTableInArray($tablename);
  66         if ($i !== NULL) {
  67             return $this->tables[$i];
  68         }
  69         $null = NULL;
  70         return $null;
  71     }
  72
  73     /**
  74      * Returns the position of one table in the array.
  75      */
  76     function &findTableInArray($tablename) {
  77         foreach ($this->tables as $i => $table) {
  78             if ($tablename == $table->getName()) {
  79                 return $i;
  80             }
  81         }
  82         $null = NULL;
  83         return $null;
  84     }
  85
  86     /**
  87      * Returns the position of one statement in the array.
  88      */
  89     function &findStatementInArray($statementname) {
  90         foreach ($this->statements as $i => $statement) {
  91             if ($statementname == $statement->getName()) {
  92                 return $i;
  93             }
  94         }
  95         $null = NULL;
  96         return $null;
  97     }
  98
  99     /**
 100      * This function will reorder the array of tables
 101      */
 102     function orderTables() {
 103         $result = $this->orderElements($this->tables);
 104         if ($result) {
 105             $this->setTables($result);
 106             return true;
 107         } else {
 108             return false;
 109         }
 110     }
 111
 112     /**
 113      * This function will reorder the array of statements
 114      */
 115     function orderStatements() {
 116         $result = $this->orderElements($this->statements);
 117         if ($result) {
 118             $this->setStatements($result);
 119             return true;
 120         } else {
 121             return false;
 122         }
 123     }
 124
 125     /**
 126      * Returns the tables of the structure
 127      */
 128     function &getTables() {
 129         return $this->tables;
 130     }
 131
 132     /**
 133      * Returns one XMLDBStatement
 134      */
 135     function &getStatement($statementname) {
 136         $i = $this->findStatementInArray($statementname);
 137         if ($i !== NULL) {
 138             return $this->statements[$i];
 139         }
 140         $null = NULL;
 141         return $null;
 142     }
 143
 144     /**
 145      * Returns the statements of the structure
 146      */
 147     function &getStatements() {
 148         return $this->statements;
 149     }
 150
 151     /**
 152      * Set the structure version
 153      */
 154     function setVersion($version) {
 155         $this->version = $version;
 156     }
 157
 158     /**
 159      * Add one table to the structure, allowing to specify the desired order
 160      * If it's not specified, then the table is added at the end.
 161      */
 162     function addTable(&$table, $after=NULL) {
 163
 164     /// Calculate the previous and next tables
 165         $prevtable = NULL;
 166         $nexttable = NULL;
 167
 168         if (!$after) {
 169             $alltables =& $this->getTables();
 170             if ($alltables) {
 171                 end($alltables);
 172                 $prevtable =& $alltables[key($alltables)];
 173             }
 174         } else {
 175             $prevtable =& $this->getTable($after);
 176         }
 177         if ($prevtable && $prevtable->getNext()) {
 178             $nexttable =& $this->getTable($prevtable->getNext());
 179         }
 180
 181     /// Set current table previous and next attributes
 182         if ($prevtable) {
 183             $table->setPrevious($prevtable->getName());
 184             $prevtable->setNext($table->getName());
 185         }
 186         if ($nexttable) {
 187             $table->setNext($nexttable->getName());
 188             $nexttable->setPrevious($table->getName());
 189         }
 190     /// Some more attributes
 191         $table->setLoaded(true);
 192         $table->setChanged(true);
 193     /// Add the new table
 194         $this->tables[] =& $table;
 195     /// Reorder the whole structure
 196         $this->orderTables($this->tables);
 197     /// Recalculate the hash
 198         $this->calculateHash(true);
 199     /// We have one new table, so the structure has changed
 200         $this->setVersion(userdate(time(), '%Y%m%d', 99, false));
 201         $this->setChanged(true);
 202     }
 203
 204     /**
 205      * Add one statement to the structure, allowing to specify the desired order
 206      * If it's not specified, then the statement is added at the end.
 207      */
 208     function addStatement(&$statement, $after=NULL) {
 209
 210     /// Calculate the previous and next tables
 211         $prevstatement = NULL;
 212         $nextstatement = NULL;
 213
 214         if (!$after) {
 215             $allstatements =& $this->getStatements();
 216             if ($allstatements) {
 217                 end($allstatements);
 218                 $prevstatement =& $allstatements[key($allstatements)];
 219             }
 220         } else {
 221             $prevstatement =& $this->getStatement($after);
 222         }
 223         if ($prevstatement && $prevstatement->getNext()) {
 224             $nextstatement =& $this->getStatement($prevstatement->getNext());
 225         }
 226
 227     /// Set current statement previous and next attributes
 228         if ($prevstatement) {
 229             $statement->setPrevious($prevstatement->getName());
 230             $prevstatement->setNext($statement->getName());
 231         }
 232         if ($nextstatement) {
 233             $statement->setNext($nextstatement->getName());
 234             $nextstatement->setPrevious($statement->getName());
 235         }
 236     /// Some more attributes
 237         $statement->setLoaded(true);
 238         $statement->setChanged(true);
 239     /// Add the new statement
 240         $this->statements[] =& $statement;
 241     /// Reorder the whole structure
 242         $this->orderStatements($this->statements);
 243     /// Recalculate the hash
 244         $this->calculateHash(true);
 245     /// We have one new statement, so the structure has changed
 246         $this->setVersion(userdate(time(), '%Y%m%d', 99, false));
 247         $this->setChanged(true);
 248     }
 249
 250     /**
 251      * Delete one table from the Structure
 252      */
 253     function deleteTable($tablename) {
 254
 255         $table =& $this->getTable($tablename);
 256         if ($table) {
 257             $i = $this->findTableInArray($tablename);
 258             $prevtable = NULL;
 259             $nexttable = NULL;
 260         /// Look for prev and next table
 261             $prevtable =& $this->getTable($table->getPrevious());
 262             $nexttable =& $this->getTable($table->getNext());
 263         /// Change their previous and next attributes
 264             if ($prevtable) {
 265                 $prevtable->setNext($table->getNext());
 266             }
 267             if ($nexttable) {
 268                 $nexttable->setPrevious($table->getPrevious());
 269             }
 270         /// Delete the table
 271             unset($this->tables[$i]);
 272         /// Reorder the tables
 273             $this->orderTables($this->tables);
 274         /// Recalculate the hash
 275             $this->calculateHash(true);
 276         /// We have one deleted table, so the structure has changed
 277             $this->setVersion(userdate(time(), '%Y%m%d', 99, false));
 278             $this->setChanged(true);
 279         }
 280     }
 281
 282     /**
 283      * Delete one statement from the Structure
 284      */
 285     function deleteStatement($statementname) {
 286
 287         $statement =& $this->getStatement($statementname);
 288         if ($statement) {
 289             $i = $this->findStatementInArray($statementname);
 290             $prevstatement = NULL;
 291             $nextstatement = NULL;
 292         /// Look for prev and next statement
 293             $prevstatement =& $this->getStatement($statement->getPrevious());
 294             $nextstatement =& $this->getStatement($statement->getNext());
 295         /// Change their previous and next attributes
 296             if ($prevstatement) {
 297                 $prevstatement->setNext($statement->getNext());
 298             }
 299             if ($nextstatement) {
 300                 $nextstatement->setPrevious($statement->getPrevious());
 301             }
 302         /// Delete the statement
 303             unset($this->statements[$i]);
 304         /// Reorder the statements
 305             $this->orderStatements($this->statements);
 306         /// Recalculate the hash
 307             $this->calculateHash(true);
 308         /// We have one deleted statement, so the structure has changed
 309             $this->setVersion(userdate(time(), '%Y%m%d', 99, false));
 310             $this->setChanged(true);
 311         }
 312     }
 313
 314     /**
 315      * Set the tables
 316      */
 317     function setTables(&$tables) {
 318         $this->tables = $tables;
 319     }
 320
 321     /**
 322      * Set the statements
 323      */
 324     function setStatements(&$statements) {
 325         $this->statements = $statements;
 326     }
 327
 328     /**
 329      * Load data from XML to the structure
 330      */
 331     function arr2XMLDBStructure($xmlarr) {
 332
 333         global $CFG;
 334
 335         $result = true;
 336
 337     /// Debug the structure
 338     /// traverse_xmlize($xmlarr);                   //Debug
 339     /// print_object ($GLOBALS['traverse_array']);  //Debug
 340     /// $GLOBALS['traverse_array']="";              //Debug
 341
 342     /// Process structure attributes (path, comment and version)
 343         if (isset($xmlarr['XMLDB']['@']['PATH'])) {
 344             $this->path = trim($xmlarr['XMLDB']['@']['PATH']);
 345         } else {
 346             $this->errormsg = 'Missing PATH attribute';
 347             $this->debug($this->errormsg);
 348             $result = false;
 349         }
 350         if (isset($xmlarr['XMLDB']['@']['VERSION'])) {
 351             $this->version = trim($xmlarr['XMLDB']['@']['VERSION']);
 352         } else {
 353             $this->errormsg = 'Missing VERSION attribute';
 354             $this->debug($this->errormsg);
 355             $result = false;
 356         }
 357         if (isset($xmlarr['XMLDB']['@']['COMMENT'])) {
 358             $this->comment = trim($xmlarr['XMLDB']['@']['COMMENT']);
 359         } else if (!empty($CFG->xmldbdisablecommentchecking)) {
 360             $this->comment = '';
 361         } else {
 362             $this->errormsg = 'Missing COMMENT attribute';
 363             $this->debug($this->errormsg);
 364             $result = false;
 365         }
 366
 367     /// Iterate over tables
 368         if (isset($xmlarr['XMLDB']['#']['TABLES']['0']['#']['TABLE'])) {
 369             foreach ($xmlarr['XMLDB']['#']['TABLES']['0']['#']['TABLE'] as $xmltable) {
 370                 if (!$result) { //Skip on error
 371                     continue;
 372                 }
 373                 $name = trim($xmltable['@']['NAME']);
 374                 $table = new XMLDBTable($name);
 375                 $table->arr2XMLDBTable($xmltable);
 376                 $this->tables[] = $table;
 377                 if (!$table->isLoaded()) {
 378                     $this->errormsg = 'Problem loading table ' . $name;
 379                     $this->debug($this->errormsg);
 380                     $result = false;
 381                 }
 382             }
 383         } else {
 384             $this->errormsg = 'Missing TABLES section';
 385             $this->debug($this->errormsg);
 386             $result = false;
 387         }
 388
 389     /// Perform some general checks over tables
 390         if ($result && $this->tables) {
 391         /// Check tables names are ok (lowercase, a-z _-)
 392             if (!$this->checkNameValues($this->tables)) {
 393                 $this->errormsg = 'Some TABLES name values are incorrect';
 394                 $this->debug($this->errormsg);
 395                 $result = false;
 396             }
 397         /// Check previous & next are ok (duplicates and existing tables)
 398             $this->fixPrevNext($this->tables);
 399             if ($result && !$this->checkPreviousNextValues($this->tables)) {
 400                 $this->errormsg = 'Some TABLES previous/next values are incorrect';
 401                 $this->debug($this->errormsg);
 402                 $result = false;
 403             }
 404         /// Order tables
 405             if ($result && !$this->orderTables($this->tables)) {
 406                 $this->errormsg = 'Error ordering the tables';
 407                 $this->debug($this->errormsg);
 408                 $result = false;
 409             }
 410         }
 411
 412     /// Iterate over statements
 413         if (isset($xmlarr['XMLDB']['#']['STATEMENTS']['0']['#']['STATEMENT'])) {
 414             foreach ($xmlarr['XMLDB']['#']['STATEMENTS']['0']['#']['STATEMENT'] as $xmlstatement) {
 415                 if (!$result) { //Skip on error
 416                     continue;
 417                 }
 418                 $name = trim($xmlstatement['@']['NAME']);
 419                 $statement = new XMLDBStatement($name);
 420                 $statement->arr2XMLDBStatement($xmlstatement);
 421                 $this->statements[] = $statement;
 422                 if (!$statement->isLoaded()) {
 423                     $this->errormsg = 'Problem loading statement ' . $name;
 424                     $this->debug($this->errormsg);
 425                     $result = false;
 426                 }
 427             }
 428         }
 429
 430     /// Perform some general checks over statements
 431         if ($result && $this->statements) {
 432         /// Check statements names are ok (lowercase, a-z _-)
 433             if (!$this->checkNameValues($this->statements)) {
 434                 $this->errormsg = 'Some STATEMENTS name values are incorrect';
 435                 $this->debug($this->errormsg);
 436                 $result = false;
 437             }
 438         /// Check previous & next are ok (duplicates and existing statements)
 439             $this->fixPrevNext($this->statements);
 440             if ($result && !$this->checkPreviousNextValues($this->statements)) {
 441                 $this->errormsg = 'Some STATEMENTS previous/next values are incorrect';
 442                 $this->debug($this->errormsg);
 443                 $result = false;
 444             }
 445         /// Order statements
 446             if ($result && !$this->orderStatements($this->statements)) {
 447                 $this->errormsg = 'Error ordering the statements';
 448                 $this->debug($this->errormsg);
 449                 $result = false;
 450             }
 451         }
 452
 453     /// Set some attributes
 454         if ($result) {
 455             $this->loaded = true;
 456         }
 457         $this->calculateHash();
 458         return $result;
 459     }
 460
 461     /**
 462      * This function calculate and set the hash of one XMLDBStructure
 463      */
 464      function calculateHash($recursive = false) {
 465         if (!$this->loaded) {
 466             $this->hash = NULL;
 467         } else {
 468             $key = $this->name . $this->path . $this->comment;
 469             if ($this->tables) {
 470                 foreach ($this->tables as $tbl) {
 471                     $table =& $this->getTable($tbl->getName());
 472                     if ($recursive) {
 473                         $table->calculateHash($recursive);
 474                     }
 475                     $key .= $table->getHash();
 476                 }
 477             }
 478             if ($this->statements) {
 479                 foreach ($this->statements as $sta) {
 480                     $statement =& $this->getStatement($sta->getName());
 481                     if ($recursive) {
 482                         $statement->calculateHash($recursive);
 483                     }
 484                     $key .= $statement->getHash();
 485                 }
 486             }
 487             $this->hash = md5($key);
 488         }
 489     }
 490
 491     /**
 492      * This function will output the XML text for one structure
 493      */
 494     function xmlOutput() {
 495         $o = '<?xml version="1.0" encoding="UTF-8" ?>' . "\n";
 496         $o.= '<XMLDB PATH="' . $this->path . '"';
 497         $o.= ' VERSION="' . $this->version . '"';
 498         if ($this->comment) {
 499             $o.= ' COMMENT="' . htmlspecialchars($this->comment) . '"'."\n";
 500         }
 501         $rel = array_fill(0, count(explode('/', $this->path)), '..');
 502         $rel = implode('/', $rel);
 503         $o.= '    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'."\n";
 504         $o.= '    xsi:noNamespaceSchemaLocation="'.$rel.'/lib/xmldb/xmldb.xsd"'."\n";
 505         $o.= '>' . "\n";
 506     /// Now the tables
 507         if ($this->tables) {
 508             $o.= '  <TABLES>' . "\n";
 509             foreach ($this->tables as $table) {
 510                 $o.= $table->xmlOutput();
 511             }
 512             $o.= '  </TABLES>' . "\n";
 513         }
 514     /// Now the statements
 515         if ($this->statements) {
 516             $o.= '  <STATEMENTS>' . "\n";
 517             foreach ($this->statements as $statement) {
 518                 $o.= $statement->xmlOutput();
 519             }
 520             $o.= '  </STATEMENTS>' . "\n";
 521         }
 522         $o.= '</XMLDB>';
 523
 524         return $o;
 525     }
 526
 527     /**
 528      * This function returns the number of uses of one table inside
 529      * a whole XMLDStructure. Useful to detect if the table must be
 530      * locked. Return false if no uses are found.
 531      */
 532     function getTableUses($tablename) {
 533
 534         $uses = array();
 535
 536     /// Check if some foreign key in the whole structure is using it
 537     /// (by comparing the reftable with the tablename)
 538         $alltables = $this->getTables();
 539         if ($alltables) {
 540             foreach ($alltables as $table) {
 541                 $keys = $table->getKeys();
 542                 if ($keys) {
 543                     foreach ($keys as $key) {
 544                         if ($key->getType() == XMLDB_KEY_FOREIGN) {
 545                             if ($tablename == $key->getRefTable()) {
 546                                 $uses[] = 'table ' . $table->getName() . ' key ' . $key->getName();
 547                             }
 548                         }
 549                     }
 550                 }
 551             }
 552         }
 553
 554     /// Return result
 555         if (!empty($uses)) {
 556             return $uses;
 557         } else {
 558             return false;
 559         }
 560     }
 561
 562     /**
 563      * This function returns the number of uses of one field inside
 564      * a whole XMLDBStructure. Useful to detect if the field must be
 565      * locked. Return false if no uses are found.
 566      */
 567     function getFieldUses($tablename, $fieldname) {
 568
 569         $uses = array();
 570
 571     /// Check if any key in the table is using it
 572         $table = $this->getTable($tablename);
 573         if ($keys = $table->getKeys()) {
 574             foreach ($keys as $key) {
 575                 if (in_array($fieldname, $key->getFields()) ||
 576                     in_array($fieldname, $key->getRefFields())) {
 577                         $uses[] = 'table ' . $table->getName() . ' key ' . $key->getName();
 578                 }
 579             }
 580         }
 581     /// Check if any index in the table is using it
 582         $table = $this->getTable($tablename);
 583         if ($indexes = $table->getIndexes()) {
 584             foreach ($indexes as $index) {
 585                 if (in_array($fieldname, $index->getFields())) {
 586                     $uses[] = 'table ' . $table->getName() . ' index ' . $index->getName();
 587                 }
 588             }
 589         }
 590     /// Check if some foreign key in the whole structure is using it
 591     /// By comparing the reftable and refields with the field)
 592         $alltables = $this->getTables();
 593         if ($alltables) {
 594             foreach ($alltables as $table) {
 595                 $keys = $table->getKeys();
 596                 if ($keys) {
 597                     foreach ($keys as $key) {
 598                         if ($key->getType() == XMLDB_KEY_FOREIGN) {
 599                             if ($tablename == $key->getRefTable()) {
 600                                 $reffieds = $key->getRefFields();
 601                                 if (in_array($fieldname, $key->getRefFields())) {
 602                                     $uses[] = 'table ' . $table->getName() . ' key ' . $key->getName();
 603                                 }
 604                             }
 605                         }
 606                     }
 607                 }
 608             }
 609         }
 610
 611     /// Return result
 612         if (!empty($uses)) {
 613             return $uses;
 614         } else {
 615             return false;
 616         }
 617     }
 618
 619     /**
 620      * This function returns the number of uses of one key inside
 621      * a whole XMLDBStructure. Useful to detect if the key must be
 622      * locked. Return false if no uses are found.
 623      */
 624     function getKeyUses($tablename, $keyname) {
 625
 626         $uses = array();
 627
 628     /// Check if some foreign key in the whole structure is using it
 629     /// (by comparing the reftable and reffields with the fields in the key)
 630         $mytable = $this->getTable($tablename);
 631         $mykey = $mytable->getKey($keyname);
 632         $alltables = $this->getTables();
 633         if ($alltables && $mykey) {
 634             foreach ($alltables as $table) {
 635                 $allkeys = $table->getKeys();
 636                 if ($allkeys) {
 637                     foreach ($allkeys as $key) {
 638                         if ($key->getType() != XMLDB_KEY_FOREIGN) {
 639                             continue;
 640                         }
 641                         if ($key->getRefTable() == $tablename &&
 642                             implode(',', $key->getRefFields()) == implode(',', $mykey->getFields())) {
 643                                 $uses[] = 'table ' . $table->getName() . ' key ' . $key->getName();
 644                         }
 645                     }
 646                 }
 647             }
 648         }
 649
 650     /// Return result
 651         if (!empty($uses)) {
 652             return $uses;
 653         } else {
 654             return false;
 655         }
 656     }
 657
 658     /**
 659      * This function returns the number of uses of one index inside
 660      * a whole XMLDBStructure. Useful to detect if the index must be
 661      * locked. Return false if no uses are found.
 662      */
 663     function getIndexUses($tablename, $indexname) {
 664
 665         $uses = array();
 666
 667     /// Nothing to check, beause indexes haven't uses! Leave it here
 668     /// for future checks...
 669
 670     /// Return result
 671         if (!empty($uses)) {
 672             return $uses;
 673         } else {
 674             return false;
 675         }
 676     }
 677
 678     /**
 679      * This function will return all the errors found in one structure
 680      * looking recursively inside each table/statement. Returns
 681      * an array of errors or false
 682      */
 683     function getAllErrors() {
 684
 685         $errors = array();
 686     /// First the structure itself
 687         if ($this->getError()) {
 688             $errors[] = $this->getError();
 689         }
 690     /// Delegate to tables
 691         if ($tables = $this->getTables()) {
 692             foreach ($tables as $table) {
 693                 if ($tableerrors = $table->getAllErrors()) {
 694
 695                 }
 696             }
 697         /// Add them to the errors array
 698             if ($tableerrors) {
 699                 $errors = array_merge($errors, $tableerrors);
 700             }
 701         }
 702     /// Delegate to statements
 703         if ($statements = $this->getStatements()) {
 704             foreach ($statements as $statement) {
 705                 if ($statement->getError()) {
 706                     $errors[] = $statement->getError();
 707                 }
 708             }
 709         }
 710     /// Return decision
 711         if (count($errors)) {
 712             return $errors;
 713         } else {
 714             return false;
 715         }
 716     }
 717
 718     /**
 719      * This function will return the SQL code needed to create the table for the specified DB and
 720      * prefix. Just one simple wrapper over generators.
 721      */
 722     function getCreateStructureSQL ($dbtype, $prefix, $statement_end=true) {
 723
 724         $results = array();
 725
 726         if ($tables = $this->getTables()) {
 727             foreach ($tables as $table) {
 728                 $results = array_merge($results, $table->getCreateTableSQL($dbtype, $prefix, $statement_end));
 729             }
 730         }
 731
 732         if ($statements = $this->getStatements()) {
 733             foreach ($statements as $statement) {
 734                 $results = array_merge($results, $statement->getExecuteStatementSQL($dbtype, $prefix, $statement_end));
 735             }
 736         }
 737         return $results;
 738     }
 739 }
 740
 741 ?>