files/classes/archive_writer.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 archives.
  19  *
  20  * @package   core_files
  21  * @copyright 2020 Mark Nelson <mdjnelson@gmail.com>
  22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 namespace core_files;
  26
  27 use core_files\local\archive_writer\file_writer_interface as file_writer_interface;
  28 use core_files\local\archive_writer\stream_writer_interface as stream_writer_interface;
  29
  30 /**
  31  * Each file archive type must extend this class.
  32  *
  33  * @package   core_files
  34  * @copyright 2020 Mark Nelson <mdjnelson@gmail.com>
  35  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  36  */
  37 abstract class archive_writer {
  38
  39     /**
  40      * The zip writer class.
  41      */
  42     public const ZIP_WRITER = 'zip_writer';
  43
  44     /**
  45      * Returns the stream writer.
  46      *
  47      * @param string $filename
  48      * @param string $type
  49      * @return stream_writer_interface
  50      */
  51     public static function get_stream_writer(string $filename, string $type): stream_writer_interface {
  52         $classname = self::get_classname_for_type($type);
  53
  54         if (!is_a($classname, stream_writer_interface::class, true)) {
  55             throw new \InvalidArgumentException("{$type} does not support streaming");
  56         }
  57
  58         return $classname::stream_instance($filename);
  59     }
  60
  61     /**
  62      * Returns the file writer.
  63      *
  64      * @param string $filepath
  65      * @param string $type
  66      * @return file_writer_interface
  67      */
  68     public static function get_file_writer(string $filepath, string $type): file_writer_interface {
  69         $classname = self::get_classname_for_type($type);
  70
  71         if (!is_a($classname, file_writer_interface::class, true)) {
  72             throw new \InvalidArgumentException("{$type} does not support writing to files");
  73         }
  74
  75         return $classname::file_instance($filepath);
  76     }
  77
  78     /**
  79      * Sanitise the file path, removing any unsuitable characters.
  80      *
  81      * @param string $filepath
  82      * @return string
  83      */
  84     public function sanitise_filepath(string $filepath): string {
  85         return clean_param($filepath, PARAM_PATH);
  86     }
  87
  88     /**
  89      * Returns the class name for the type that was provided in get_file_writer().
  90      *
  91      * @param string $type
  92      * @return string
  93      */
  94     protected static function get_classname_for_type(string $type): string {
  95         return "core_files\local\archive_writer\\" . $type;
  96     }
  97
  98     /**
  99      * The archive_writer Constructor.
 100      */
 101     protected function __construct() {
 102
 103     }
 104
 105     /**
 106      * Adds a file from a file path.
 107      *
 108      * @param string $name The path of file in archive (including directory).
 109      * @param string $path The path to file on disk (note: paths should be encoded using
 110      *                     UNIX-style forward slashes -- e.g '/path/to/some/file').
 111      */
 112     abstract public function add_file_from_filepath(string $name, string $path): void;
 113
 114     /**
 115      * Adds a file from a string.
 116      *
 117      * @param string $name The path of file in archive (including directory).
 118      * @param string $data The contents of file
 119      */
 120     abstract public function add_file_from_string(string $name, string $data): void;
 121
 122     /**
 123      * Adds a file from a stream.
 124      *
 125      * @param string $name The path of file in archive (including directory).
 126      * @param resource $stream The contents of file as a stream resource
 127      */
 128     abstract public function add_file_from_stream(string $name, $stream): void;
 129
 130     /**
 131      * Adds a stored_file to archive.
 132      *
 133      * @param string $name The path of file in archive (including directory).
 134      * @param \stored_file $file
 135      */
 136     abstract public function add_file_from_stored_file(string $name, \stored_file $file): void;
 137
 138     /**
 139      * Finish writing the zip footer.
 140      */
 141     abstract public function finish(): void;
 142 }