Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 and 311]

       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   * Defines the base class for question import and export formats.
      19   *
      20   * @package    moodlecore
      21   * @subpackage questionbank
      22   * @copyright  1999 onwards Martin Dougiamas {@link http://moodle.com}
      23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
      24   */
      25  
      26  
      27  defined('MOODLE_INTERNAL') || die();
      28  
      29  
      30  /**
      31   * Base class for question import and export formats.
      32   *
      33   * @copyright  1999 onwards Martin Dougiamas {@link http://moodle.com}
      34   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
      35   */
      36  class qformat_default {
      37  
      38      public $displayerrors = true;
      39      public $category = null;
      40      public $questions = array();
      41      public $course = null;
      42      public $filename = '';
      43      public $realfilename = '';
      44      public $matchgrades = 'error';
      45      public $catfromfile = 0;
      46      public $contextfromfile = 0;
      47      public $cattofile = 0;
      48      public $contexttofile = 0;
      49      public $questionids = array();
      50      public $importerrors = 0;
      51      public $stoponerror = true;
      52      public $translator = null;
      53      public $canaccessbackupdata = true;
      54      protected $importcontext = null;
      55      /** @var bool $displayprogress Whether to display progress. */
      56      public $displayprogress = true;
      57  
      58      // functions to indicate import/export functionality
      59      // override to return true if implemented
      60  
      61      /** @return bool whether this plugin provides import functionality. */
      62      public function provide_import() {
      63          return false;
      64      }
      65  
      66      /** @return bool whether this plugin provides export functionality. */
      67      public function provide_export() {
      68          return false;
      69      }
      70  
      71      /** The string mime-type of the files that this plugin reads or writes. */
      72      public function mime_type() {
      73          return mimeinfo('type', $this->export_file_extension());
      74      }
      75  
      76      /**
      77       * @return string the file extension (including .) that is normally used for
      78       * files handled by this plugin.
      79       */
      80      public function export_file_extension() {
      81          return '.txt';
      82      }
      83  
      84      /**
      85       * Check if the given file is capable of being imported by this plugin.
      86       *
      87       * Note that expensive or detailed integrity checks on the file should
      88       * not be performed by this method. Simple file type or magic-number tests
      89       * would be suitable.
      90       *
      91       * @param stored_file $file the file to check
      92       * @return bool whether this plugin can import the file
      93       */
      94      public function can_import_file($file) {
      95          return ($file->get_mimetype() == $this->mime_type());
      96      }
      97  
      98      /**
      99       * Validate the given file.
     100       *
     101       * For more expensive or detailed integrity checks.
     102       *
     103       * @param stored_file $file the file to check
     104       * @return string the error message that occurred while validating the given file
     105       */
     106      public function validate_file(stored_file $file): string {
     107          return '';
     108      }
     109  
     110      /**
     111       * Check if the given file has the required utf8 encoding.
     112       *
     113       * @param stored_file $file the file to check
     114       * @return string the error message if the file encoding is not UTF-8
     115       */
     116      protected function validate_is_utf8_file(stored_file $file): string {
     117          if (!mb_check_encoding($file->get_content(), "UTF-8")) {
     118              return get_string('importwrongfileencoding', 'question',  $this->get_name());
     119          }
     120          return '';
     121      }
     122  
     123      /**
     124       * Return the localized pluginname string for the question format.
     125       *
     126       * @return string the pluginname string for the question format
     127       */
     128      protected function get_name(): string {
     129          return get_string('pluginname', get_class($this));
     130      }
     131  
     132      // Accessor methods
     133  
     134      /**
     135       * set the category
     136       * @param object category the category object
     137       */
     138      public function setCategory($category) {
     139          if (count($this->questions)) {
     140              debugging('You shouldn\'t call setCategory after setQuestions');
     141          }
     142          $this->category = $category;
     143          $this->importcontext = context::instance_by_id($this->category->contextid);
     144      }
     145  
     146      /**
     147       * Set the specific questions to export. Should not include questions with
     148       * parents (sub questions of cloze question type).
     149       * Only used for question export.
     150       * @param array of question objects
     151       */
     152      public function setQuestions($questions) {
     153          if ($this->category !== null) {
     154              debugging('You shouldn\'t call setQuestions after setCategory');
     155          }
     156          $this->questions = $questions;
     157      }
     158  
     159      /**
     160       * set the course class variable
     161       * @param course object Moodle course variable
     162       */
     163      public function setCourse($course) {
     164          $this->course = $course;
     165      }
     166  
     167      /**
     168       * set an array of contexts.
     169       * @param array $contexts Moodle course variable
     170       */
     171      public function setContexts($contexts) {
     172          $this->contexts = $contexts;
     173          $this->translator = new context_to_string_translator($this->contexts);
     174      }
     175  
     176      /**
     177       * set the filename
     178       * @param string filename name of file to import/export
     179       */
     180      public function setFilename($filename) {
     181          $this->filename = $filename;
     182      }
     183  
     184      /**
     185       * set the "real" filename
     186       * (this is what the user typed, regardless of wha happened next)
     187       * @param string realfilename name of file as typed by user
     188       */
     189      public function setRealfilename($realfilename) {
     190          $this->realfilename = $realfilename;
     191      }
     192  
     193      /**
     194       * set matchgrades
     195       * @param string matchgrades error or nearest for grades
     196       */
     197      public function setMatchgrades($matchgrades) {
     198          $this->matchgrades = $matchgrades;
     199      }
     200  
     201      /**
     202       * set catfromfile
     203       * @param bool catfromfile allow categories embedded in import file
     204       */
     205      public function setCatfromfile($catfromfile) {
     206          $this->catfromfile = $catfromfile;
     207      }
     208  
     209      /**
     210       * set contextfromfile
     211       * @param bool $contextfromfile allow contexts embedded in import file
     212       */
     213      public function setContextfromfile($contextfromfile) {
     214          $this->contextfromfile = $contextfromfile;
     215      }
     216  
     217      /**
     218       * set cattofile
     219       * @param bool cattofile exports categories within export file
     220       */
     221      public function setCattofile($cattofile) {
     222          $this->cattofile = $cattofile;
     223      }
     224  
     225      /**
     226       * set contexttofile
     227       * @param bool cattofile exports categories within export file
     228       */
     229      public function setContexttofile($contexttofile) {
     230          $this->contexttofile = $contexttofile;
     231      }
     232  
     233      /**
     234       * set stoponerror
     235       * @param bool stoponerror stops database write if any errors reported
     236       */
     237      public function setStoponerror($stoponerror) {
     238          $this->stoponerror = $stoponerror;
     239      }
     240  
     241      /**
     242       * @param bool $canaccess Whether the current use can access the backup data folder. Determines
     243       * where export files are saved.
     244       */
     245      public function set_can_access_backupdata($canaccess) {
     246          $this->canaccessbackupdata = $canaccess;
     247      }
     248  
     249      /**
     250       * Change whether to display progress messages.
     251       * There is normally no need to use this function as the
     252       * default for $displayprogress is true.
     253       * Set to false for unit tests.
     254       * @param bool $displayprogress
     255       */
     256      public function set_display_progress($displayprogress) {
     257          $this->displayprogress = $displayprogress;
     258      }
     259  
     260      /***********************
     261       * IMPORTING FUNCTIONS
     262       ***********************/
     263  
     264      /**
     265       * Handle parsing error
     266       */
     267      protected function error($message, $text='', $questionname='') {
     268          $importerrorquestion = get_string('importerrorquestion', 'question');
     269  
     270          echo "<div class=\"importerror\">\n";
     271          echo "<strong>{$importerrorquestion} {$questionname}</strong>";
     272          if (!empty($text)) {
     273              $text = s($text);
     274              echo "<blockquote>{$text}</blockquote>\n";
     275          }
     276          echo "<strong>{$message}</strong>\n";
     277          echo "</div>";
     278  
     279          $this->importerrors++;
     280      }
     281  
     282      /**
     283       * Import for questiontype plugins
     284       * Do not override.
     285       * @param data mixed The segment of data containing the question
     286       * @param question object processed (so far) by standard import code if appropriate
     287       * @param extra mixed any additional format specific data that may be passed by the format
     288       * @param qtypehint hint about a question type from format
     289       * @return object question object suitable for save_options() or false if cannot handle
     290       */
     291      public function try_importing_using_qtypes($data, $question = null, $extra = null,
     292              $qtypehint = '') {
     293  
     294          // work out what format we are using
     295          $formatname = substr(get_class($this), strlen('qformat_'));
     296          $methodname = "import_from_{$formatname}";
     297  
     298          //first try importing using a hint from format
     299          if (!empty($qtypehint)) {
     300              $qtype = question_bank::get_qtype($qtypehint, false);
     301              if (is_object($qtype) && method_exists($qtype, $methodname)) {
     302                  $question = $qtype->$methodname($data, $question, $this, $extra);
     303                  if ($question) {
     304                      return $question;
     305                  }
     306              }
     307          }
     308  
     309          // loop through installed questiontypes checking for
     310          // function to handle this question
     311          foreach (question_bank::get_all_qtypes() as $qtype) {
     312              if (method_exists($qtype, $methodname)) {
     313                  if ($question = $qtype->$methodname($data, $question, $this, $extra)) {
     314                      return $question;
     315                  }
     316              }
     317          }
     318          return false;
     319      }
     320  
     321      /**
     322       * Perform any required pre-processing
     323       * @return bool success
     324       */
     325      public function importpreprocess() {
     326          return true;
     327      }
     328  
     329      /**
     330       * Process the file
     331       * This method should not normally be overidden
     332       * @return bool success
     333       */
     334      public function importprocess() {
     335          global $USER, $DB, $OUTPUT;
     336  
     337          // Raise time and memory, as importing can be quite intensive.
     338          core_php_time_limit::raise();
     339          raise_memory_limit(MEMORY_EXTRA);
     340  
     341          // STAGE 1: Parse the file
     342          if ($this->displayprogress) {
     343              echo $OUTPUT->notification(get_string('parsingquestions', 'question'), 'notifysuccess');
     344          }
     345  
     346          if (! $lines = $this->readdata($this->filename)) {
     347              echo $OUTPUT->notification(get_string('cannotread', 'question'));
     348              return false;
     349          }
     350  
     351          if (!$questions = $this->readquestions($lines)) {   // Extract all the questions
     352              echo $OUTPUT->notification(get_string('noquestionsinfile', 'question'));
     353              return false;
     354          }
     355  
     356          // STAGE 2: Write data to database
     357          if ($this->displayprogress) {
     358              echo $OUTPUT->notification(get_string('importingquestions', 'question',
     359                      $this->count_questions($questions)), 'notifysuccess');
     360          }
     361  
     362          // check for errors before we continue
     363          if ($this->stoponerror and ($this->importerrors>0)) {
     364              echo $OUTPUT->notification(get_string('importparseerror', 'question'));
     365              return true;
     366          }
     367  
     368          // get list of valid answer grades
     369          $gradeoptionsfull = question_bank::fraction_options_full();
     370  
     371          // check answer grades are valid
     372          // (now need to do this here because of 'stop on error': MDL-10689)
     373          $gradeerrors = 0;
     374          $goodquestions = array();
     375          foreach ($questions as $question) {
     376              if (!empty($question->fraction) and (is_array($question->fraction))) {
     377                  $fractions = $question->fraction;
     378                  $invalidfractions = array();
     379                  foreach ($fractions as $key => $fraction) {
     380                      $newfraction = match_grade_options($gradeoptionsfull, $fraction,
     381                              $this->matchgrades);
     382                      if ($newfraction === false) {
     383                          $invalidfractions[] = $fraction;
     384                      } else {
     385                          $fractions[$key] = $newfraction;
     386                      }
     387                  }
     388                  if ($invalidfractions) {
     389                      echo $OUTPUT->notification(get_string('invalidgrade', 'question',
     390                              implode(', ', $invalidfractions)));
     391                      ++$gradeerrors;
     392                      continue;
     393                  } else {
     394                      $question->fraction = $fractions;
     395                  }
     396              }
     397              $goodquestions[] = $question;
     398          }
     399          $questions = $goodquestions;
     400  
     401          // check for errors before we continue
     402          if ($this->stoponerror && $gradeerrors > 0) {
     403              return false;
     404          }
     405  
     406          // count number of questions processed
     407          $count = 0;
     408  
     409          foreach ($questions as $question) {   // Process and store each question
     410              $transaction = $DB->start_delegated_transaction();
     411  
     412              // reset the php timeout
     413              core_php_time_limit::raise();
     414  
     415              // check for category modifiers
     416              if ($question->qtype == 'category') {
     417                  if ($this->catfromfile) {
     418                      // find/create category object
     419                      $catpath = $question->category;
     420                      $newcategory = $this->create_category_path($catpath, $question);
     421                      if (!empty($newcategory)) {
     422                          $this->category = $newcategory;
     423                      }
     424                  }
     425                  $transaction->allow_commit();
     426                  continue;
     427              }
     428              $question->context = $this->importcontext;
     429  
     430              $count++;
     431  
     432              if ($this->displayprogress) {
     433                  echo "<hr /><p><b>{$count}</b>. " . $this->format_question_text($question) . "</p>";
     434              }
     435  
     436              $question->category = $this->category->id;
     437              $question->stamp = make_unique_id_code();  // Set the unique code (not to be changed)
     438  
     439              $question->createdby = $USER->id;
     440              $question->timecreated = time();
     441              $question->modifiedby = $USER->id;
     442              $question->timemodified = time();
     443              if (isset($question->idnumber)) {
     444                  if ((string) $question->idnumber === '') {
     445                      // Id number not really set. Get rid of it.
     446                      unset($question->idnumber);
     447                  } else {
     448                      if ($DB->record_exists('question',
     449                              ['idnumber' => $question->idnumber, 'category' => $question->category])) {
     450                          // We cannot have duplicate idnumbers in a category. Just remove it.
     451                          unset($question->idnumber);
     452                      }
     453                  }
     454              }
     455  
     456              $fileoptions = array(
     457                      'subdirs' => true,
     458                      'maxfiles' => -1,
     459                      'maxbytes' => 0,
     460                  );
     461  
     462              $question->id = $DB->insert_record('question', $question);
     463              $event = \core\event\question_created::create_from_question_instance($question, $this->importcontext);
     464              $event->trigger();
     465  
     466              if (isset($question->questiontextitemid)) {
     467                  $question->questiontext = file_save_draft_area_files($question->questiontextitemid,
     468                          $this->importcontext->id, 'question', 'questiontext', $question->id,
     469                          $fileoptions, $question->questiontext);
     470              } else if (isset($question->questiontextfiles)) {
     471                  foreach ($question->questiontextfiles as $file) {
     472                      question_bank::get_qtype($question->qtype)->import_file(
     473                              $this->importcontext, 'question', 'questiontext', $question->id, $file);
     474                  }
     475              }
     476              if (isset($question->generalfeedbackitemid)) {
     477                  $question->generalfeedback = file_save_draft_area_files($question->generalfeedbackitemid,
     478                          $this->importcontext->id, 'question', 'generalfeedback', $question->id,
     479                          $fileoptions, $question->generalfeedback);
     480              } else if (isset($question->generalfeedbackfiles)) {
     481                  foreach ($question->generalfeedbackfiles as $file) {
     482                      question_bank::get_qtype($question->qtype)->import_file(
     483                              $this->importcontext, 'question', 'generalfeedback', $question->id, $file);
     484                  }
     485              }
     486              $DB->update_record('question', $question);
     487  
     488              $this->questionids[] = $question->id;
     489  
     490              // Now to save all the answers and type-specific options
     491  
     492              $result = question_bank::get_qtype($question->qtype)->save_question_options($question);
     493  
     494              if (core_tag_tag::is_enabled('core_question', 'question')) {
     495                  // Is the current context we're importing in a course context?
     496                  $importingcontext = $this->importcontext;
     497                  $importingcoursecontext = $importingcontext->get_course_context(false);
     498                  $isimportingcontextcourseoractivity = !empty($importingcoursecontext);
     499  
     500                  if (!empty($question->coursetags)) {
     501                      if ($isimportingcontextcourseoractivity) {
     502                          $mergedtags = array_merge($question->coursetags, $question->tags);
     503  
     504                          core_tag_tag::set_item_tags('core_question', 'question', $question->id,
     505                              $question->context, $mergedtags);
     506                      } else {
     507                          core_tag_tag::set_item_tags('core_question', 'question', $question->id,
     508                              context_course::instance($this->course->id), $question->coursetags);
     509  
     510                          if (!empty($question->tags)) {
     511                              core_tag_tag::set_item_tags('core_question', 'question', $question->id,
     512                                  $importingcontext, $question->tags);
     513                          }
     514                      }
     515                  } else if (!empty($question->tags)) {
     516                      core_tag_tag::set_item_tags('core_question', 'question', $question->id,
     517                          $question->context, $question->tags);
     518                  }
     519              }
     520  
     521              if (!empty($result->error)) {
     522                  echo $OUTPUT->notification($result->error);
     523                  // Can't use $transaction->rollback(); since it requires an exception,
     524                  // and I don't want to rewrite this code to change the error handling now.
     525                  $DB->force_transaction_rollback();
     526                  return false;
     527              }
     528  
     529              $transaction->allow_commit();
     530  
     531              if (!empty($result->notice)) {
     532                  echo $OUTPUT->notification($result->notice);
     533                  return true;
     534              }
     535  
     536              // Give the question a unique version stamp determined by question_hash()
     537              $DB->set_field('question', 'version', question_hash($question),
     538                      array('id' => $question->id));
     539          }
     540          return true;
     541      }
     542  
     543      /**
     544       * Count all non-category questions in the questions array.
     545       *
     546       * @param array questions An array of question objects.
     547       * @return int The count.
     548       *
     549       */
     550      protected function count_questions($questions) {
     551          $count = 0;
     552          if (!is_array($questions)) {
     553              return $count;
     554          }
     555          foreach ($questions as $question) {
     556              if (!is_object($question) || !isset($question->qtype) ||
     557                      ($question->qtype == 'category')) {
     558                  continue;
     559              }
     560              $count++;
     561          }
     562          return $count;
     563      }
     564  
     565      /**
     566       * find and/or create the category described by a delimited list
     567       * e.g. $course$/tom/dick/harry or tom/dick/harry
     568       *
     569       * removes any context string no matter whether $getcontext is set
     570       * but if $getcontext is set then ignore the context and use selected category context.
     571       *
     572       * @param string catpath delimited category path
     573       * @param object $lastcategoryinfo Contains category information
     574       * @return mixed category object or null if fails
     575       */
     576      protected function create_category_path($catpath, $lastcategoryinfo = null) {
     577          global $DB;
     578          $catnames = $this->split_category_path($catpath);
     579          $parent = 0;
     580          $category = null;
     581  
     582          // check for context id in path, it might not be there in pre 1.9 exports
     583          $matchcount = preg_match('/^\$([a-z]+)\$$/', $catnames[0], $matches);
     584          if ($matchcount == 1) {
     585              $contextid = $this->translator->string_to_context($matches[1]);
     586              array_shift($catnames);
     587          } else {
     588              $contextid = false;
     589          }
     590  
     591          // Before 3.5, question categories could be created at top level.
     592          // From 3.5 onwards, all question categories should be a child of a special category called the "top" category.
     593          if (isset($catnames[0]) && (($catnames[0] != 'top') || (count($catnames) < 3))) {
     594              array_unshift($catnames, 'top');
     595          }
     596  
     597          if ($this->contextfromfile && $contextid !== false) {
     598              $context = context::instance_by_id($contextid);
     599              require_capability('moodle/question:add', $context);
     600          } else {
     601              $context = context::instance_by_id($this->category->contextid);
     602          }
     603          $this->importcontext = $context;
     604  
     605          // Now create any categories that need to be created.
     606          foreach ($catnames as $key => $catname) {
     607              if ($parent == 0) {
     608                  $category = question_get_top_category($context->id, true);
     609                  $parent = $category->id;
     610              } else if ($category = $DB->get_record('question_categories',
     611                      array('name' => $catname, 'contextid' => $context->id, 'parent' => $parent))) {
     612                  // If this category is now the last one in the path we are processing ...
     613                  if ($key == (count($catnames) - 1) && $lastcategoryinfo) {
     614                      // Do nothing unless the child category appears before the parent category
     615                      // in the imported xml file. Because the parent was created without info being available
     616                      // at that time, this allows the info to be added from the xml data.
     617                      if (isset($lastcategoryinfo->info) && $lastcategoryinfo->info !== ''
     618                              && $category->info === '') {
     619                          $category->info = $lastcategoryinfo->info;
     620                          if (isset($lastcategoryinfo->infoformat) && $lastcategoryinfo->infoformat !== '') {
     621                              $category->infoformat = $lastcategoryinfo->infoformat;
     622                          }
     623                      }
     624                      // Same for idnumber.
     625                      if (isset($lastcategoryinfo->idnumber) && $lastcategoryinfo->idnumber !== ''
     626                              && $category->idnumber === '') {
     627                          $category->idnumber = $lastcategoryinfo->idnumber;
     628                      }
     629                      $DB->update_record('question_categories', $category);
     630                  }
     631                  $parent = $category->id;
     632              } else {
     633                  if ($catname == 'top') {
     634                      // Should not happen, but if it does just move on.
     635                      // Occurs when there has been some import/export that has created
     636                      // multiple nested 'top' categories (due to old bug solved by MDL-63165).
     637                      // This basically silently cleans up old errors. Not throwing an exception here.
     638                      continue;
     639                  }
     640                  require_capability('moodle/question:managecategory', $context);
     641                  // Create the new category. This will create all the categories in the catpath,
     642                  // though only the final category will have any info added if available.
     643                  $category = new stdClass();
     644                  $category->contextid = $context->id;
     645                  $category->name = $catname;
     646                  $category->info = '';
     647                  // Only add info (category description) for the final category in the catpath.
     648                  if ($key == (count($catnames) - 1) && $lastcategoryinfo) {
     649                      if (isset($lastcategoryinfo->info) && $lastcategoryinfo->info !== '') {
     650                          $category->info = $lastcategoryinfo->info;
     651                          if (isset($lastcategoryinfo->infoformat) && $lastcategoryinfo->infoformat !== '') {
     652                              $category->infoformat = $lastcategoryinfo->infoformat;
     653                          }
     654                      }
     655                      // Same for idnumber.
     656                      if (isset($lastcategoryinfo->idnumber) && $lastcategoryinfo->idnumber !== '') {
     657                          $category->idnumber = $lastcategoryinfo->idnumber;
     658                      }
     659                  }
     660                  $category->parent = $parent;
     661                  $category->sortorder = 999;
     662                  $category->stamp = make_unique_id_code();
     663                  $category->id = $DB->insert_record('question_categories', $category);
     664                  $parent = $category->id;
     665                  $event = \core\event\question_category_created::create_from_question_category_instance($category, $context);
     666                  $event->trigger();
     667              }
     668          }
     669          return $category;
     670      }
     671  
     672      /**
     673       * Return complete file within an array, one item per line
     674       * @param string filename name of file
     675       * @return mixed contents array or false on failure
     676       */
     677      protected function readdata($filename) {
     678          if (is_readable($filename)) {
     679              $filearray = file($filename);
     680  
     681              // If the first line of the file starts with a UTF-8 BOM, remove it.
     682              $filearray[0] = core_text::trim_utf8_bom($filearray[0]);
     683  
     684              // Check for Macintosh OS line returns (ie file on one line), and fix.
     685              if (preg_match("~\r~", $filearray[0]) AND !preg_match("~\n~", $filearray[0])) {
     686                  return explode("\r", $filearray[0]);
     687              } else {
     688                  return $filearray;
     689              }
     690          }
     691          return false;
     692      }
     693  
     694      /**
     695       * Parses an array of lines into an array of questions,
     696       * where each item is a question object as defined by
     697       * readquestion().   Questions are defined as anything
     698       * between blank lines.
     699       *
     700       * NOTE this method used to take $context as a second argument. However, at
     701       * the point where this method was called, it was impossible to know what
     702       * context the quetsions were going to be saved into, so the value could be
     703       * wrong. Also, none of the standard question formats were using this argument,
     704       * so it was removed. See MDL-32220.
     705       *
     706       * If your format does not use blank lines as a delimiter
     707       * then you will need to override this method. Even then
     708       * try to use readquestion for each question
     709       * @param array lines array of lines from readdata
     710       * @return array array of question objects
     711       */
     712      protected function readquestions($lines) {
     713  
     714          $questions = array();
     715          $currentquestion = array();
     716  
     717          foreach ($lines as $line) {
     718              $line = trim($line);
     719              if (empty($line)) {
     720                  if (!empty($currentquestion)) {
     721                      if ($question = $this->readquestion($currentquestion)) {
     722                          $questions[] = $question;
     723                      }
     724                      $currentquestion = array();
     725                  }
     726              } else {
     727                  $currentquestion[] = $line;
     728              }
     729          }
     730  
     731          if (!empty($currentquestion)) {  // There may be a final question
     732              if ($question = $this->readquestion($currentquestion)) {
     733                  $questions[] = $question;
     734              }
     735          }
     736  
     737          return $questions;
     738      }
     739  
     740      /**
     741       * return an "empty" question
     742       * Somewhere to specify question parameters that are not handled
     743       * by import but are required db fields.
     744       * This should not be overridden.
     745       * @return object default question
     746       */
     747      protected function defaultquestion() {
     748          global $CFG;
     749          static $defaultshuffleanswers = null;
     750          if (is_null($defaultshuffleanswers)) {
     751              $defaultshuffleanswers = get_config('quiz', 'shuffleanswers');
     752          }
     753  
     754          $question = new stdClass();
     755          $question->shuffleanswers = $defaultshuffleanswers;
     756          $question->defaultmark = 1;
     757          $question->image = '';
     758          $question->usecase = 0;
     759          $question->multiplier = array();
     760          $question->questiontextformat = FORMAT_MOODLE;
     761          $question->generalfeedback = '';
     762          $question->generalfeedbackformat = FORMAT_MOODLE;
     763          $question->answernumbering = 'abc';
     764          $question->penalty = 0.3333333;
     765          $question->length = 1;
     766  
     767          // this option in case the questiontypes class wants
     768          // to know where the data came from
     769          $question->export_process = true;
     770          $question->import_process = true;
     771  
     772          $this->add_blank_combined_feedback($question);
     773  
     774          return $question;
     775      }
     776  
     777      /**
     778       * Construct a reasonable default question name, based on the start of the question text.
     779       * @param string $questiontext the question text.
     780       * @param string $default default question name to use if the constructed one comes out blank.
     781       * @return string a reasonable question name.
     782       */
     783      public function create_default_question_name($questiontext, $default) {
     784          $name = $this->clean_question_name(shorten_text($questiontext, 80));
     785          if ($name) {
     786              return $name;
     787          } else {
     788              return $default;
     789          }
     790      }
     791  
     792      /**
     793       * Ensure that a question name does not contain anything nasty, and will fit in the DB field.
     794       * @param string $name the raw question name.
     795       * @return string a safe question name.
     796       */
     797      public function clean_question_name($name) {
     798          $name = clean_param($name, PARAM_TEXT); // Matches what the question editing form does.
     799          $name = trim($name);
     800          $trimlength = 251;
     801          while (core_text::strlen($name) > 255 && $trimlength > 0) {
     802              $name = shorten_text($name, $trimlength);
     803              $trimlength -= 10;
     804          }
     805          return $name;
     806      }
     807  
     808      /**
     809       * Add a blank combined feedback to a question object.
     810       * @param object question
     811       * @return object question
     812       */
     813      protected function add_blank_combined_feedback($question) {
     814          $question->correctfeedback = [
     815              'text' => '',
     816              'format' => $question->questiontextformat,
     817              'files' => []
     818          ];
     819          $question->partiallycorrectfeedback = [
     820              'text' => '',
     821              'format' => $question->questiontextformat,
     822              'files' => []
     823          ];
     824          $question->incorrectfeedback = [
     825              'text' => '',
     826              'format' => $question->questiontextformat,
     827              'files' => []
     828          ];
     829          return $question;
     830      }
     831  
     832      /**
     833       * Given the data known to define a question in
     834       * this format, this function converts it into a question
     835       * object suitable for processing and insertion into Moodle.
     836       *
     837       * If your format does not use blank lines to delimit questions
     838       * (e.g. an XML format) you must override 'readquestions' too
     839       * @param $lines mixed data that represents question
     840       * @return object question object
     841       */
     842      protected function readquestion($lines) {
     843          // We should never get there unless the qformat plugin is broken.
     844          throw new coding_exception('Question format plugin is missing important code: readquestion.');
     845  
     846          return null;
     847      }
     848  
     849      /**
     850       * Override if any post-processing is required
     851       * @return bool success
     852       */
     853      public function importpostprocess() {
     854          return true;
     855      }
     856  
     857      /*******************
     858       * EXPORT FUNCTIONS
     859       *******************/
     860  
     861      /**
     862       * Provide export functionality for plugin questiontypes
     863       * Do not override
     864       * @param name questiontype name
     865       * @param question object data to export
     866       * @param extra mixed any addition format specific data needed
     867       * @return string the data to append to export or false if error (or unhandled)
     868       */
     869      protected function try_exporting_using_qtypes($name, $question, $extra=null) {
     870          // work out the name of format in use
     871          $formatname = substr(get_class($this), strlen('qformat_'));
     872          $methodname = "export_to_{$formatname}";
     873  
     874          $qtype = question_bank::get_qtype($name, false);
     875          if (method_exists($qtype, $methodname)) {
     876              return $qtype->$methodname($question, $this, $extra);
     877          }
     878          return false;
     879      }
     880  
     881      /**
     882       * Do any pre-processing that may be required
     883       * @param bool success
     884       */
     885      public function exportpreprocess() {
     886          return true;
     887      }
     888  
     889      /**
     890       * Enable any processing to be done on the content
     891       * just prior to the file being saved
     892       * default is to do nothing
     893       * @param string output text
     894       * @param string processed output text
     895       */
     896      protected function presave_process($content) {
     897          return $content;
     898      }
     899  
     900      /**
     901       * Perform the export.
     902       * For most types this should not need to be overrided.
     903       *
     904       * @param   bool    $checkcapabilities Whether to check capabilities when exporting the questions.
     905       * @return  string  The content of the export.
     906       */
     907      public function exportprocess($checkcapabilities = true) {
     908          global $CFG, $DB;
     909  
     910          // Raise time and memory, as exporting can be quite intensive.
     911          core_php_time_limit::raise();
     912          raise_memory_limit(MEMORY_EXTRA);
     913  
     914          // Get the parents (from database) for this category.
     915          $parents = [];
     916          if ($this->category) {
     917              $parents = question_categorylist_parents($this->category->id);
     918          }
     919  
     920          // get the questions (from database) in this category
     921          // only get q's with no parents (no cloze subquestions specifically)
     922          if ($this->category) {
     923              $questions = get_questions_category($this->category, true);
     924          } else {
     925              $questions = $this->questions;
     926          }
     927  
     928          $count = 0;
     929  
     930          // results are first written into string (and then to a file)
     931          // so create/initialize the string here
     932          $expout = '';
     933  
     934          // track which category questions are in
     935          // if it changes we will record the category change in the output
     936          // file if selected. 0 means that it will get printed before the 1st question
     937          $trackcategory = 0;
     938  
     939          // Array of categories written to file.
     940          $writtencategories = [];
     941  
     942          foreach ($questions as $question) {
     943              // used by file api
     944              $contextid = $DB->get_field('question_categories', 'contextid',
     945                      array('id' => $question->category));
     946              $question->contextid = $contextid;
     947  
     948              // do not export hidden questions
     949              if (!empty($question->hidden)) {
     950                  continue;
     951              }
     952  
     953              // do not export random questions
     954              if ($question->qtype == 'random') {
     955                  continue;
     956              }
     957  
     958              // check if we need to record category change
     959              if ($this->cattofile) {
     960                  $addnewcat = false;
     961                  if ($question->category != $trackcategory) {
     962                      $addnewcat = true;
     963                      $trackcategory = $question->category;
     964                  }
     965                  $trackcategoryparents = question_categorylist_parents($trackcategory);
     966                  // Check if we need to record empty parents categories.
     967                  foreach ($trackcategoryparents as $trackcategoryparent) {
     968                      // If parent wasn't written.
     969                      if (!in_array($trackcategoryparent, $writtencategories)) {
     970                          // If parent is empty.
     971                          if (!count($DB->get_records('question', array('category' => $trackcategoryparent)))) {
     972                              $categoryname = $this->get_category_path($trackcategoryparent, $this->contexttofile);
     973                              $categoryinfo = $DB->get_record('question_categories', array('id' => $trackcategoryparent),
     974                                  'name, info, infoformat, idnumber', MUST_EXIST);
     975                              if ($categoryinfo->name != 'top') {
     976                                  // Create 'dummy' question for parent category.
     977                                  $dummyquestion = $this->create_dummy_question_representing_category($categoryname, $categoryinfo);
     978                                  $expout .= $this->writequestion($dummyquestion) . "\n";
     979                                  $writtencategories[] = $trackcategoryparent;
     980                              }
     981                          }
     982                      }
     983                  }
     984                  if ($addnewcat && !in_array($trackcategory, $writtencategories)) {
     985                      $categoryname = $this->get_category_path($trackcategory, $this->contexttofile);
     986                      $categoryinfo = $DB->get_record('question_categories', array('id' => $trackcategory),
     987                              'info, infoformat, idnumber', MUST_EXIST);
     988                      // Create 'dummy' question for category.
     989                      $dummyquestion = $this->create_dummy_question_representing_category($categoryname, $categoryinfo);
     990                      $expout .= $this->writequestion($dummyquestion) . "\n";
     991                      $writtencategories[] = $trackcategory;
     992                  }
     993              }
     994  
     995              // Add the question to result.
     996              if (!$checkcapabilities || question_has_capability_on($question, 'view')) {
     997                  $expquestion = $this->writequestion($question, $contextid);
     998                  // Don't add anything if witequestion returned nothing.
     999                  // This will permit qformat plugins to exclude some questions.
    1000                  if ($expquestion !== null) {
    1001                      $expout .= $expquestion . "\n";
    1002                      $count++;
    1003                  }
    1004              }
    1005          }
    1006  
    1007          // continue path for following error checks
    1008          $course = $this->course;
    1009          $continuepath = "{$CFG->wwwroot}/question/export.php?courseid={$course->id}";
    1010  
    1011          // did we actually process anything
    1012          if ($count==0) {
    1013              print_error('noquestions', 'question', $continuepath);
    1014          }
    1015  
    1016          // final pre-process on exported data
    1017          $expout = $this->presave_process($expout);
    1018          return $expout;
    1019      }
    1020  
    1021      /**
    1022       * Create 'dummy' question for category export.
    1023       * @param string $categoryname the name of the category
    1024       * @param object $categoryinfo description of the category
    1025       * @return stdClass 'dummy' question for category
    1026       */
    1027      protected function create_dummy_question_representing_category(string $categoryname, $categoryinfo) {
    1028          $dummyquestion = new stdClass();
    1029          $dummyquestion->qtype = 'category';
    1030          $dummyquestion->category = $categoryname;
    1031          $dummyquestion->id = 0;
    1032          $dummyquestion->questiontextformat = '';
    1033          $dummyquestion->contextid = 0;
    1034          $dummyquestion->info = $categoryinfo->info;
    1035          $dummyquestion->infoformat = $categoryinfo->infoformat;
    1036          $dummyquestion->idnumber = $categoryinfo->idnumber;
    1037          $dummyquestion->name = 'Switch category to ' . $categoryname;
    1038          return $dummyquestion;
    1039      }
    1040  
    1041      /**
    1042       * get the category as a path (e.g., tom/dick/harry)
    1043       * @param int id the id of the most nested catgory
    1044       * @return string the path
    1045       */
    1046      protected function get_category_path($id, $includecontext = true) {
    1047          global $DB;
    1048  
    1049          if (!$category = $DB->get_record('question_categories', array('id' => $id))) {
    1050              print_error('cannotfindcategory', 'error', '', $id);
    1051          }
    1052          $contextstring = $this->translator->context_to_string($category->contextid);
    1053  
    1054          $pathsections = array();
    1055          do {
    1056              $pathsections[] = $category->name;
    1057              $id = $category->parent;
    1058          } while ($category = $DB->get_record('question_categories', array('id' => $id)));
    1059  
    1060          if ($includecontext) {
    1061              $pathsections[] = '$' . $contextstring . '$';
    1062          }
    1063  
    1064          $path = $this->assemble_category_path(array_reverse($pathsections));
    1065  
    1066          return $path;
    1067      }
    1068  
    1069      /**
    1070       * Convert a list of category names, possibly preceeded by one of the
    1071       * context tokens like $course$, into a string representation of the
    1072       * category path.
    1073       *
    1074       * Names are separated by / delimiters. And /s in the name are replaced by //.
    1075       *
    1076       * To reverse the process and split the paths into names, use
    1077       * {@link split_category_path()}.
    1078       *
    1079       * @param array $names
    1080       * @return string
    1081       */
    1082      protected function assemble_category_path($names) {
    1083          $escapednames = array();
    1084          foreach ($names as $name) {
    1085              $escapedname = str_replace('/', '//', $name);
    1086              if (substr($escapedname, 0, 1) == '/') {
    1087                  $escapedname = ' ' . $escapedname;
    1088              }
    1089              if (substr($escapedname, -1) == '/') {
    1090                  $escapedname = $escapedname . ' ';
    1091              }
    1092              $escapednames[] = $escapedname;
    1093          }
    1094          return implode('/', $escapednames);
    1095      }
    1096  
    1097      /**
    1098       * Convert a string, as returned by {@link assemble_category_path()},
    1099       * back into an array of category names.
    1100       *
    1101       * Each category name is cleaned by a call to clean_param(, PARAM_TEXT),
    1102       * which matches the cleaning in question/category_form.php.
    1103       *
    1104       * @param string $path
    1105       * @return array of category names.
    1106       */
    1107      protected function split_category_path($path) {
    1108          $rawnames = preg_split('~(?<!/)/(?!/)~', $path);
    1109          $names = array();
    1110          foreach ($rawnames as $rawname) {
    1111              $names[] = clean_param(trim(str_replace('//', '/', $rawname)), PARAM_TEXT);
    1112          }
    1113          return $names;
    1114      }
    1115  
    1116      /**
    1117       * Do an post-processing that may be required
    1118       * @return bool success
    1119       */
    1120      protected function exportpostprocess() {
    1121          return true;
    1122      }
    1123  
    1124      /**
    1125       * convert a single question object into text output in the given
    1126       * format.
    1127       * This must be overriden
    1128       * @param object question question object
    1129       * @return mixed question export text or null if not implemented
    1130       */
    1131      protected function writequestion($question) {
    1132          // if not overidden, then this is an error.
    1133          throw new coding_exception('Question format plugin is missing important code: writequestion.');
    1134          return null;
    1135      }
    1136  
    1137      /**
    1138       * Convert the question text to plain text, so it can safely be displayed
    1139       * during import to let the user see roughly what is going on.
    1140       */
    1141      protected function format_question_text($question) {
    1142          return s(question_utils::to_plain_text($question->questiontext,
    1143                  $question->questiontextformat));
    1144      }
    1145  }
    1146  
    1147  class qformat_based_on_xml extends qformat_default {
    1148  
    1149      /**
    1150       * A lot of imported files contain unwanted entities.
    1151       * This method tries to clean up all known problems.
    1152       * @param string str string to correct
    1153       * @return string the corrected string
    1154       */
    1155      public function cleaninput($str) {
    1156  
    1157          $html_code_list = array(
    1158              "&#039;" => "'",
    1159              "&#8217;" => "'",
    1160              "&#8220;" => "\"",
    1161              "&#8221;" => "\"",
    1162              "&#8211;" => "-",
    1163              "&#8212;" => "-",
    1164          );
    1165          $str = strtr($str, $html_code_list);
    1166          // Use core_text entities_to_utf8 function to convert only numerical entities.
    1167          $str = core_text::entities_to_utf8($str, false);
    1168          return $str;
    1169      }
    1170  
    1171      /**
    1172       * Return the array moodle is expecting
    1173       * for an HTML text. No processing is done on $text.
    1174       * qformat classes that want to process $text
    1175       * for instance to import external images files
    1176       * and recode urls in $text must overwrite this method.
    1177       * @param array $text some HTML text string
    1178       * @return array with keys text, format and files.
    1179       */
    1180      public function text_field($text) {
    1181          return array(
    1182              'text' => trim($text),
    1183              'format' => FORMAT_HTML,
    1184              'files' => array(),
    1185          );
    1186      }
    1187  
    1188      /**
    1189       * Return the value of a node, given a path to the node
    1190       * if it doesn't exist return the default value.
    1191       * @param array xml data to read
    1192       * @param array path path to node expressed as array
    1193       * @param mixed default
    1194       * @param bool istext process as text
    1195       * @param string error if set value must exist, return false and issue message if not
    1196       * @return mixed value
    1197       */
    1198      public function getpath($xml, $path, $default, $istext=false, $error='') {
    1199          foreach ($path as $index) {
    1200              if (!isset($xml[$index])) {
    1201                  if (!empty($error)) {
    1202                      $this->error($error);
    1203                      return false;
    1204                  } else {
    1205                      return $default;
    1206                  }
    1207              }
    1208  
    1209              $xml = $xml[$index];
    1210          }
    1211  
    1212          if ($istext) {
    1213              if (!is_string($xml)) {
    1214                  $this->error(get_string('invalidxml', 'qformat_xml'));
    1215              }
    1216              $xml = trim($xml);
    1217          }
    1218  
    1219          return $xml;
    1220      }
    1221  }