lib/filestorage/file_packer.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  * Abstraction of general file packer.
  19  *
  20  * @package   core_files
  21  * @copyright 2008 Petr Skoda (http://skodak.org)
  22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 /**
  28  * Abstract class for archiving of files.
  29  *
  30  * @package   core_files
  31  * @copyright 2008 Petr Skoda (http://skodak.org)
  32  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  33  */
  34 abstract class file_packer {
  35     /**
  36      * Archive files and store the result in file storage.
  37      *
  38      * The key of the $files array is always the path within the archive, e.g.
  39      * 'folder/subfolder/file.txt'. There are several options for the values of
  40      * the array:
  41      * - null = this entry represents a directory, so no file
  42      * - string = full path to file within operating system filesystem
  43      * - stored_file = file within Moodle filesystem
  44      * - array with one string element = use in-memory string for file content
  45      *
  46      * For the string (OS path) and stored_file (Moodle filesystem) cases, you
  47      * can specify a directory instead of a file to recursively include all files
  48      * within this directory.
  49      *
  50      * @param array $files Array of files to archive
  51      * @param int $contextid context ID
  52      * @param string $component component
  53      * @param string $filearea file area
  54      * @param int $itemid item ID
  55      * @param string $filepath file path
  56      * @param string $filename file name
  57      * @param int $userid user ID
  58      * @param bool $ignoreinvalidfiles true means ignore missing or invalid files, false means abort on any error
  59      * @param file_progress $progress Progress indicator callback or null if not required
  60      * @return stored_file|bool false if error stored_file instance if ok
  61      */
  62     public abstract function archive_to_storage(array $files, $contextid,
  63             $component, $filearea, $itemid, $filepath, $filename,
  64             $userid = NULL, $ignoreinvalidfiles=true, file_progress $progress = null);
  65
  66     /**
  67      * Archive files and store the result in os file.
  68      *
  69      * The key of the $files array is always the path within the archive, e.g.
  70      * 'folder/subfolder/file.txt'. There are several options for the values of
  71      * the array:
  72      * - null = this entry represents a directory, so no file
  73      * - string = full path to file within operating system filesystem
  74      * - stored_file = file within Moodle filesystem
  75      * - array with one string element = use in-memory string for file content
  76      *
  77      * For the string (OS path) and stored_file (Moodle filesystem) cases, you
  78      * can specify a directory instead of a file to recursively include all files
  79      * within this directory.
  80      *
  81      * @param array $files array with zip paths as keys (archivepath=>ospathname or archivepath=>stored_file)
  82      * @param string $archivefile path to target zip file
  83      * @param bool $ignoreinvalidfiles true means ignore missing or invalid files, false means abort on any error
  84      * @param file_progress $progress Progress indicator callback or null if not required
  85      * @return bool true if file created, false if not
  86      */
  87     public abstract function archive_to_pathname(array $files, $archivefile,
  88             $ignoreinvalidfiles=true, file_progress $progress = null);
  89
  90     /**
  91      * Extract file to given file path (real OS filesystem), existing files are overwritten.
  92      *
  93      * @param stored_file|string $archivefile full pathname of zip file or stored_file instance
  94      * @param string $pathname target directory
  95      * @param array $onlyfiles only extract files present in the array
  96      * @param file_progress $progress Progress indicator callback or null if not required
  97      * @param bool $returnbool Whether to return a basic true/false indicating error state, or full per-file error
  98      * details.
  99      * @return array|bool list of processed files; false if error
 100      */
 101     public abstract function extract_to_pathname($archivefile, $pathname,
 102             array $onlyfiles = NULL, file_progress $progress = null, $returnbool = false);
 103
 104     /**
 105      * Extract file to given file path (real OS filesystem), existing files are overwritten.
 106      *
 107      * @param string|stored_file $archivefile full pathname of zip file or stored_file instance
 108      * @param int $contextid context ID
 109      * @param string $component component
 110      * @param string $filearea file area
 111      * @param int $itemid item ID
 112      * @param string $pathbase file path
 113      * @param int $userid user ID
 114      * @param file_progress $progress Progress indicator callback or null if not required
 115      * @return array|bool list of processed files; false if error
 116      */
 117     public abstract function extract_to_storage($archivefile, $contextid,
 118             $component, $filearea, $itemid, $pathbase, $userid = NULL,
 119             file_progress $progress = null);
 120
 121     /**
 122      * Returns array of info about all files in archive.
 123      *
 124      * @param string|file_archive $archivefile
 125      * @return array of file infos
 126      */
 127     public abstract function list_files($archivefile);
 128 }