{"id":21670774,"url":"https://github.com/seboettg/citeproc-php","last_synced_at":"2025-04-04T21:09:10.373Z","repository":{"id":8931468,"uuid":"60277642","full_name":"seboettg/citeproc-php","owner":"seboettg","description":"Full-featured CSL 1.0.1 processor for PHP","archived":false,"fork":false,"pushed_at":"2024-07-06T00:00:08.000Z","size":3170,"stargazers_count":76,"open_issues_count":42,"forks_count":39,"subscribers_count":9,"default_branch":"develop","last_synced_at":"2025-03-28T20:07:54.806Z","etag":null,"topics":["bibliographies","citation","citations","citeproc-php","csl","csl-processor"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seboettg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-02T15:57:50.000Z","updated_at":"2024-10-26T15:00:23.000Z","dependencies_parsed_at":"2024-11-25T15:47:35.571Z","dependency_job_id":null,"html_url":"https://github.com/seboettg/citeproc-php","commit_stats":{"total_commits":489,"total_committers":24,"mean_commits":20.375,"dds":0.640081799591002,"last_synced_commit":"116b470c80940baabc04aec962d0ad5e4360c6fc"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboettg%2Fciteproc-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboettg%2Fciteproc-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboettg%2Fciteproc-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboettg%2Fciteproc-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seboettg","download_url":"https://codeload.github.com/seboettg/citeproc-php/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249529,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bibliographies","citation","citations","citeproc-php","csl","csl-processor"],"created_at":"2024-11-25T12:35:17.798Z","updated_at":"2025-04-04T21:09:10.354Z","avatar_url":"https://github.com/seboettg.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# citeproc-php #\n[![Latest Stable Version](https://poser.pugx.org/seboettg/citeproc-php/v/stable)](https://packagist.org/packages/seboettg/citeproc-php) \n[![Total Downloads](https://poser.pugx.org/seboettg/citeproc-php/downloads)](https://packagist.org/packages/seboettg/citeproc-php/stats) \n[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT)\n[![Build Status](https://scrutinizer-ci.com/g/seboettg/citeproc-php/badges/build.png?b=master)](https://scrutinizer-ci.com/g/seboettg/citeproc-php/build-status/master)\n[![Code Coverage](https://scrutinizer-ci.com/g/seboettg/citeproc-php/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/seboettg/citeproc-php/code-structure/master/code-coverage/src/)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/seboettg/citeproc-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/seboettg/citeproc-php/?branch=master)\n[![Code Intelligence Status](https://scrutinizer-ci.com/g/seboettg/citeproc-php/badges/code-intelligence.svg?b=master)](https://scrutinizer-ci.com/code-intelligence)\n![PHP](https://img.shields.io/badge/PHP-7.3-green.svg?style=flat)\n![PHP](https://img.shields.io/badge/PHP-7.4-green.svg?style=flat)\n![PHP](https://img.shields.io/badge/PHP-8.0-green.svg?style=flat)\n![PHP](https://img.shields.io/badge/PHP-8.1-green.svg?style=flat)\n\nciteproc-php is a full-featured CSL 1.0.1 processor that renders bibliographic metadata into html formatted citations or bibliographies using CSL stylesheets. citeproc-php renders bibliographies as well as citations (except of [Citation-specific Options](http://docs.citationstyles.org/en/stable/specification.html#citation-specific-options)).\n\n## Citation Style Language CSL ##\n\nThe Citation Style Language (CSL) is an XML-based format to describe the formatting of citations, notes and bibliographies, offering:\n\n* An open format\n* Compact and robust styles\n* Extensive support for style requirements\n* Automatic style localization\n* Infrastructure for style distribution and updating\n* Thousands of freely available styles (Creative Commons BY-SA licensed)\n\nFor additional documentation of CSL visit [http://citationstyles.org](http://citationstyles.org).\n\n## Installing citeproc-php ##\n\nThe recommended way to install citeproc-php is through\n[Composer](https://getcomposer.org).\n\n```bash\n$ curl -sS https://getcomposer.org/installer | php\n```\nAdd the following lines to your `composer.json` file in order to add required program libraries as well as CSL styles and locales:\n\n```json\n{\n    \"name\": \"vendor-name/program-name\",\n    \"repositories\": [\n        {\n            \"type\": \"package\",\n            \"package\": {\n                \"name\": \"citation-style-language/locales\",\n                \"version\":\"1.0.0\",\n                \"source\": {\n                    \"type\": \"git\",\n                    \"url\": \"https://github.com/citation-style-language/locales.git\",\n                    \"reference\": \"master\"\n                }\n            }\n        },\n        {\n            \"type\": \"package\",\n            \"package\": {\n                \"name\": \"citation-style-language/styles\",\n                \"version\":\"1.0.0\",\n                \"source\": {\n                    \"type\": \"git\",\n                    \"url\": \"https://github.com/citation-style-language/styles.git\",\n                    \"reference\": \"master\"\n                }\n            }\n        }\n    ],\n    \"require\": {\n        \"citation-style-language/locales\":\"@dev\",\n        \"citation-style-language/styles\":\"@dev\",\n        \"seboettg/citeproc-php\": \"^2\"\n    }\n}\n```\n\nNext, run the Composer command to install the latest stable version of citeproc-php and its dependencies:\n\n```bash\n$ php composer.phar install --no-dev\n```\n\nAfter installing, you need to require Composer's autoloader:\n\n```php\nrequire 'vendor/autoload.php';\n```\n\nYou can then later update citeproc-php using composer:\n\n ```bash\n$ composer.phar update --no-dev\n ```\n\nIf you have trouble using composer you will find further information on [https://getcomposer.org/doc/](https://getcomposer.org/doc/).\n\n## How to use citeproc-php ##\n\nciteproc-php renders bibliographical metadata into html formatted citations or bibliographies using a stylesheet which defines the \ncitation rules. \n\n\n### Get the metadata of your publications ###\n\nCreate a project folder:\n\n```bash\n$ mkdir mycslproject\n$ cd mycslproject\n```\n\nFirst, you need json formatted metadata array of publication's metadata. There are a lot of services that supports CSL exports. For instance [BibSonomy](https://www.bibsonomy.org), [Zotero](https://www.zotero.org/), [Mendeley](https://www.mendeley.com/). \nIf you don't use any of these services, you can use the following test data for a first step.\n\n```javascript\n[\n    {\n        \"author\": [\n            {\n                \"family\": \"Doe\", \n                \"given\": \"James\", \n                \"suffix\": \"III\"\n            }\n        ], \n        \"id\": \"item-1\", \n        \"issued\": {\n            \"date-parts\": [\n                [\n                    \"2001\"\n                ]\n            ]\n        }, \n        \"title\": \"My Anonymous Heritage\", \n        \"type\": \"book\"\n    },\n    {\n        \"author\": [\n            {\n                \"family\": \"Anderson\", \n                \"given\": \"John\"\n            }, \n            {\n                \"family\": \"Brown\", \n                \"given\": \"John\"\n            }\n        ], \n        \"id\": \"ITEM-2\", \n        \"type\": \"book\",\n        \"title\": \"Two authors writing a book\"\n    }\n]\n```\nCopy this into a file in your project root and name that file `metadata.json`.\n\n### Build a first simple script ###\n\n```php\n\u003c?php\ninclude \"vendor/autoload.php\";\nuse Seboettg\\CiteProc\\StyleSheet;\nuse Seboettg\\CiteProc\\CiteProc;\n\n$data = file_get_contents(\"metadata.json\");\n$style = StyleSheet::loadStyleSheet(\"din-1505-2\");\n$citeProc = new CiteProc($style);\necho $citeProc-\u003erender(json_decode($data), \"bibliography\");\n```\n\nYou can also render citations instead of bibliographies:\n\n```php\necho $citeProc-\u003erender(json_decode($data), \"citation\");\n```\n\n### Filter Citations ###\n\nSince version 2.1 you have also the possibility to apply a filter so that just specific citations appear.\n\n```php\n\u003cp\u003eThis a wise sentence \n\u003c?php echo $citeProc-\u003erender($data, \"citation\", json_decode('[{\"id\":\"item-1\"}]')); ?\u003e.\u003c/p\u003e\n\u003cp\u003eThis is the most wise sentence \n\u003c?php echo $citeProc-\u003erender($data, \"citation\", json_decode('[{\"id\":\"item-1\"},{\"id\":\"ITEM-2\"}]')); ?\u003e.\u003c/p\u003e\n```\n\n### Bibliography-specific styles using CSS ###\n\nSome CSL stylesheets use bibliography-specific style options like hanging indents or alignments. To get an effect of these options you can render separated Cascading Stylesheets using CiteProc. \nYou have to insert these styles within the `\u003chead\u003e` tag of your html output page.\n\n```php\n\u003c?php\ninclude \"vendor/autoload.php\";\nuse Seboettg\\CiteProc\\StyleSheet;\nuse Seboettg\\CiteProc\\CiteProc;\n\n$data = file_get_contents(\"metadata.json\");\n$style = StyleSheet::loadStyleSheet(\"harvard-north-west-university\");\n$citeProc = new CiteProc($style);\n$bibliography = $citeProc-\u003erender(json_decode($data), \"bibliography\");\n$cssStyles = $citeProc-\u003erenderCssStyles();\n?\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003ctitle\u003eCSL Test\u003c/title\u003e\n    \u003cstyle type=\"text/css\" rel=\"stylesheet\"\u003e\n        \u003c?php echo $cssStyles; ?\u003e\n    \u003c/style\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eBibliography\u003c/h1\u003e\n    \u003c?php echo $bibliography; ?\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nNow, you can watch and test the output using PHP's internal web server:\n\n```bash\n$ php -S localhost:8080\n```\n\nStart your Browser and open the URL `http://localhost:8080`.\n\nUnder `examples` folder you will find another example script.\n\n\n## Advanced usage of citeproc-php ##\n\nSince version 2.1, citeproc-php comes with additional features that are not a part of the CSL specifications.\n\nYou 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.\n\n### Use Lambda Functions to setup citeproc-php in order to render advanced citations or bibliographies ###\n\n```php\n\u003c?php\ninclude \"vendor/autoload.php\";\nuse Seboettg\\CiteProc\\StyleSheet;\nuse Seboettg\\CiteProc\\CiteProc;\n\n$data = file_get_contents(\"metadata.json\");\n$style = StyleSheet::loadStyleSheet(\"elsevier-vancouver\");\n\n// pimp the title\n$titleFunction = function($cslItem, $renderedText) {\n    return '\u003ca href=\"https://example.org/publication/' . $cslItem-\u003eid . '\"\u003e' . $renderedText . '\u003c/a\u003e';\n};\n\n//pimp author names\n$authorFunction = function($authorItem, $renderedText) {\n    if (isset($authorItem-\u003eid)) {\n        return '\u003ca href=\"https://example.org/author/' . $authorItem-\u003eid . '\"\u003e' . $renderedText . '\u003c/a\u003e';\n    }\n    return $renderedText;\n};\n?\u003e\n```\n\nAs you can see, `$titleFunction` wraps the title and `$authorFunction` wraps author's name in a link.\n\nAssign these functions to its associated CSL variable (in this case title and author) as follows.\n\n```php\n\u003c?php\n$additionalMarkup = [\n    \"title\" =\u003e $titleFunction,\n    \"author\" =\u003e $authorFunction\n];\n\n$citeProc = new CiteProc($style, \"en-US\", $additionalMarkup);\n?\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003ctitle\u003eCSL Test\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eBibliography\u003c/h1\u003e\n    \u003c?php echo $citeProc-\u003erender(json_decode($data), \"bibliography\"); ?\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nYou can also use custom Lambda Functions in order to enrich citations with additional HTML markup.\n\nIf you want to restrict citeproc-php to use a custom Lambda Function either for bibliographies or citations, or you want to apply different \nfunctions for both, you can define the array as follows:\n\n```php\n\u003c?php \n$additionalMarkup = [\n    \"bibliography\" =\u003e [\n        \"author\" =\u003e $authorFunction,\n        \"title\" =\u003e $titleFunction,\n        \"csl-entry\" =\u003e function($cslItem, $renderedText) {\n            return '\u003ca id=\"' . $cslItem-\u003eid .'\" href=\"#' . $cslItem-\u003eid .'\"\u003e\u003c/a\u003e' . $renderedText;\n        }\n    ],\n    \"citation\" =\u003e [\n        \"citation-number\" =\u003e function($cslItem, $renderedText) {\n            return '\u003ca href=\"#' . $cslItem-\u003eid .'\"\u003e'.$renderedText.'\u003c/a\u003e';\n        }\n    ]\n];\n\n$citeProc = new CiteProc($style, \"en-US\", $additionalMarkup);\n\n?\u003e\n\u003cp\u003eThis ia a wise sentence \u003c?php echo $citeProc-\u003erender(json_decode($data), \"citation\", json_decode('[{\"id\":\"item-1\"}]')); ?\u003e.\u003c/p\u003e\n\u003ch3\u003eLiterature\u003c/h3\u003e\n\u003c?php echo $citeProc-\u003erender(json_decode($data), \"bibliography\");\n\n```\nIn this example each entry of the bibliography gets an anchor by its `id` and the citation (in Elsevier-Vancouver style [1]) gets an URL with a fragment by its `id`. Hence, every citation mark gets a link to its entry in the bibliography.\nFurther examples you will find in the example folder.\n\n### Good to know ###\n* A custom Lambda Function must have two parameters (`function ($item, $renderedValue) { ... }`) in their signature and must return a string.\n* The 1st parameter of a custom Lambda Function is the item (either a citation item or a name item. Both of type `\\stdClass`). The 2nd parameter is the rendered result of the associated item.\n* Custom Lambda Functions may be applied on all Standard Variables (according to the [CSL specification](http://docs.citationstyles.org/en/1.0.1/specification.html#standard-variables)).\n* Custom Lambda Functions may be applied on all Name Variables (according to the [CSL specification](http://docs.citationstyles.org/en/1.0.1/specification.html#name-variables)). Be aware, just one name item will passed as parameter instead of the full citation item.\n* Custom Lambda Function for Number Variables or Date Variables will be ignored.\n* ```csl-entry``` is not a valid variable according to the CSL specifications. citeproc-php use ```csl-entry``` to hook in and apply a custom Lambda Function after a whole citation item or bibliography entry is rendered. \n\n## Contribution ##\n\nciteproc-php is an Open Source project. You can support it by reporting bugs, contributing code or contributing documentation.\n\n### Star the Repo ###\nDeveloping software is a hard job and one has to spend a lot of time. Every open-source developer is looking forward \nabout esteem for his work. If you use citeproc-php and if you like it, star it and talk about it in Blogs.\n\n### Reporting a Bug ###\nUse the [Issue Tracker](https://github.com/seboettg/citeproc-php/issues) in order to report a bug.\n\n### Contribute Code ###\nYou are a developer and you like to help developing new features or bug fixes? Fork citeproc-php, setup a workspace and send\na pull request.\n\nI would suggest the following way:\n\n* Fork citeproc-php on Github\n* Clone the forked repo\n```bash\n$ git clone https://github.com/\u003cyourname\u003e/citeproc-php\n``` \n* Setup your preferred IDE\n* Run the UnitTests within your IDE\n* Write a test case for your issue. My tests are based on the original [test-suite](https://github.com/citation-style-language/test-suite). You can build custom (human-readable) test cases following the described [Fixture layout](https://github.com/citation-style-language/test-suite#fixture-layout). \n* Additionally, you have to translate (human-readable) test-cases into json format (machine-readable)\n```bash\n$ cd \u003cproject-root\u003e/tests/fixtures/basic-tests\n$ ./processor.py -g\n```\n* create a test function within an already existing test class or create a new test class:\n```php\n\u003c?php \nnamespace Seboettg\\CiteProc;\nuse PHPUnit\\Framework\\TestCase;\n\nclass MyNewClassTest extends TestCase\n{\n    use TestSuiteTestCaseTrait;\n    // ...\n    public function testMyBrandNewFunction() \n    {\n        //my brand new function is the file name (without file extension)\n        $this-\u003e_testRenderTestSuite(\"myBrandNewFunction\");\n    }\n    // ...\n}\n```\n* Implement or adapt your code as long as all tests finishing successfully\n* Make sure that your test case covers relevant code parts\n* Send a pull request\n\n## Testing ##\n\nYou can also run test cases without IDE:\n\n```bash\n$ composer test\n```\n\n## Known projects that use citeproc-php\n\n* [Citation Style Language plugin for Open Journal Systems 3](https://github.com/pkp/citationStyleLanguage)\n* [Islandora Scholar](https://github.com/Islandora/islandora_scholar)\n* [Grav Bibliography Plugin](https://github.com/OleVik/grav-plugin-bibliography)\n* [Bibcite Wordpress Plugin](https://github.com/ShadyChars/Bibcite)\n* [DKAN Science Metadata](https://github.com/GetDKAN/dkan_sci_metadata)\n* [Stud.IP](https://github.com/studip/studip)\n* [bibliography Plugin for DokuWiki](https://github.com/gyger/dokuwiki-bibliography)\n* [ldbase_citations (Plugin for LDbase)](https://github.com/ldbase/ldbase_citations)\n* [Citations - (Drupal module)](https://github.com/fsulib/citations)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseboettg%2Fciteproc-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseboettg%2Fciteproc-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseboettg%2Fciteproc-php/lists"}