ro-crate-php

This is a PHP tool to create and manipulate Research Object Crate.

Install

Install the tool using composer:

composer require gigascience/ro-crate-php

Docs

Inline phpDoc comments are written.

Usage

Create a new empty crate with the base path set to resources directory in the parent directory:

$crate = new ROCrate(__DIR__ . '/../resources', false);

The ROCrate constructor enables the creation of a crate using an existing metadata file:

$crate = new ROCrate(__DIR__ . '/../resources', true);

Add an entity to the crate:

// A person
$author = $crate->createGenericEntity('#alice', ['Person']);
$author->addProperty('name', 'Alice Smith');
$author->addProperty('affiliation', 'Institution of Example');
// Add the person to the crate
$crate->addEntity($author);

// Adds the person as one of the creators of the root data entity, i.e. the dataset being described by the crate
$root = $crate->getRootDataset();
$root->addPropertyPair('creator', '#alice', true);

Interact with the crate just like normal objects with methods:

$crate->addEntity($author);
$crate->removeEntity($author->getId());

RECOMMENDED: Chain up the methods to enhance the compactness of the code when adding/removing properties of an entity:

$root->addPropertyPair('creator', '#bob', true)
  ->addPropertyPair('creator', '#cathy')
  ->removePropertyPair('creator', '#alice')
  ->addPropertyPair('creator', '#alice');

The methods of addPropertyPair and removePropertyPair abstract away the details about the file formatting. The user only has to provide the key for the property of the entity and the value to be added to or removed from the property. An optional boolean argument is to tell whether the value should be treated as a plain literal with false or as an identifier referencing other entity in the crate. By default, the flag is set to be comply with the previous value of this property if any.

HTML Rendering

Use the following code to generate a human-readable HTML preview from the RO-Crate Metadata File.

ROCratePreviewGenerator::generatePreview(__DIR__ . '/../resources');

Change Log

Please refer to CHANGELOG.md in the repository.

GigaDB Example

An example based on GigaDB dataset 102736 is generated using the code in index.php to illustarte how the tool can be utilized with the general steps in Guide.md in the repository. The inforamtion to generate the metadata file is mainly from the Website. The example ro-crate-metadata.json and ro-crate-preview.html are stored in the assets directory. To make the file easier to read, only the first 2 files and a zipped file treated as a directory are included, where the remaining files are described using a collective directory construct. To ensure integribility and compatibility with other/downstream applications, the metadata file of this example is imported into RoHub for testing, where the about property of the metadat descriptor and the id of the root data entity are replaced with ./ to be backward compatible to the RO-Crate 1.1 standard adopted by RoHub.