Download the PHP package magicmonkey/metasya without Composer

Metasya

Metasya is a library allowing the management of embarked metadatas on diverse types of files, to manage the import of metadatas in an information system and the synchronization of the data between the information system and files with exiftool.

What is Exiftool ? Take a look here : https://www.sno.phy.queensu.ca/~phil/exiftool/

[TOC]

Install

1. You have to use Composer, a tool for dependency management in PHP :

   Metasya is enregistred as package on Packagist : https://packagist.org/packages/magicmonkey/metasya

   ​

2. To activate the autoloader, you may need to type the following command into the command line :

   ​

3. With operating system based on UNIX, the provided version of Exiftool by Metasya at least must have the execute permission for the owner :

   ​

4. You can write in a file like index.php a code that tests if Metasya that you have just downloaded really works :

Usage : Here we go !

The MetadataHelper

The MetadataHelper is the main class of Metasya.

Create the object

In order to manage metadata of a file you have to create a new MetadataHelper object with the path of the file.

Use the exiftool version installed on your computer

By default, Metasya uses the provided exiftool. However it's possible to use the one installed on your computer in two different ways :

Display errors

By default, Metasya displays errors returned by the tool Exiftool. However it's possible to not display it :

Version information

Various functions are available in order to get information about the version of exiftool.

Change the path of the file

If you have to change the path of the file, you can proceed as described bellow :

Execute his own exiftool command line

The next part is about taskers which allow you to manage files metadata thanks predefined commands. However, you can use the function "execute" in order to do specifically what you really want regardless of the path of the file given as parameter to the object metadataHelper.

Generate Sidecar file

Sidecar files, also known as buddy files or connected files, are computer files that store data (often metadata which is not supported by the format of a source file.

Note that by default the output path of the generated sidecar file is the folder which is called "metasya/Sidecar" and it's created at the root of your project. However you can specify an other path like this :

Notion of Taskers

The MetadataHelper object has several Taskers. Each Tasker brings features thanks the use of exiftool.

ReaderTasker

The ReaderTasker allows to read file's metadata. You can use 3 features which are :

read (\$selectedMetadata, \$excludedMetadata) :

• description : Allows to read all or some file's metadata without exiftool group option.
• params :
  • $selectedMetadata : array (default : null) : Indicates metadata you want to read.
  • $excludedMetadata : array (default : null) : Indicates metadata you won't to read.
• return : array | string

• examples :

  • Read all metadata

  • Read all XMP Dublin Core metadata except the XMP Dublin Core subject :

  • Read all metadata except XMP Photoshop and XMP Rights metadata :

readByGroup (\$selectedMetadata, \$num, \$excludedMetadata) :

• description : Allows to read all or some file's metadata with the group option -g[$num...] which organize output by tag group.

• params :

  • $selectedMetadata : array (default : null) : Indicates metadata you want to read.
  • $num : int (default : 0) : Indicates the level of group.
  • $excludedMetadata : array (default : null) : Indicates metadata you won't to read.
    • return : array | string
    • examples :

  • Read all metadata with the group level 1 :

  • Read all XMP Dublin Core metadata except the XMP Dublin Core subject with the group level 1 :

readWithPrefix (\$selectedMetadata, \$num, \$excludedMetadata) :

• description : Allows to read all or some file's metadata with the group option -G[$num...] which print group name before each tag.

• params :

  • $selectedMetadata : array (default : null) : Indicates metadata you want to read.
  • $num : int (default : 0) : Indicates the level of group.

  • $excludedMetadata : array (default : null) : Indicates metadata you won't to read.

    • return : array | string

    • examples :

      • Read all metadata :

      • Read all XMP Dublin Core metadata except the XMP Dublin Core subject with the group level 1:

WriterTasker

The WriterTasker allows to add metadata to a file or to edit file's metadata. You can use 3 features which are :

write (\$targetedMetadata, \$replace, \$overwrite) :

• description : Allows to add or edit some metadata of a file.

• params :

  • $targetedMetadata ( default : null ) : Indicates metadata you want to add or edit.
  • $replace ( default : true ) : Indicates if the metadata value must be replaced if the metadata already exists.
  • $overwrite ( default : true ) : Indicates if the addition or the modification must be applied to the original file or to a copy. It's corresponds to the use of the exiftool option -overwrite_original.
• return : string | null

• examples :

  • Write some XMP Dublin Core metadata :

  • Write XMP Dublin Core title only if it doesn't already exists :

writeFromJsonFile (\$jsonFilePath, \$replace, \$overwrite) :

• description : Same as write feature but from a json file.

• WARNING : Note that the json inside the json file must contains the metadata tag "SourceFile" with the path of the file used by the MetadataHelper Object as value.

• params :

  • $jsonFilePath ( default : null ) : Indicates the path of the json file which contains metadata tags to use.
  • $replace ( default : true ) : Indicates if the metadata value must be replaced if the metadata already exists.
  • $overwrite ( default : true ) : Indicates if the addition or the modification must be applied to the original file or to a copy. It's corresponds to the use of the exiftool option -overwrite_original.

• return : string | null

• examples :
  • Write metadata from json file :

writeFromJson (\$json, \$replace, \$overwrite) :

• description : Same as write feature but from a json string.

• WARNING : Note that the json string must contains the metadata tag "SourceFile" with the path of the file used by the MetadataHelper Object as value.

• params :

  • $json : Indicates the json string which contains metadata tags to use.
  • $replace ( default : true ) : Indicates if the metadata value must be replaced if the metadata already exists.
  • $overwrite ( default : true ) : Indicates if the addition or the modification must be applied to the original file or to a copy. It's corresponds to the use of the exiftool option -overwrite_original.

• return : string | null

• examples :
  • Write metadata from json file :

EraserTasker

The EraserTasker allows to remove file's metadata. Only one feature is available at this moment :

remove ($targetedMetadata, \$excludedMetadata, \$overwrite) :

• description : Allows to remove all or some file's metadata.
• params :
  • $targetedMetadata ( default : "all" ) : Indicates metadata you want to remove. Can be a String or an Array.
  • $excludedMetadata ( default : null ) : Indicates metadata you won't to remove. Can be a String or an Array.
  • $overwrite ( default : true ) : Indicates if the deletion must be applied to the original file or to a copy. It's corresponds to the use of the exiftool option -overwrite_original.

• return : string | null

• examples :

  • Remove all metadata :

  • Remove all XMP Dublin Core metadata except the XMP Dublin Core title :

The system of schemata

Metasya offers a system of schemata in order to easly manage metadata of files.

• What is a schema ? A schema can be a JSON file and/or an object which contains information like the shortcut of the schema, metadata properties, namespace, description ... There are two kinds of schema : the default schemata which are nominated by Metasya, and the user's schemata which are created by the user.

• What is the utility of this system ? With this system, you can use several schemata in order to read, write or delete a lot of metadata. This sytem it's a saving of time : you can just write one word (the shema's shortcut) instead of the list of all metadata you want to read.

How to add a custom schema as JSON file

Note that you have the possibility to create your own schemata and to stock them in the desired folder. Thus, schemeta created in a project can be used in an other one !

! Note : the name of a personal schema must ends with "-schema.json". Example of a valid name : cosmos-schema.json.

Example of a valid schema as JSON file

Description & rules of the structure

Respect the following rules in order to create a valid schema as JSON file. Note that if a JSON file is not valid, the schema object will be created but it will not be usable.

Types of metadata

The default type of a metadata is an instance of the class MetaTypeAny. This last one accepts any type of value. By specifying the type of metadata, the new value of a metadata will be checked before to be added. If this last one is not accepted, it's not added.

The list of types of metadata

How to create his own type of metadata

How to use schemata with taskers

Note that for every following examples, the above schema example called "cosmos" will be used.

How to read

You can read all schema's metadata by passing its shortcut or the schema as object. You can also read only some metadata of the schema in same ways.

Let's see an example :

How to write

You can add or edit metatdata without knowing namespace and metadata tag. Indeed, the system of schemata allows to use the shortcut of schemata's metadata like following :

How to delete

As the method to read, you can remove all schema's metadata by passing its shortcut or the schema as object. You can also remove only some metadata of the schema in same ways.

The SchemataManager

First you need to know that the SchemataManager is a singleton : it means that only one instance of this class can be created. How it works ? The SchemataManager will automotically convert all the JSON file inside the both directory user and default shemata to schema objects. Next these schema objects will be added to the list of schemata of the SchemataManager.

You can get this manager like following :

or directly via the MetadataHelper class :

Get all schemata as objects (default and user)

Get all valid schemata as objects (default and user)

The path of the user's schemata's folder

By default, the user's schemata's folder is called "metasya/Schemata" and it's created at the root of your project. However, you can change it like following :

If the old folder "metasyaSchemata" contains json files as schemata, all these files will be copied inside the new folder. Next, if you want to delete the folder "metasyaSchemata" and it's content, you can do it manually (safe and secure) or you can ask to Metasya to do it automatically. Indeed, you can inform a boolean with the value "true" as parameter which indicates to remove the older folder and it's content after the copy :

You can get the user's schemata's folder for information like this :

Test if a string is a shortcut of schema

You can test if a string is associated to a schema with the function isSchemaShortcut(). This last one return true of false according the shortcut value given as parameter :

Get a schema as object from its shortcut

You can get a schema as object with the function getSchemaFromShortcut() :

Test if a string is a shortcut of metadata

You can test if a string is associated to a metadata with the function isMetadataShortcut(). This last one return true of false according the shortcut value given as parameter. Note that only metadata from valid schemata are tested.

Get a metadata as object from its shortcut

You can get a metadata as object with the function getMetadataFromShortcut(). Note that only metadata from valid schemata are tested.

Check the state of schemata

It can be useful to check the state of schemata in order to be aware of possible errors. In the example below, the first one schema identified by "USER-xmp" isn't valid, contrary to to the second one identified by "cosmos".

The class Metadata

A Metadata object corresponds to a metadata tag. You can create a Metadata according to its tag name, its namespace, its shortcut, it's description and it's type (in this order). Let's see an example :

Note that by default the type of a Metadata will be the type MetaTypeAny and the description of a Metadata is null.

The class Schema

A Schema object is mainly constituted by a shortcut, a description and a list of metadata. The shortcut allows to make a reference to the schema.

Get the list of metadata

Get the list of metadata as targeted metadata

Add and remove metadata to a schema

Obviously you can add and remove a metadata to a schema like following :

Test if a string is a shortcut of metadata of the schema

You can test if a string is associated to a metadata of the schema with the function isMetadataShortcut(). This last one return true of false according the shortcut value given as parameter. Note that the schema must be valid.

Get a metadata as object from its shortcut

You can get a metadata fo the schema as object with the function getMetadataFromShortcut(). Note that the schema must be valid.

The list of defaults schemata

comming soon ...