## General plugins (Local): Changelog Lib

local_changeloglib
Maintained by Hendrik Würz, Guido Roessling
This plugin provides helper methods to handle the backup process of files which are required for a changelog generation.
28 sites

# 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
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/>;.


## Requirements

• Tested with Moodle 3.4+
• For the diff detection, the command line tools poppler-utils and diff are required.

## Installation

1. 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.
sudo apt install -y poppler-utils
pdftotext -h
The last command should print the usage information for pdftotext. Please ensure that the installation was successful.
2. 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.
diff --help
3. 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
4. Browse to Site Administration -> Notifications and allow the database upgrades to execute

## Tests

This plugin provides tests for the main functions. To run them please follow the next steps:

2. Install the plugin.
3. Run the tests
cd /path/to/moodle/home
vendor/bin/phpunit --group local_changeloglib

## Features

### Backup-Lib

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$data Additional 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_from The context ID of the file which should be backuped • @param string$component_from The component of the file which should be backuped
• @param string $filearea_from The filearea of the file which should be backuped • @param int$itemid_from The itemid of the file which should be backuped
• @param int $context_id_to The new context under which the backup should be stored • @param int$scope_id The 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: get_backup_file($backup): null|stored_file • @param object$backup The database backup record.
• @return stored_file|null The 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(): void Removes 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(): void Deletes all backup files.
• clean_up_selected($context,$scope): void Deletes all backup files with the passed context and scope. $contextand $scope are integers with the IDs.
• clean_up_id($backup_id): void Delete the backup with the passed ID (integer). This ID is the primary key in the database and the itemid of the file instance. ### Update detector 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_files The new files whose predecessors should be found.
• @param int $context The context of the file and its predecessor. (Resources: The course context) • @param int$scope The scope of the file and its predecessor within the context. (In courses: the section)
• @param stored_file[] $further_candidates All 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): void Whether 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_type Whether the MIME type of the candidates must match or not. • set_min_similarity($min_similarity): void If 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 stored_file $file The file which should be converted. • @return bool|string Returns false if file could not be converted or a string with the path of the generated text file. ### Diff detector 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_file The filename and path for the first text document.
• @param string \$second_file The filename and path for the second text document.
• get_info(): string Get a string with all pages containing changes, separated by comma.
• @return string A string which can be printed to the user.
• has_acceptable_amount_of_changes(): bool Checks 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(): bool Checks whether the command line tool diff is installed. This tool is required to search for differences in txt files.