README

COAR通知（CNs）管理器既可以作为接收通知的收件箱，也可以发送通知。CNs是具有类似链接数据通知结构的活动流2.0通知（见附录中的COAR通知示例）。

CNs没有最终规范，但通知模式和示例场景提供了良好的指导。

它使用PHP 7.4编写，使用Guzzle（封装cURL）和JSON。它使用Doctrine在数据库中持久化，Monolog进行日志记录，ramsey/uuid生成v4 UUIDs，并使用Guzzle发送通知（请参阅composer.json以获取版本号）。

此通知管理器最初设计用于支持涉及三种不同类型活动的场景 # 1、2、3、4 和 9：宣布审查、请求审查和宣布认可。后来扩展到包括：确认和接受、确认和拒绝、宣布摄取、宣布关系、请求认可、请求摄取和撤回报价，总共10种不同的通知模式。

按字母顺序排列的10种支持的模式

安装和设置

最简单的安装方法是使用Composer。

$ composer require cottagelabs/coar-notifications

要设置收件箱，您需要一个MySQL/MariaDB数据库。

通过在项目的根目录中创建文件cli-config.php来创建数据库模式，并运行：$ php vendor/bin/doctrine orm:schema-tool:create以创建数据库模式（从容器外部：docker exec coar_notify_php php vendor/bin/doctrine orm:schema-tool:create），Dockerfile将运行Apache 2 Web服务器。

用法

此模块不涉及LDN建议中的发现部分。这取决于Web应用程序的开发者。

可以将一些配置参数传递给COARNotificationManager

在以下示例中，我们将假设我们已创建了COARNotificationManager实例，如下所示：

$conn = array('host'     => '127.0.0.1',
    'driver'   => 'pdo_mysql',
    'user'     => 'root',
    'password' => 'my-secret-pw',
    'dbname'   => 'coar_notifications',
);

$logger = new Logger('NotifyCOARLogger');
$handler = new RotatingFileHandler(__DIR__ . '/log/NotifyCOARLogger.log', 0, Logger::DEBUG, true, 0664);
$formatter = new LineFormatter(null, null, false, true);
$handler->setFormatter($formatter);
$logger->pushHandler($handler);

// Initialising a COARNotificationManager
$coarNotificationManager = new COARNotificationManager($conn, $logger);

假设已创建了一个名为 notifications 的表（参见上方的安装和设置）。该表将包含所有通知，使用一个名为 direction 的单表继承映射鉴别列，以区分 INBOUND 和 OUTBOUND 通知。

COAR 通知管理器不了解请求，这些请求必须由 Web 应用程序的逻辑处理。管理器提供适当的响应

选项

根据 LDN 建议，发送者可以使用 OPTIONS 请求来确定服务器接受的 RDF 内容类型。此方法将设置响应头 Allow 和 Accept-Post。

确定是否已发出 OPTIONS 请求的责任在于 Web 应用程序。

示例

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    $coarNotificationManager->setOptionsResponseHeaders();
}

POST

此方法尝试解码 JSON 有效负载，并根据其成功与否，将响应一个 HTTP 状态码

400 如果 JSON 格式错误
422 如果通知无效或在持久化通知时发生错误
201 如果通知成功接收并持久化
415 如果使用了不支持的媒体类型

示例

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $coarNotificationManager->getPostResponse();
}

GET

根据 LDN 建议，此方法列出收件箱的内容。COAR 通知管理器没有提供分页方法。然而，Doctrine 支持分页。

示例

if ($_SERVER['REQUEST_METHOD'] === 'GET') {
    $response = $coarNotificationManager->getGetResponse();

    // Optionally manipulate $response
    // ...

    echo $response;
}

示例输出

{
  "@context": "http://www.w3.org/ns/ldp",
  "@id": "https://overlay-journal.com",
  "contains": [
    "https://overlay-journal.com/inbox/b5df022a-fc6c-4679-8246-d288f5690b17"
  ]
}

发送

为了发送通知，您首先需要初始化一个 $coarNotificationInbox 对象。这是因为出站通知将保存到上述描述的同一数据库表中。

在创建 OutboundNotification 对象之前，必要的部分将独立创建

// This represents the entity sending the notification
$actor = new COARNotificationActor("actorId", "actorName", "Person");

// The journal that the actor wishes to publish in
$object = new COARNotificationObject("https://overlay-journal.com/reviews/000001/00001",
"https://doi.org/10.3214/987654", array("Document", "sorg:Review"));

// The url of the context object, see below
$url = new COARNotificationURL("https://research-organisation.org/repository/preprint/201203/421/content.pdf",
"application/pdf", array("Article", "sorg:ScholarlyArticle"));

// The actual content that is to be actioned on
$context = new COARNotificationContext("https://research-organisation.org/repository/preprint/201203/421/",
"https://doi.org/10.5555/12345680", array("sorg:AboutPage"), $url);

// This represents the target system the notification is to be delivered to
$target = new COARNotificationTarget("https://research-organisation.org/repository",
"https://:81/post");

// Create the notification
$notification = $coarNotificationManager->createOutboundNotification($actor, $object, $context, $target);

将这些 POPO 组合在一起，几乎构成了一个完整的 COAR 通知，唯一剩下的是调用以下之一

$coarNotificationManager->announceEndorsement($notification);

或

$coarNotificationManager->announceReview($notification);

或

$notification->requestReview($notification);

注意，所有模式都具有可选的 $inReplyTo 参数，以指示该步骤是对早期步骤的响应。

开发

包括 docker-compose.yml 以便于实验和开发。它将 Apache HTTPD2 容器与 MySQL 容器连接起来。只需运行

$ docker-compose up

在 https://:8060/，有一个交互式表单，您可以用来半手动创建 COAR 通知。请注意，三个字段；type、url type 和 object type 预期逗号分隔的值，这些值将被拆分为字符串数组。

在 https://:8060/inbox.php，将按 ID 和时间戳列出发送或接收的通知。

单元测试

此项目使用 PHPUnit 进行单元测试。要运行测试，请使用 docker compose up -d 启动 docker 容器，然后运行 docker exec coar_notify_php ./vendor/bin/phpunit tests。

许可

在此，任何人获得本软件及其相关文档文件（以下简称“软件”）的副本，均被授予在此软件上不受限制地处理的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本，并允许向获得软件的人提供本软件，前提是必须遵守以下条件

资金来源

本项目获得法国国家开放科学基金的资助法国国家开放科学基金

Projet financé avec le soutien du Fonds National pour la Science Ouverte

附录

COAR通知JSON负载示例

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://purl.org/coar/notify"
  ],
  "actor": {
    "id": "https://overlay-journal.com",
    "name": "Overlay Journal",
    "type": "Service"
  },
  "context": {
    "id": "https://research-organisation.org/repository/preprint/201203/421/",
    "ietf:cite-as": "https://doi.org/10.5555/12345680",
    "type": "sorg:AboutPage",
    "url": {
      "id": "https://research-organisation.org/repository/preprint/201203/421/content.pdf",
      "media-type": "application/pdf",
      "type": [
        "Article",
        "sorg:ScholarlyArticle"
      ]
    }
  },
  "id": "urn:uuid:94ecae35-dcfd-4182-8550-22c7164fe23f",
  "object": {
    "id": "https://overlay-journal.com/reviews/000001/00001",
    "ietf:cite-as": "https://doi.org/10.3214/987654",
    "type": [
      "Document",
      "sorg:Review"
    ]
  },
  "origin": {
    "id": "https://overlay-journal.com/system",
    "inbox": "https://overlay-journal.com/system/inbox/",
    "type": "Service"
  },
  "target": {
    "id": "https://research-organisation.org/repository",
    "inbox": "https://research-organisation.org/repository/inbox/",
    "type": "Service"
  },
  "type": [
    "Announce",
    "coar-notify:ReviewAction"
  ]
}

cottagelabs / coar-notifications

维护者

详细信息

README

安装和设置

用法

选项

POST

GET

发送

开发

单元测试

许可

资金来源

附录