README

The H5P Caretaker is a library that is supposed to help people take care of H5P content types. It expects an H5P content files as input and will return a JSON object that contains structured information about issues that may hinder sharing the content, e.g. missing alternative texts for images, missing or incompatible license information of subcontent, etc.

Installation

This library is not meant to be used standalone. The common use case is to use it as a dependency for your own application, e.g. inside a plugin of some kind or as a standalone application.

In fact, there is a reference H5P Caretaker client which displays the results found by this library and a PHP based reference H5P Caretaker server that glues this library to the client.

Using the library

In your own project, you can use common composer practices to use this library. Inside your composer.json file, you should add an entry like this:

"require": {
    "ndlano/h5p-caretaker": "^1.1.0"
}

and then run composer update or run composer require ndlano/h5p-caretaker that should do the same.

The common use case then is to fetch an H5P content file (.h5p), pass it to the library and then to further process the results.

Your own project either uses the common autoload procedure itself, meaning that the library will be loaded as a depencency automatically. Alternatively, you'll have to run something like

require_once __DIR__ . '/vendor/autoload.php';
use Ndlano\H5PCaretaker\H5PCaretaker;

You many need to adjust the path, of course, depending on where your PHP code lives at.

Instantiating

You can then instantiate an H5PCaretaker instance via something like.

$h5pCaretaker = new H5PCaretaker($config);

$config is expected to be an associative array like this:

Property	Type	Description	Required
locale	String	ISO 639 Set 1 language code, representing the requested language for the reporting data. Default: en	Optional
uploadsPath	String	Path to where the H5P content files may be unpacked to temporarily. Default: `uploads` inside the h5p-caretaker folder (must be writable by server)	Optional
cachePath	String	Path to where external reports that are fetched from the web can be cached. Default: `cache` inside the h5p-caretaker folder (must be writable by server)	Optional
cacheTimeout	Int	Define how long (in seconds) external ressources (e.g. Libretext accessibility data) will be cached. _Default: `86400` (24 hours)	Optional

After instantiating, you can use certain methods

analyze($params: array) => array

Use analyze to retrieve the report.

$params is expected to be an associative array that at least contains the file path to the H5P content that is supposed to be analyzed.

Property	Type	Description	Required
file	String	File path to H5P content file that should be analyzed.	Required

More properties may become available in the future in order to tweak the analysis.

The return value is going to be a JSON object represented in an associative array. Please refer to the report properties documentation for details.

write($changes: array) => array

Use to receive a modified version of the file

Property	Type	Description	Required
file	String	File path to H5P content file that should be modified.	Required
changes	array	Array of change objects	Required

A change object represents a change that should be performed on the H5P file parameters: in h5p.json or content.json and potentially in the content folder. The object will look like:

Property	Type	Description	Required
uuid	String	Unique identifier for the change	Required
semanticsPath	String	Path to field in semantics where change is due. Starts with `root` for changes to the main content metadata	Required
filePath	String	Relative path to file inside `content`. Needs to be set when files are supposed to be changed.	Optional
value	String	Valut that the semantics field should be set to or command for file changes.	Required

Currently, these commands for file changes are available:

scale-down height|width pixels: Scale down an image to a height/width of pixels (number) while preserving the aspect ratio and the file type.
convert jpeg/png/gif/bmp: Convert an image to the respective image file type.

Contribution

If you think that some feature of the H5P content should be checked, please raise an issue in order to discuss it. Please note though that this library does not render the content, but merely assesses the parmeters, media and libraries that are found on the server. Therefore, it is e.g. not possible to detect contrast issues impeding accessibility, etc.

If you want to contribute code, you are welcome. Please also raise an issue beforehand to talk about your ideas. Please see the coding information documentation for technical details.

If you want to contribute translation, you will find easily understandable translation files in app/lang.

Future Development

There are some ideas on what this library should be able to do in the future:

Allow to use large language models to fill in missing data, e.g. set missing alternative texts for images.

ndlano / h5p-caretaker

Maintainers

Details