Proyectos de Subversion Moodle

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace mod_data\local\exporter;

use file_serving_exception;
use moodle_exception;
use zip_archive;

/**
 * Exporter class for exporting data and - if needed - files as well in a zip archive.
 *
 * @package    mod_data
 * @copyright  2023 ISB Bayern
 * @author     Philipp Memmel
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class entries_exporter {

    /** @var int Tracks the currently edited row of the export data file. */
    private int $currentrow;

    /**
     * @var array The data structure containing the data for exporting. It's a 2-dimensional array of
     *  rows and columns.
     */
    protected array $exportdata;

    /** @var string Name of the export file name without extension. */
    protected string $exportfilename;

    /** @var zip_archive The zip archive object we store all the files in, if we need to export files as well. */
    private zip_archive $ziparchive;

    /** @var bool Tracks the state if the zip archive already has been closed. */
    private bool $isziparchiveclosed;

    /** @var string full path of the zip archive. */
    private string $zipfilepath;

    /** @var array Array to store all filenames in the zip archive for export. */
    private array $filenamesinzip;

    /**
     * Creates an entries_exporter object.
     *
     * This object can be used to export data to different formats including files. If files are added,
     * everything will be bundled up in a zip archive.
     */
    public function __construct() {
        $this->currentrow = 0;
        $this->exportdata = [];
        $this->exportfilename = 'Exportfile';
        $this->filenamesinzip = [];
        $this->isziparchiveclosed = true;
    }

    /**
     * Adds a row (array of strings) to the export data.
     *
     * @param array $row the row to add, $row has to be a plain array of strings
     * @return void
     */
    public function add_row(array $row): void {
        $this->exportdata[] = $row;
        $this->currentrow++;
    }

    /**
     * Adds a data string (so the content for a "cell") to the current row.
     *
     * @param string $cellcontent the content to add to the current row
     * @return void
     */
    public function add_to_current_row(string $cellcontent): void {
        $this->exportdata[$this->currentrow][] = $cellcontent;
    }

    /**
     * Signal the entries_exporter to finish the current row and jump to the next row.
     *
     * @return void
     */
    public function next_row(): void {
        $this->currentrow++;
    }

    /**
     * Sets the name of the export file.
     *
     * Only use the basename without path and without extension here.
     *
     * @param string $exportfilename name of the file without path and extension
     * @return void
     */
    public function set_export_file_name(string $exportfilename): void {
        $this->exportfilename = $exportfilename;
    }

    /**
     * The entries_exporter will prepare a data file from the rows and columns being added.
     * Overwrite this method to generate the data file as string.
     *
     * @return string the data file as a string
     */
    abstract protected function get_data_file_content(): string;

    /**
     * Overwrite the method to return the file extension your data file will have, for example
     * <code>return 'csv';</code> for a csv file entries_exporter.
     *
     * @return string the file extension of the data file your entries_exporter is using
     */
    abstract protected function get_export_data_file_extension(): string;

    /**
     * Returns the count of currently stored records (rows excluding header row).
     *
     * @return int the count of records/rows
     */
    public function get_records_count(): int {
        // The attribute $this->exportdata also contains a header. If only one row is present, this
        // usually is the header, so record count should be 0.
        if (count($this->exportdata) <= 1) {
            return 0;
        }
        return count($this->exportdata) - 1;
    }

    /**
     * Use this method to add a file which should be exported to the entries_exporter.
     *
     * @param string $filename the name of the file which should be added
     * @param string $filecontent the content of the file as a string
     * @param string $zipsubdir the subdirectory in the zip archive. Defaults to 'files/'.
     * @return void
     * @throws moodle_exception if there is an error adding the file to the zip archive
     */
    public function add_file_from_string(string $filename, string $filecontent, string $zipsubdir = 'files/'): void {
        if (empty($this->filenamesinzip)) {
            // No files added yet, so we need to create a zip archive.
            $this->create_zip_archive();
        }
        if (!str_ends_with($zipsubdir, '/')) {
            $zipsubdir .= '/';
        }
        $zipfilename = $zipsubdir . $filename;
        $this->filenamesinzip[] = $zipfilename;
        $this->ziparchive->add_file_from_string($zipfilename, $filecontent);
    }

    /**
     * Sends the generated export file.
     *
     * Care: By default this function finishes the current PHP request and directly serves the file to the user as download.
     *
     * @param bool $sendtouser true if the file should be sent directly to the user, if false the file content will be returned
     *  as string
     * @return string|null file content as string if $sendtouser is true
     * @throws moodle_exception if there is an issue adding the data file
     * @throws file_serving_exception if the file could not be served properly
     */
    public function send_file(bool $sendtouser = true): null|string {
        if (empty($this->filenamesinzip)) {
            if ($sendtouser) {
                send_file($this->get_data_file_content(),
                    $this->exportfilename . '.' . $this->get_export_data_file_extension(),
                    null, 0, true, true);
                return null;
            } else {
                return $this->get_data_file_content();
            }
        }
        $this->add_file_from_string($this->exportfilename . '.' . $this->get_export_data_file_extension(),
            $this->get_data_file_content(), '/');
        $this->finish_zip_archive();

        if ($this->isziparchiveclosed) {
            if ($sendtouser) {
                send_file($this->zipfilepath, $this->exportfilename . '.zip', null, 0, false, true);
                return null;
            } else {
                return file_get_contents($this->zipfilepath);
            }
        } else {
            throw new file_serving_exception('Could not serve zip file, it could not be closed properly.');
        }
    }

    /**
     * Checks if a file with the given name has already been added to the file export bundle.
     *
     * Care: Filenames are compared to all files in the specified zip subdirectory which
     *  defaults to 'files/'.
     *
     * @param string $filename the filename containing the zip path of the file to check
     * @param string $zipsubdir The subdirectory in which the filename should be looked for,
     *  defaults to 'files/'
     * @return bool true if file with the given name already exists, false otherwise
     */
    public function file_exists(string $filename, string $zipsubdir = 'files/'): bool {
        if (!str_ends_with($zipsubdir, '/')) {
            $zipsubdir .= '/';
        }
        if (empty($filename)) {
            return false;
        }
        return in_array($zipsubdir . $filename, $this->filenamesinzip, true);
    }

    /**
     * Creates a unique filename based on the given filename.
     *
     * This method adds "_1", "_2", ... to the given file name until the newly generated filename
     * is not equal to any of the already saved ones in the export file bundle.
     *
     * @param string $filename the filename based on which a unique filename should be generated
     * @return string the unique filename
     */
    public function create_unique_filename(string $filename): string {
        if (!$this->file_exists($filename)) {
            return $filename;
        }

        $extension = pathinfo($filename, PATHINFO_EXTENSION);
        $filenamewithoutextension = empty($extension)
            ? $filename
            : substr($filename, 0,strlen($filename) - strlen($extension) - 1);
        $filenamewithoutextension = $filenamewithoutextension . '_1';
        $i = 1;
        $filename = empty($extension) ? $filenamewithoutextension : $filenamewithoutextension . '.' . $extension;
        while ($this->file_exists($filename)) {
            // In case we have already a file ending with '_XX' where XX is an ascending number, we have to
            // remove '_XX' first before adding '_YY' again where YY is the successor of XX.
            $filenamewithoutextension = preg_replace('/_' . $i . '$/', '_' . ($i + 1), $filenamewithoutextension);
            $filename = empty($extension) ? $filenamewithoutextension : $filenamewithoutextension . '.' . $extension;
            $i++;
        }
        return $filename;
    }

    /**
     * Prepares the zip archive.
     *
     * @return void
     */
    private function create_zip_archive(): void {
        $tmpdir = make_request_directory();
        $this->zipfilepath = $tmpdir . '/' . $this->exportfilename . '.zip';
        $this->ziparchive = new zip_archive();
        $this->isziparchiveclosed = !$this->ziparchive->open($this->zipfilepath);
    }

    /**
     * Closes the zip archive.
     *
     * @return void
     */
    private function finish_zip_archive(): void {
        if (!$this->isziparchiveclosed) {
            $this->isziparchiveclosed = $this->ziparchive->close();
        }
    }
}