README

The Public Knowledge Project has taken over stewardship of citeproc-php from @seboettg. Thanks for your many years of hard work, Sebastian! Follow the discussion leading to this change at #200.

citeproc-php

citeproc-php is a full-featured CSL 1.0.1 processor that renders bibliographic metadata into HTML-formatted citations or bibliographies using CSL stylesheets. It supports both bibliographies and citations (except for Citation-specific Options).

Citation Style Language CSL

The Citation Style Language (CSL) is an XML-based format to describe the formatting of citations, notes and bibliographies, offering:

• An open format
• Compact and robust styles
• Extensive support for style requirements
• Automatic style localization
• Infrastructure for style distribution and updating
• Thousands of freely available styles (Creative Commons BY-SA licensed)

For additional documentation of CSL visit http://citationstyles.org.

Installing citeproc-php

The recommended way to install citeproc-php is through Composer.

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

Add the following lines to your composer.json file in order to add required program libraries as well as CSL styles and locales:

{
    "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"
    }
}

Next, run the Composer command to install the latest stable version of citeproc-php and its dependencies:

$ php composer.phar install --no-dev

After installing, you need to require Composer's autoloader:

require 'vendor/autoload.php';

You can then later update citeproc-php using composer:

$ composer.phar update --no-dev

If you have trouble using composer you will find further information on https://getcomposer.org/doc/.

How to use citeproc-php

citeproc-php renders bibliographic metadata into HTML-formatted citations or bibliographies using a stylesheet that defines the citation rules.

Get the metadata of your publications

Create a project folder:

$ mkdir mycslproject
$ cd mycslproject

First, you need a JSON-formatted array of publication metadata. Many services support CSL exports, such as BibSonomy, Zotero, and Mendeley. If you don't use any of these services, you can use the following test data as a starting point.

[
    {
        "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"
    }
]

Copy this into a file in your project root and name that file metadata.json.

Build a first simple script

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

You can also render citations instead of bibliographies:

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

Filter Citations

Since version 2.1, you can also apply a filter to render only specific citations.

<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>

Bibliography-specific styles using CSS

Some CSL stylesheets use bibliography-specific style options such as hanging indents or alignments. To apply these options, you can render the corresponding CSS using CiteProc. Insert these styles within the <head> tag of your HTML output page.

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

Now, you can watch and test the output using PHP's internal web server:

$ php -S localhost:8080

Start your Browser and open the URL http://localhost:8080.

You can find additional example scripts in the examples folder.

Advanced usage of citeproc-php

Since version 2.1, citeproc-php comes with additional features that are not part of the CSL specification.

You can enrich bibliographies and citations with additional HTML tags to inject links (i.e. to set a link to an author's CV), or to add other html markup.

Use Lambda Functions to setup citeproc-php in order to render advanced citations or bibliographies

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

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

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

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

As you can see, $titleFunction wraps the title and $authorFunction wraps the author's name in a link.

Assign these functions to its associated CSL variable (in this case title and author) as follows.

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

You can also use custom Lambda Functions in order to enrich citations with additional HTML markup.

If you want to restrict citeproc-php to use a custom Lambda Function either for bibliographies or citations, or you want to apply different functions for both, you can define the array as follows:

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

In this example, each bibliography entry receives an anchor based on its id, and the citation (in Elsevier-Vancouver style [1]) gets a URL with a fragment identifier. This way, every citation links to its corresponding entry in the bibliography. You can find further examples in the examples folder.

Good to know

• A custom lambda function must have two parameters (function ($item, $renderedValue) { ... }) in its signature and must return a string.
• The first parameter is the item (either a citation item or a name item, both of type \stdClass). The second parameter is the rendered result of the associated item.
• Custom lambda functions can be applied to all Standard Variables (according to the CSL specification).
• Custom lambda functions can be applied to all Name Variables (according to the CSL specification). Note that only a single name item is passed as a parameter instead of the full citation item.
• Custom lambda functions for Number Variables or Date Variables are ignored.
• csl-entry is not a valid variable according to the CSL specification. citeproc-php uses csl-entry as a hook to apply a custom lambda function after an entire citation item or bibliography entry has been rendered.

Contribution

citeproc-php is an Open Source project. You can support it by reporting bugs, contributing code or contributing documentation.

Star the Repo

Developing software is a demanding task that requires a lot of time. Every open-source developer appreciates recognition for their work. If you use citeproc-php and find it helpful, consider starring the repository and sharing it on your blog.

Reporting a Bug

Use the Issue Tracker in order to report a bug.

Contribute Code

Are you a developer who wants to help develop new features or fix bugs? Fork citeproc-php, set up a workspace, and send a pull request.

Here is the recommended workflow:

• Fork citeproc-php on Github
• Clone the forked repo

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

• Setup your preferred IDE
• Run the UnitTests within your IDE
• Write a test case for your issue. The tests are based on the original test-suite. You can build custom human-readable test cases following the Fixture layout.
• Then translate the human-readable test cases into JSON format (machine-readable)

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

• Create a test function within an existing test class or create a new test class:

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

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

• Implement or adapt your code until all tests pass successfully
• Make sure that your test case covers relevant code parts
• Send a pull request

Testing

You can also run test cases without IDE:

$ composer test

Projects using citeproc-php

• Citation Style Language plugin for Open Journal Systems 3
• Islandora Scholar
• Grav Bibliography Plugin
• Bibcite Wordpress Plugin
• DKAN Science Metadata
• Stud.IP
• bibliography Plugin for DokuWiki
• ldbase_citations (Plugin for LDbase)
• Citations - (Drupal module)