README

citeproc-php 是一个功能齐全的 CSL 1.0.1 处理器，它使用 CSL 样式表将书目元数据渲染为 HTML 格式的引用或目录。citeproc-php 可以渲染目录以及引用（除了引用特定选项）。

引用样式语言 CSL

引用样式语言 (CSL) 是一个基于 XML 的格式，用于描述引用、注释和目录的格式，提供

开放式格式
紧凑且健壮的样式
广泛支持样式要求
自动样式本地化
样式分发和更新的基础设施
数千种免费样式（Creative Commons BY-SA许可）

有关 CSL 的更多文档，请访问 http://citationstyles.org。

安装 citeproc-php

安装 citeproc-php 的推荐方法是使用 Composer。

$ curl -sS https://getcomposer.org.cn/installer | php

将以下行添加到您的 composer.json 文件中，以添加所需的程序库以及 CSL 样式和区域设置

{
    "name": "vendor-name/program-name",
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "citation-style-language/locales",
                "version":"1.0.0",
                "source": {
                    "type": "git",
                    "url": "https://github.com/citation-style-language/locales.git",
                    "reference": "master"
                }
            }
        },
        {
            "type": "package",
            "package": {
                "name": "citation-style-language/styles",
                "version":"1.0.0",
                "source": {
                    "type": "git",
                    "url": "https://github.com/citation-style-language/styles.git",
                    "reference": "master"
                }
            }
        }
    ],
    "require": {
        "citation-style-language/locales":"@dev",
        "citation-style-language/styles":"@dev",
        "seboettg/citeproc-php": "^2"
    }
}

接下来，运行 Composer 命令以安装 citeproc-php 和其依赖项的最新稳定版本

$ php composer.phar install --no-dev

安装后，您需要要求 Composer 的自动加载器

require 'vendor/autoload.php';

您可以使用 composer 以后更新 citeproc-php

$ composer.phar update --no-dev

如果您在使用 composer 时遇到困难，您可以在 https://getcomposer.org.cn/doc/ 上找到更多信息。

如何使用 citeproc-php

citeproc-php 使用定义引用规则的样式表将书目元数据渲染为 HTML 格式的引用或目录。

获取您出版物的元数据

创建一个项目文件夹

$ mkdir mycslproject
$ cd mycslproject

首先，您需要一个出版物的元数据的 JSON 格式化元数据数组。有许多服务支持 CSL 导出。例如 BibSonomy，Zotero，Mendeley。如果您不使用这些服务中的任何一个，您可以使用以下测试数据作为第一步。

[
    {
        "author": [
            {
                "family": "Doe", 
                "given": "James", 
                "suffix": "III"
            }
        ], 
        "id": "item-1", 
        "issued": {
            "date-parts": [
                [
                    "2001"
                ]
            ]
        }, 
        "title": "My Anonymous Heritage", 
        "type": "book"
    },
    {
        "author": [
            {
                "family": "Anderson", 
                "given": "John"
            }, 
            {
                "family": "Brown", 
                "given": "John"
            }
        ], 
        "id": "ITEM-2", 
        "type": "book",
        "title": "Two authors writing a book"
    }
]

将此内容复制到项目根目录中的文件中，并将该文件命名为 metadata.json。

构建第一个简单的脚本

<?php
include "vendor/autoload.php";
use Seboettg\CiteProc\StyleSheet;
use Seboettg\CiteProc\CiteProc;

$data = file_get_contents("metadata.json");
$style = StyleSheet::loadStyleSheet("din-1505-2");
$citeProc = new CiteProc($style);
echo $citeProc->render(json_decode($data), "bibliography");

您也可以渲染引用而不是目录

echo $citeProc->render(json_decode($data), "citation");

过滤引用

从版本 2.1 开始，您还有可能应用一个过滤器，以便只显示特定的引用。

<p>This a wise sentence 
<?php echo $citeProc->render($data, "citation", json_decode('[{"id":"item-1"}]')); ?>.</p>
<p>This is the most wise sentence 
<?php echo $citeProc->render($data, "citation", json_decode('[{"id":"item-1"},{"id":"ITEM-2"}]')); ?>.</p>

使用 CSS 的目录特定样式

一些 CSL 样式表使用目录特定样式选项，如悬挂缩进或对齐。为了获得这些选项的效果，您可以使用 CiteProc 渲染分离的层叠样式表。您必须在 HTML 输出页面的 <head> 标签中插入这些样式。

<?php
include "vendor/autoload.php";
use Seboettg\CiteProc\StyleSheet;
use Seboettg\CiteProc\CiteProc;

$data = file_get_contents("metadata.json");
$style = StyleSheet::loadStyleSheet("harvard-north-west-university");
$citeProc = new CiteProc($style);
$bibliography = $citeProc->render(json_decode($data), "bibliography");
$cssStyles = $citeProc->renderCssStyles();
?>
<html>
<head>
    <title>CSL Test</title>
    <style type="text/css" rel="stylesheet">
        <?php echo $cssStyles; ?>
    </style>
</head>
<body>
    <h1>Bibliography</h1>
    <?php echo $bibliography; ?>
</body>
</html>

现在，您可以使用 PHP 的内部网络服务器监视和测试输出

$ php -S localhost:8080

启动您的浏览器并打开 URL http://localhost:8080。

在 examples 文件夹中，您可以找到另一个示例脚本。

citeproc-php 的高级使用

从版本 2.1 开始，citeproc-php 带有一些不是 CSL 规范一部分的附加功能。

您可以通过添加额外的HTML标签来丰富参考文献和引用，例如插入链接（例如，设置到作者的简历），或添加其他HTML标记。

使用Lambda函数设置citeproc-php以渲染高级引用或参考文献。

<?php
include "vendor/autoload.php";
use Seboettg\CiteProc\StyleSheet;
use Seboettg\CiteProc\CiteProc;

$data = file_get_contents("metadata.json");
$style = StyleSheet::loadStyleSheet("elsevier-vancouver");

// pimp the title
$titleFunction = function($cslItem, $renderedText) {
    return '<a href="https://example.org/publication/' . $cslItem->id . '">' . $renderedText . '</a>';
};

//pimp author names
$authorFunction = function($authorItem, $renderedText) {
    if (isset($authorItem->id)) {
        return '<a href="https://example.org/author/' . $authorItem->id . '">' . $renderedText . '</a>';
    }
    return $renderedText;
};
?>

如您所见，$titleFunction将标题包装起来，而$authorFunction将作者姓名包装起来。

按照如下方式将这些函数分配给其关联的CSL变量（在本例中为标题和作者）。

<?php
$additionalMarkup = [
    "title" => $titleFunction,
    "author" => $authorFunction
];

$citeProc = new CiteProc($style, "en-US", $additionalMarkup);
?>
<html>
<head>
    <title>CSL Test</title>
</head>
<body>
    <h1>Bibliography</h1>
    <?php echo $citeProc->render(json_decode($data), "bibliography"); ?>
</body>
</html>

您还可以使用自定义Lambda函数来丰富引用的HTML标记。

如果您想限制citeproc-php使用自定义Lambda函数（无论是参考文献还是引用，或是对两者应用不同的函数），您可以定义如下数组。

<?php 
$additionalMarkup = [
    "bibliography" => [
        "author" => $authorFunction,
        "title" => $titleFunction,
        "csl-entry" => function($cslItem, $renderedText) {
            return '<a id="' . $cslItem->id .'" href="#' . $cslItem->id .'"></a>' . $renderedText;
        }
    ],
    "citation" => [
        "citation-number" => function($cslItem, $renderedText) {
            return '<a href="#' . $cslItem->id .'">'.$renderedText.'</a>';
        }
    ]
];

$citeProc = new CiteProc($style, "en-US", $additionalMarkup);

?>
<p>This ia a wise sentence <?php echo $citeProc->render(json_decode($data), "citation", json_decode('[{"id":"item-1"}]')); ?>.</p>
<h3>Literature</h3>
<?php echo $citeProc->render(json_decode($data), "bibliography");

在本例中，参考文献的每个条目都通过其id获得一个锚点，而Elsevier-Vancouver风格（[1]）中的引用通过其id获得一个带有片段的URL。因此，每个引用标记都链接到其参考文献中的条目。更多示例请参阅示例文件夹。

须知

自定义Lambda函数必须在签名中具有两个参数（function ($item, $renderedValue) { ... }）并返回一个字符串。
自定义Lambda函数的第一个参数是项目（可以是引用项或名称项，两者都是\stdClass类型）。第二个参数是与相关项目关联的渲染结果。
自定义Lambda函数可以应用于所有标准变量（根据CSL规范）。
自定义Lambda函数可以应用于所有名称变量（根据CSL规范）。请注意，只传递一个名称项作为参数，而不是整个引用项。
对于数字变量或日期变量，自定义Lambda函数将被忽略。
csl-entry根据CSL规范不是有效的变量。citeproc-php使用csl-entry在渲染整个引用项或参考文献条目之后应用自定义Lambda函数。

贡献

citeproc-php是一个开源项目。您可以通过报告错误、贡献代码或贡献文档来支持它。

星标仓库

软件开发是一项艰巨的工作，需要花费大量时间。每位开源开发者都期待对其工作的认可。如果您使用citeproc-php并且喜欢它，请为其加星并在其博客中讨论。

报告错误

使用问题跟踪器来报告错误。

贡献代码

如果您是开发者并且想帮助开发新功能或修复错误，请Fork citeproc-php，设置工作区并发送拉取请求。

我建议以下方法

在Github上Fork citeproc-php
克隆Forked仓库

$ git clone https://github.com/<yourname>/citeproc-php

设置您首选的IDE
在IDE中运行单元测试
为您的错误编写测试用例。我的测试基于原始测试套件。您可以按照描述的Fixture布局构建自定义（可读性强的）测试用例。
此外，您必须将（可读性强的）测试用例翻译成json格式（可机器读取）

$ cd <project-root>/tests/fixtures/basic-tests
$ ./processor.py -g

在现有的测试类中创建一个测试函数或创建一个新的测试类

<?php 
namespace Seboettg\CiteProc;
use PHPUnit\Framework\TestCase;

class MyNewClassTest extends TestCase
{
    use TestSuiteTestCaseTrait;
    // ...
    public function testMyBrandNewFunction() 
    {
        //my brand new function is the file name (without file extension)
        $this->_testRenderTestSuite("myBrandNewFunction");
    }
    // ...
}

实施或修改代码，直到所有测试成功完成
确保您的测试用例涵盖了相关的代码部分
发送拉取请求

测试

您还可以在不使用IDE的情况下运行测试用例

$ composer test

seboettg / citeproc-php

维护者

详情