Skip to content

Latest commit

 

History

History
202 lines (141 loc) · 9 KB

README.md

File metadata and controls

202 lines (141 loc) · 9 KB
Raw

Flysystem RDF Converter Plugin

Project stage: Development License Latest Version Maintained

PDS Interop standard-readme compliant keep-a-changelog compliant

Flysystem plugin to transform RDF data between various serialization formats.

When using RDF, you will notice there are several different popular serialization formats. Instead of having to store data in multiple formats, it is easier to store the data in one format and convert it to others as needed.

This project contains a plugin to be used with Flysystem to do just that.

For the conversion EasyRDF is used. Any formats supported by EasyRDF are available from this plugin.

Currently supported formats are:

  • JSON-LD
  • N-triples
  • Notation 3 / N3
  • RDF/XML
  • Turtle

Table of Contents

Background

This project is part of the PHP stack of projects by PDS Interop. It is used by both the Solid-Nextcloud app and the standalone PHP Solid server.

As the functionality seemed useful for other projects, it was implemented as a separate package.

Installation

The advised install method is through composer:

composer require pdsinterop/flysystem-rdf

PHP version 7.3 and higher is supported. The mbstring extension needs to be enabled in order for this package to work.

Usage

This package offers features to read files from a Filesystem that have been stored in one RDF format as another format.

These features are provided by a plugin and an adapter.

The plugin is best suited for light-weight scenarios where all you want to do is convert a file to another format.

The adapter is best suited for full-featured usage of Flysystem, as it also handles calls to has and getMimeType correctly (which the plugin does not)

Adapter

To use the adapter, instantiate it, add it to a Flysystem filesystem and add the helper plugin.

<?php

// Create Formats objects
$formats = new \Pdsinterop\Rdf\Formats();

// Use an adapter of your choice
$adapter = new League\Flysystem\Adapter\Local('/path/to/files/');

// Create the RDF Adapter
$rdfAdapter = new \Pdsinterop\Rdf\Flysystem\Adapter\Rdf(
    $adapter,
    new \EasyRdf\Graph(),
    $formats,
    'server'
);

// Create Flysystem as usual, adding the RDF Adapter
$filesystem = new League\Flysystem\Filesystem($rdfAdapter);

// Add the `AsMime` plugin to convert contents based on a provided MIME type, 
$filesystem->addPlugin(new \Pdsinterop\Rdf\Flysystem\Plugin\AsMime($formats));

// Read the contents of a file in the format it was stored in
$content = $filesystem->read('/foaf.rdf');

// Read the contents of a file in another format from what was stored in
$convertedContents = $filesystem
    ->asMime('text/turtle')
    ->read('/foaf.rdf');

// Get the MIME type of the format the requested mime-type would return
// This is especially useful for RDF formats that can be requested with several
// different MIME types.
$convertedMimeType = $filesystem
    ->asMime('text/turtle')
    ->getMimetype('/foaf.rdf');

// This also works for `has`
$hasConvertedContents = $filesystem
    ->asMime('text/turtle')
    ->has('/foaf.ttl');

// Without using the plugin, this will be false
$hasContents = $filesystem->has('/foaf.ttl');

The adapter adds any found .meta files that reference a file to that file's metadata, which can be retrieved with $filesystem->getMetadata($path).

Plugin

To use the plugin, instantiate it and add it to a Flysystem filesystem.

The function readRdf can then be called to get RDF files in a specific format:

<?php

// Create Flysystem as usual, adding an adapter of your choice
$adapter = new League\Flysystem\Adapter\Local('/path/to/files/');
$filesystem = new League\Flysystem\Filesystem($adapter);

// create and add the RdF Plugin
$plugin = new \Pdsinterop\Rdf\Flysystem\Plugin\ReadRdf(new \EasyRdf\Graph());
$filesystem->addPlugin($plugin);

// Read the contents of a RDF file in another format from what was stored in
$content = $filesystem->readRdf('/foaf.rdf', \Pdsinterop\Rdf\Enum\Format::TURTLE);

Develop

  • Do not forget to install the required dependencies using composer.

  • Most of the logic here involves EasyRdf and/or FlySystem. You'll want to familiarise yourself with their workings.

  • Test are available in the tests/ directory. They are run by GitHub actions for any pull request. To run them,call ./bin/phpunit

  • The changelog can be automatically generated using github_changelog_generator with the provided configuration file

Contributing

Questions or feedback can be given by opening an issue on GitHub.

All PDS Interop projects are open source and community-friendly. Any contribution is welcome! For more details read the contribution guidelines.

All PDS Interop projects adhere to the Code Manifesto as its code-of-conduct. Contributors are expected to abide by its terms.

There is a list of all contributors on GitHub.

For a list of changes see the CHANGELOG or the GitHub releases page.

License

All code created by PDS Interop is licensed under the MIT License.