capdataopera/php-sdk

开发工具，用于公开和检索RDF格式的CapData Opera本体。

维护者

详细信息

gitlab.com/capdataopera/capdataopera-php-sdk

源代码

问题

论坛

安装: 358

依赖项: 0

建议者: 0

安全: 0

星星: 1

分支: 0

0.7.0 2024-05-28 15:20 UTC

Requires

Requires (Dev)

CC-BY-SA-4.0 d287474b05bcfa4fc00818ebeecb0c3addca75d8

sdkRDFontologyOperacapdata

This package is auto-updated.

Last update: 2024-08-28 13:49:08 UTC

README

Pipeline badge Coverage badge License: CC BY-SA 4.0

在CapData Opéra项目框架下开发 - 法国2030年，由法国歌剧联盟发起。该项目由法国2030年的“增强型现场演出体验”项目支持，由法国存款银行操作。更多信息请访问https://www.rof.fr/rof/capdata-opera.aspx。

PHP SDK允许

  • [x] 以RDF格式暴露按照CapData Opéra本体模型化的结构化数据。
  • [ ] 通过SPARQL语言查询这些数据，并从查询结果中填充PHP对象。

目录

文档

SDK使用强类型和PHP-doc进行开发，其中包含类型和泛型信息。我们建议您设置您的IDE以利用这些信息。这将为您提供输入辅助和实时文档。

有用链接

使用方法

项目中的安装

composer require capdataopera/php-sdk

使用示例

以下是一个使用SDK创建RDF图并将其序列化为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']);

支持的类

对于媒体，建议使用子类 Image、Sound 和 Text。

更详细的信息

数据不可变性

每个类的原始数据由一个 Value Object 表示，以验证数据并使其不可变。

基数

使用 Value Object 来表示数据，可以管理一个类属性的基数，通过构建一个代表值集合的 Value Object 而不是一个单一值。

所有 ValueObject 都可以接受一个基本类型或基本类型的数组。方法 __toString 和 __serialize 允许以强制方式获取基本类型的值或基本类型值的数组。

Value Object 负责验证输入数据。

<?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']

与schema.org的对应关系

SDK 可以自动构建 CapData Opéra 和 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> ;

类属性

继承自 OntologyClass 的类的所有属性都是 ValueObject。因此，setter 接受以下内容：

  • 一个基本类型的值
  • 基本类型值的数组
  • 代表一个值的 ValueObject
  • 代表一个值集合的 ValueObject

getter 总是返回一个 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')

对象之间的关系

对象之间的关系由 RelationObject 表示，它们是表示集合的 ValueObject，在构建时进行类型检查以验证输入数据。

<?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));

外部关系

所有接受 RelationObject 的方法也接受通过 ExternalThing 类提供的资源外部 URI。

<?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'));

以下是用于外部关系的可用类：

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

使用这些类创建的对象不需要添加到图中进行序列化。

对象序列化

对象构建后，您必须将每个对象添加到 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);

图记录添加的每个对象的 URI 以避免重复，并验证每个关系是否已正确记录在图中。

构建图后，序列化器将使用 EasyRdf 库将每个对象转换为 RDF，并根据本体 https://ontologie.capdataculture.fr/v1/、https://schema.org/ 等. 这一阶段由 Converter 和 LiteralConverter 执行，它们负责通过责任链模式进行转换。

CapDataOpera\PhpSdk\Serializer\Serializer 类默认配置了一个 Converter 和 LiteralConverter 列表。但您可以为 RDF 添加属性或类来配置自己的 Converter 和 LiteralConverter。

<?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(),
    ]
);

最后，一旦图转换为 RDF，您就可以将其序列化为您选择的格式。这是 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']);

添加自定义属性

您可以使用 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']);

选择序列化的本体

serialize 方法接受一个字符串数组来选择用于序列化的本体。可用的本体如下：

默认情况下，序列化器仅使用 capdata 本体。

<?php
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'/*, ['capdata'] */); 
// les 2 ontologies sont utilisées
echo $serializer->serialize($graph, 'turtle', ['capdata', 'schema']);
// 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', ['schema']);

如何为项目做出贡献

请阅读 CONTRIBUTING.md 了解更多关于我们的代码准则以及提交 pull-request 或 issue 的流程。

致谢

由法国 2030 年代号支持的项目 CapData Opéra - France 2030 完成，由法国歌剧协会负责。该活动由法国国家在 2030 年「现场表演增强体验」计划下支持，由法国存款银行运营。更多信息请访问 https://www.rof.fr/rof/capdata-opera.aspx。

SDK PHP 的设计与开发：Rezo Zero - https://www.rezo-zero.com/