Changeloglib Plugin for Moodle
This plugin provides helper methods to handle the backup process of files which are required for a changelog generation. This plugin will analyse the files and detect changes. Currently all file types are supported for backup and PDF documents can be used for difference detection.
Without any other plugins this will not do anything.
Copyright (c) 2017 Hendrik Wuerz This program 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. This program 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 this program. If not, see <http://www.gnu.org/licenses/>.
- Tested with Moodle 3.4+
- For the diff detection, the command line tools poppler-utils and diff are required.
- Install the package poppler-utils for difference detection. This step is optional but recommended. If you skip the installation, the difference detection will not be available.The last command should print the usage information for pdftotext. Please ensure that the installation was successful.
sudo apt install -y poppler-utils pdftotext -h
- Ensure that the tool diff is installed on your system. It should be included in every Ubuntu or Linux distribution. The following command should print some help text. If it is not available please install it following the documentation for your system. This tool is optional but recommended. If it is not installed, the difference detection is not possible.
- Clone the repo inside MOODLE_HOME/local/changeloglib
cd path/to/moodle/home git clone https://github.com/hwuerz/moodle-local_changeloglib.git local/changeloglib
- Browse to
Notificationsand allow the database upgrades to execute
This plugin provides tests for the main functions. To run them please follow the next steps:
- Install PHPUnit on your system and configure moodle. See https://docs.moodle.org/dev/PHPUnit for more information.
- Install the plugin.
- Run the tests
cd /path/to/moodle/home php admin/tool/phpunit/cli/init.php vendor/bin/phpunit --group local_changeloglib
To detect updates, the plugin must backup old materials. These backups can later be used to find a predecessor of a new file. As soon as a file becomes deleted, you should call the backup function which will create an own copy of the document. Because of the intelligent file system API of moodle, no hard disc copy will be performed. For every backup only one database record will be created.
Use the class
local_changeloglib_backup_lib to manage your backups. It has six public functions:
- Backup a file before it will be deleted:
backup(array $data, $context_id_from, $component_from, $filearea_from, $itemid_from = 0, $context_id_to, $scope_id): void
@param array $dataAdditional data which is used to identify a definite predecessor. Use this to exclude all other candidates when you can ensure fitting IDs.
@param int $context_id_fromThe context ID of the file which should be backuped
@param string $component_fromThe component of the file which should be backuped
@param string $filearea_fromThe filearea of the file which should be backuped
@param int $itemid_fromThe itemid of the file which should be backuped
@param int $context_id_toThe new context under which the backup should be stored
@param int $scope_idThe scope within the context. (For resources this is the section within the course) The scope of a predecessor must be identically to the new file.
- Get the stored_file instance of a backup:
@param object $backupThe database backup record.
@return stored_file|nullThe file instances of the backup or null if no file exists.
- Clean up backups which are nor longer required. The plugin removes old files automatically, but maybe you want to remove some files manually.
clean_up_old_files(): voidRemoves backups which are older than one hour. This function is automatically called. You can invoke it manually but this should not be needed.
clean_up_all_files(): voidDeletes all backup files.
clean_up_selected($context, $scope): voidDeletes all backup files with the passed context and scope.
$scopeare integers with the IDs.
clean_up_id($backup_id): voidDelete the backup with the passed ID (integer). This ID is the primary key in the database and the itemid of the file instance.
The update detector
local_changeloglib_update_detector checks whether one file is an update of another. Use it to find the most probable predecessor of a new file.
__construct(array $new_files, $context, $scope, array $further_candidates)
@param local_changeloglib_new_file_wrapper $new_filesThe new files whose predecessors should be found.
@param int $contextThe context of the file and its predecessor. (Resources: The course context)
@param int $scopeThe scope of the file and its predecessor within the context. (In courses: the section)
@param stored_file $further_candidatesAll other files which should be checked as predecessor. Use this if candidates exists which are not in the backup table.
set_ensure_mime_type($ensure_mime_type): voidWhether this detector should ensure that the MIME type of the found predecessor matches the MIME type of the new file. If this value is true, all candidates with not matching type will be skipped. If this value is false, the MIME Type will be handled as a similarity property. Default value is true.
@param bool $ensure_mime_typeWhether the MIME type of the candidates must match or not.
set_min_similarity($min_similarity): voidIf the similarity is below this value, a file will be rejected as a predecessor. Adjust this value to define a level of similarity you want to ensure. Default is 0.5
@param float $min_similarityThe minimum similarity a predecessor must have in the range [0, 1].
map_backups(): local_changeloglib_update_detector_distributionMaps the backups to a new file.
@return local_changeloglib_update_detector_distributionThe best distribution of backups for the new files.
local_changeloglib_pdftotext is a wrapper to access the command line tool pdftotext from poppler-utils.
is_installed(): boolChecks whether the command line tool pdftotext is installed. This tool is required to convert a pdf file to a text document for diff detection.
convert_to_txt(stored_file $file): bool|stringTries to convert the passed file in a text document. Conversion is only possible if pdftotext is available and a PDF document was passed.
@param stored_file $fileThe file which should be converted.
@return bool|stringReturns false if file could not be converted or a string with the path of the generated text file.
The diff detector
local_changeloglib_diff_detector can identify the pages on which changes were performed. It requires the command line tool diff and analyses text documents.
__construct($first_file, $second_file)Creates a new detector for the two files.
@param string $first_fileThe filename and path for the first text document.
@param string $second_fileThe filename and path for the second text document.
get_info(): stringGet a string with all pages containing changes, separated by comma.
@return stringA string which can be printed to the user.
has_acceptable_amount_of_changes(): boolChecks whether there are more changes than allowed for a predecessor. Allowed means: Not more than half of the pages contains changes and not more than half of the lines in the documents are changed.
is_command_line_diff_installed(): boolChecks whether the command line tool diff is installed. This tool is required to search for differences in txt files.