capdataopera/php-sdk

Development kit to expose and fetch CapData Opera ontology in RDF format.

Package info

gitlab.com/capdataopera/capdataopera-php-sdk

Issues

Forum

pkg:composer/capdataopera/php-sdk

Statistics

Installs: 1 124

Dependents: 0

Suggesters: 0

Stars: 1

0.8.6 2026-06-26 13:05 UTC

Requires

Requires (Dev)

Suggests

None

Provides

None

Conflicts

None

Replaces

None

CC-BY-SA-4.0 f36ba9dac3ab4cbdd2cb9b75ef8090ccead386b0

sdkRDFontologyOperacapdata

This package is auto-updated.

Last update: 2026-06-26 11:05:51 UTC

README

👁 Pipeline badge
👁 Coverage badge
👁 License: CC BY-SA 4.0

DĂ©veloppements rĂ©alisĂ©s dans le cadre du projet CapData OpĂ©ra - France 2030, portĂ© par la RĂ©union des OpĂ©ras de France. \ OpĂ©ration soutenue par l'État dans le cadre du dispositif « ExpĂ©rience augmentĂ©e du spectacle vivant » de France 2030, opĂ©rĂ© par la Caisse des DĂ©pĂŽts. \ Information sur https://www.rof.fr/rof/capdata-opera.aspx.

Le SDK PHP permet :

  • [x] d'exposer des donnĂ©es structurĂ©es modĂ©lisĂ©es selon l'ontologie CapData OpĂ©ra au format RDF.
  • [ ] d'interroger ces donnĂ©es via le langage SPARQL et hydrater des objets PHP Ă  partir des rĂ©sultats de ces requĂȘtes.

Sommaire

Documentation

Le SDK est développé avec un typage fort et des PHP-doc renseignant les types et des génériques. Nous vous conseillons de paramétrer votre IDE pour qu'il tire parti de ces informations. Cela vous permettra d'avoir une aide à la saisie et une documentation en temps réel.

Liens utiles

Utilisation

Installation dans un projet

composer require capdataopera/php-sdk

Exemple d'utilisation

Voici un exemple simpliste d'utilisation du SDK pour créer un graphe RDF et le sérialiser au format Turtle.

<?php
use CapDataOpera\PhpSdk\Graph\Graph;
use CapDataOpera\PhpSdk\Model\Collectivite;
use CapDataOpera\PhpSdk\Model\Isni;
use CapDataOpera\PhpSdk\Serializer\Serializer;

$serializer = new Serializer();
$graph = new Graph();

$ownOrg = new Collectivite('https://mon-opera.fr/organization/1');
$ownOrg->setNom('Mon opéra de test')
 ->setFacebook('https://facebook.com/mon-opera')
 ->setSiteWeb('https://mon-opera.fr')
 ->setCatalogageSourceAgence($ownOrg)
 ->setDateCreationRessource(new \DateTimeImmutable('2022-01-30T00:00:00+00:00'))
 ->setDateModificationRessource(new \DateTimeImmutable('2024-01-30T00:00:00+00:00'))
 ->setIsni(new Isni('https://isni.org/isni/0000000122982840'));
$graph->add($ownOrg);

/*
 * On exporte le graph en RDF avec les ontologies capdata et schema.org pour obtenir un fichier Turtle
 */
echo $serializer->serialize($graph, 'turtle', ['capdata', 'schema']);

Classes supportées

Pour les médias, il est recommandé d'utiliser les sous-classes Image, Sound et Text.

Plus en détails

Immutabilité des données

Les données primitives de chaque classe sont représentées par un Value Object pour valider les données et les rendre immutables.

Cardinalité

En utilisant les Value Object pour représenter les données, on peut gérer la cardinalité des propriétés d'une classe, en construisant un Value Object qui représente une collection de valeurs plutÎt qu'une valeur unique.

Tous les ValueObject peuvent accepter une primitive ou bien un tableau de primitives. Les méthodes __toString et __serialize permettent de récupérer la valeur primitive ou le tableau de valeurs primitives de maniÚre forcée.

Le Value Object est responsable de la validation des données en entrée.

<?php
$simpleString = new StringObject('foo');
$multipleString = new StringObject(['foo', 'bar']);

echo $simpleString; // 'foo'
echo $multipleString; // 'foo, bar' (concaténation des valeurs avec une virgule)

var_dump($simpleString->__serialize()); // ['foo']
var_dump($multipleString->__serialize()); // ['foo', 'bar']

Correspondance avec schema.org

Le SDK permet de construire automatiquement certaines correspondances entre les ontologies CapData Opéra et schema.org.

<https://mon-opera.fr/production/1>
 a schema:Thing, rof:Production, schema:CreativeWork ;
 rof:aPourInterpretation <https://mon-opera.fr/interpretation/1>, <https://mon-opera.fr/interpretation/2> ;

Valeurs multilingues

Les noms, descriptions, contenus éditoriaux et libellés de Referentiel peuvent porter des littéraux balisés par langue via le LocalizedStringObject. Lorsqu'elles sont renseignées, les valeurs localisées sont sérialisées avec leur balise de langue ("Opéra de Lyon"@fr) ; sinon, l'API non localisée se comporte comme avant.

<?php
$lieu->setLocalizedName(['fr' => 'Opéra de Lyon', 'en' => 'Lyon Opera']);
$lieu->setLocalizedDescription([
 'fr' => 'Le Grand Théùtre
',
 'en' => 'The Grand Theatre
',
]);

// L'API non localisée reste disponible :
$lieu->setName('Opéra de Lyon');

Page web publique

Toute classe Thing (via HasUrl) accepte une URL de page web publique, ou une page par langue. Elle est Ă©mise en schema:url (sortie schema uniquement) :

<?php
$production->setUrl('https://www.opera-lyon.com/fr/spectacle/
');
$production->setUrl([
 'https://www.opera-lyon.com/fr/spectacle/
',
 'https://www.opera-lyon.com/en/show/
',
]);

// Une page par langue → un nƓud schema:WebPage par langue (schema:inLanguage)
$lieu->setLocalizedUrl([
 'fr' => 'https://www.opera-lyon.com/fr/',
 'en' => 'https://www.opera-lyon.com/en/',
]);

À ne pas confondre avec HasSocials::setSiteWeb() : siteWeb est le site propre de la ressource (ex. le site personnel d'un·e artiste), tandis que setUrl() dĂ©signe la page qui la prĂ©sente (ex. la page de l'opĂ©ra dĂ©diĂ©e Ă  cet·te artiste). Les deux sont Ă©mises en schema:url.

Saison comme schema:EventSeries

Saison reste un skos:Concept / rof:Saison et est désormais aussi typée schema:EventSeries, avec des dates de début et de fin. Chaque représentation (Evenement) référence la saison via schema:superEvent (Evenement::setAPourSaison(...)).

<?php
$saison->setDateDebut('2025-09-01');
$saison->setDateFin('2026-07-15'); // → schema:startDate / schema:endDate

Pour le détail des évolutions de la v0.8 (DataTourisme, couverture schema.org étendue, multilingue
), voir UPGRADE_v0.8.md.

Propriétés de classes

Toutes les propriĂ©tĂ©s des classes hĂ©ritant OntologyClass sont des ValueObject. Ainsi, les setter acceptent soit :

  • une valeur primitive
  • un tableau de valeurs primitives
  • un ValueObject reprĂ©sentant une valeur
  • un ValueObject reprĂ©sentant une collection de valeurs

Le getter retourne toujours un ValueObject.

<?php
use CapDataOpera\PhpSdk\ValueObject\StringObject;
use CapDataOpera\PhpSdk\Model\Personne;

$personne = new Personne('https://mon-opera.fr/person/1');

// Appels possibles pour ajouter une propriété :
// - Le setter wrap la valeur dans un ValueObject
$personne->setNom('foo');
// - On peut aussi passer un tableau de valeurs
$personne->setNom(['foo', 'bar']);
// - On passe directement un ValueObject
$personne->setNom(new StringObject('foo'));
// - On passe directement un ValueObject avec le tableau de valeurs
$personne->setNom(new StringObject(['foo', 'bar']));


// Le getter retourne toujours un ValueObject
$personne->getNom(); // StringObject('foo')

Relations entre objets

Les relations entre objets sont représentées par des RelationObject qui sont des ValueObject qui représentent une collection. Les RelationObject sont typés dÚs leur construction pour valider les données en entrée.

<?php
use CapDataOpera\PhpSdk\ValueObject\RelationObject;
use CapDataOpera\PhpSdk\Model\Fonction;
use CapDataOpera\PhpSdk\Model\Personne;

$fonction = new Fonction('https://mon-opera.fr/fonction/1');
$fonction2 = new Fonction('https://mon-opera.fr/fonction/2');
$personne = new Personne('https://mon-opera.fr/person/1');

// Appels possibles pour ajouter une relation :
// - Le setter wrap l'objet dans un RelationObject en définissant le type
$personne->setAPourFonction($fonction);
// - On peut aussi passer un tableau de valeurs
$personne->setAPourFonction([$fonction, $fonction2]);
// - On passe directement un RelationObject
$personne->setAPourFonction(new RelationObject($fonction, Fonction::class));
// - On passe directement un RelationObject avec le tableau de valeurs
$personne->setAPourFonction(new RelationObject([$fonction, $fonction2], Fonction::class));

Relations externes

Toutes les méthodes acceptant des RelationObject acceptent aussi des URI de ressources externes via la class ExternalThing.

<?php
use CapDataOpera\PhpSdk\Model\Personne;
use CapDataOpera\PhpSdk\Model\ExternalThing;

$personne = new Personne('https://mon-opera.fr/person/1');
$personne->setAPourFonction(new ExternalThing('http://capdataculture.fr/graph/FONCTION/230'));

Voici les classes disponibles pour les relations externes :

  • CapDataOpera\PhpSdk\Model\ExternalThing
  • CapDataOpera\PhpSdk\Model\Isni
  • CapDataOpera\PhpSdk\Model\ArkBnf

Les objets crĂ©Ă©s avec ces classes n'ont pas besoin d'ĂȘtre ajoutĂ©s au graph pour ĂȘtre sĂ©rialisĂ©s.

Serialization des objets

Une fois les objets construits, vous devrez ajouter chaque objet Ă  un Graph.

$graph = new Graph();

$address = new AdressePostale('https://mon-opera.fr/adresse/1');
$address
 ->setAdressePostale('1 place de la Comédie')
 ->setCodePostal('69001')
 ->setCommune('Lyon')
;

$ownOrg = new Collectivite('https://mon-opera.fr/organization/1');
$ownOrg->setNom('Mon opéra de test')
 ->setFacebook('https://facebook.com/mon-opera')
 ->setSiteWeb('https://mon-opera.fr')
 ->setAdresse($address)
 ->setCatalogageSourceAgence($ownOrg)
 ->setDateCreationRessource(new \DateTimeImmutable('2022-01-30T00:00:00+00:00'))
 ->setDateModificationRessource(new \DateTimeImmutable('2024-01-30T00:00:00+00:00'))
 ->setIsni(new Isni('https://isni.org/isni/0000000122982840'));
 
$graph->add($address);
$graph->add($ownOrg);

Le graph enregistre chaque URI d'objet ajouté pour éviter les doublons, mais aussi pour valider si chaque relation vers une ressource interne est bien enregistrée dans le graph.

Une fois le graph construit, le serializer va convertir chaque objet en RDF via la librairie EasyRdf et créer les triplets selon les ontologies https://ontologie.capdataculture.fr/v1/, https://schema.org/, etc. Cette étape est opérée par les Converter et les LiteralConverter qui sont responsables de la conversion via le pattern Chain of Responsibility.

La classe CapDataOpera\PhpSdk\Serializer\Serializer est, par défaut, configurée avec une liste de Converter et de LiteralConverter. Mais vous pouvez configurer vos propres Converter et LiteralConverter pour ajouter des propriétés ou des classes à votre RDF.

<?php
use CapDataOpera\PhpSdk\Serializer\Serializer;

// Serializer avec les converters par défaut
$serializer = new Serializer();

// Serializer des converters personnalisés
$serializer = new Serializer(
 [
 new MyCustomObjectConverter(),
 ],
 [
 new MyCustomLiteralConverter(),
 ]
);

Enfin, une fois le graph convertit en RDF, vous pouvez le sérialiser dans le format de votre choix. Il s'agit des formats supportés par EasyRdf : https://www.easyrdf.org/docs/api/EasyRdf/Serialiser.html#method_serialise

<?php
// La méthode serialize effectue la conversion, la validation puis la sérialisation
echo $serializer->serialize($graph, 'turtle', ['capdata']);

Ajouter des propriétés personnalisées

Vous avez la possibilitĂ© d'ajouter des propriĂ©tĂ©s personnalisĂ©es n'importe oĂč dans votre Graph en utilisant la mĂ©thode addResource :

<?php
use CapDataOpera\PhpSdk\Graph\Graph;
use CapDataOpera\PhpSdk\Model\Collectivite;
use CapDataOpera\PhpSdk\Model\Isni;
use CapDataOpera\PhpSdk\Serializer\Serializer;

$serializer = new Serializer();
$graph = new Graph();

$ownOrg = new Collectivite('https://mon-opera.fr/organization/1');
$ownOrg->setNom('Mon opéra de test')
 ->setFacebook('https://facebook.com/mon-opera')
 ->setSiteWeb('https://mon-opera.fr')
 ->setCatalogageSourceAgence($ownOrg)
 ->setDateCreationRessource(new \DateTimeImmutable('2022-01-30T00:00:00+00:00'))
 ->setDateModificationRessource(new \DateTimeImmutable('2024-01-30T00:00:00+00:00'))
 ->setIsni(new Isni('https://isni.org/isni/0000000122982840'));
$graph->add($ownOrg);

/**
 * Ajout d'une propriété personnalisée sur l'objet Collectivite
 */
$graph->addResource(
 'https://mon-opera.fr/organization/1', 
 'https://schema.org/startDate', 
 new Literal('2016-04-21T20:00', null, 'xsd:dateTime')
);

echo $serializer->serialize($graph, 'turtle', ['capdata']);

Choisir les ontologies pour la sérialisation

La mĂ©thode serialize accepte un tableau de chaĂźnes de caractĂšres pour choisir les ontologies Ă  utiliser pour la sĂ©rialisation. Les ontologies disponibles sont :

Par défaut, le serializer utilise l'ontologie capdata uniquement.

Vous pouvez passer les clés sous forme de chaßnes ('capdata', 'schema', 'datatourisme') ou bien utiliser les constantes de la classe CapDataOpera\PhpSdk\Ontology, qui sont à privilégier.

<?php
use CapDataOpera\PhpSdk\Ontology;
use CapDataOpera\PhpSdk\Serializer\Serializer;

$serializer = new Serializer();
$graph = new Graph();
// ...

// Par défaut, exporte uniquement les classes et propriétés de l'ontologie capdata au format Turtle
echo $serializer->serialize($graph, 'turtle'/*, [Ontology::CAPDATA] */);
// Plusieurs ontologies sont utilisées
echo $serializer->serialize($graph, 'turtle', [Ontology::CAPDATA, Ontology::SCHEMA]);
// Toutes les ontologies : capdata + schema + datatourisme
echo $serializer->serialize($graph, 'turtle', Ontology::all());
// Exporte uniquement les classes et propriétés de l'ontologie schema.org au format LD-JSON pour le web sémantique
// L'export au format LD-JSON nécessite la librairie ml/json-ld: composer require ml/json-ld
echo $serializer->serialize($graph, 'jsonld', [Ontology::SCHEMA]);

Vous pouvez aussi définir les ontologies utilisées par défaut, soit à la construction du Serializer, soit via setDefaultOntologies (par exemple pour basculer en mode schema-first) :

<?php
use CapDataOpera\PhpSdk\Ontology;
use CapDataOpera\PhpSdk\Serializer\Serializer;

// Le 3e argument définit les ontologies par défaut
$serializer = new Serializer([], [], [Ontology::SCHEMA]);

// ... ou plus tard
$serializer->setDefaultOntologies([Ontology::CAPDATA, Ontology::SCHEMA]);

Toutes les classes CapData n'ont pas d'Ă©quivalent DataTourisme : les modĂšles propres au spectacle vivant (Production, Oeuvre, Saison, Participation) ne sont volontairement pas Ă©mis dans la sortie datatourisme.

Comment contribuer au projet

Veuillez lire CONTRIBUTING.md pour plus de détails sur notre code de conduite, et le processus pour soumettre une pull-request ou une issue.

Crédits

DĂ©veloppements rĂ©alisĂ©s dans le cadre du projet CapData OpĂ©ra - France 2030, portĂ© par la RĂ©union des OpĂ©ras de France. OpĂ©ration soutenue par l'État dans le cadre du dispositif « ExpĂ©rience augmentĂ©e du spectacle vivant » de France 2030, opĂ©rĂ© par la Caisse des DĂ©pĂŽts. Information sur https://www.rof.fr/rof/capdata-opera.aspx.

Conception et développement du SDK PHP : Rezo Zero - https://www.rezo-zero.com/