{"id":16065094,"url":"https://github.com/hedii/zotero-api","last_synced_at":"2025-03-17T16:32:46.542Z","repository":{"id":62515351,"uuid":"64474905","full_name":"hedii/zotero-api","owner":"hedii","description":"A php wrapper for zotero web api.","archived":false,"fork":false,"pushed_at":"2024-03-25T14:24:18.000Z","size":17,"stargazers_count":14,"open_issues_count":3,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-16T05:48:00.276Z","etag":null,"topics":["php","php-wrapper","rest-api","zotero","zotero-api"],"latest_commit_sha":null,"homepage":null,"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/hedii.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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-07-29T11:13:39.000Z","updated_at":"2024-09-11T12:16:29.000Z","dependencies_parsed_at":"2024-06-21T05:54:23.272Z","dependency_job_id":null,"html_url":"https://github.com/hedii/zotero-api","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedii%2Fzotero-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedii%2Fzotero-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedii%2Fzotero-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedii%2Fzotero-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hedii","download_url":"https://codeload.github.com/hedii/zotero-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221697199,"owners_count":16865560,"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":["php","php-wrapper","rest-api","zotero","zotero-api"],"created_at":"2024-10-09T05:11:05.300Z","updated_at":"2024-10-27T15:19:14.465Z","avatar_url":"https://github.com/hedii.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/hedii/zotero-api.svg?branch=master)](https://travis-ci.org/hedii/zotero-api)\n\n# Zotero Api\n\nA php wrapper for zotero web api.\n\n## Table of contents\n\n- [Table of contents](#table-of-contents)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Instantiation](#instantiation)\n  - [User and group libraries](#user-and-group-libraries)\n  - [Items](#items)\n    - [Multiple items](#multiple-items)\n    - [Single item](#single-item)\n    - [Top level items](#top-level-items)\n    - [Items in the trash](#items-in-the-trash)\n    - [Child items](#child-items)\n    - [Item tags](#item-tags)\n  - [Collections](#collections)\n    - [Multiple collections](#multiple-collections)\n    - [Single collection](#single-collection)\n    - [Items in a collection](#items-in-a-collection)\n    - [Top level items in a collection](#top-level-items-in-a-collection)\n    - [Collection tags](#collection-tags)\n    - [Sub collections](#sub-collections)\n  - [Versions](#versions)\n  - [Tags](#tags)\n  - [Searches](#searches)\n    - [Multiple searches](#multiple-searches)\n    - [Single search](#single-search)\n  - [Key](#key)\n  - [Groups](#groups)\n  - [Sorting and pagination](#sorting-and-pagination)\n    - [Sorting](#sorting)\n    - [Direction](#direction)\n    - [Limit](#limit)\n    - [Start](#start)\n  - [Request timeout](#request-timeout)\n  - [Connection timeout](#connection-timeout)\n  - [**Sending a request and getting a response**](#sending-a-request-and-getting-a-response)\n    - [Sending the request](#sending-the-request)\n    - [Response body](#response-body)\n    - [Response json](#response-json)\n    - [Response headers](#response-headers)\n    - [Response status code](#response-status-code)\n    - [Response reason phrase](#response-reason-phrase)\n  - [Raw query](#raw-query)\n- [Examples](#examples)\n- [Testing](#testing)\n- [License](#license)\n\n## Installation\n\nInstall via [composer](https://getcomposer.org/doc/00-intro.md)\n```sh\ncomposer require hedii/zotero-api\n```\n\n## Usage\n\n### Instantiation\n\nZoteroApi has to be instantiated with an api key. You can generate a zotero api key [here](https://www.zotero.org/settings/keys) if you have an account on zotero.org.\n\n```php\n\u003c?php\n// require composer autoloader\nrequire '/path/to/vendor/autoload.php';\n\n// instantiate\n$api = new Hedii\\ZoteroApi\\ZoteroApi('your_zotero_api_key_here');\n```\n\n### User and group libraries\n\nEvery call to zotero web api has to be made on a user or a group library (except for `key($apiKey)` method).\n\nThis is reflected on this package by the fact that you always have to call the method `user($userId)` or the method `group($groupId)` at the beginning of each call.\n\n```php\n$api-\u003euser($userId)\n    // continue chaining methods...\n\n$api-\u003egroup($groupId)\n    // continue chaining methods...\n```\n\n### Items\n\n#### Multiple items\n\nTo access all items in a library, call the `items()` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems()\n    // continue chaining methods...\n```\n\n#### Single item\n\nTo access a specific item in a library, call `items($itemKey)` method with the item key as a parameter.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems($itemKey)\n    // continue chaining methods...\n```\n\n#### Top level items\n\nTo access only top level items in a library, call `top()` method just after the `items()` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems()\n    -\u003etop()\n    // continue chaining methods...\n```\n\n#### Items in the trash\n\nTo access items that have been put in the trash, call `trash()` method just after `items()` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems()\n    -\u003etrash()\n    // continue chaining methods...\n```\n\n#### Child items\n\nTo access an item's child items, call `children()` method just after `items($itemKey)` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems($itemKey)\n    -\u003echildren()\n    // continue chaining methods...\n```\n\n#### Item tags\n\nTo access all tags associated with a specific item, call `tags()` method just after `items($itemKey)` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems($itemKey)\n    -\u003etags()\n    // continue chaining methods...\n```\n\n### Collections\n\n#### Multiple collections\n\nTo access all collections in a library, call the `collections()` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003ecollections()\n    // continue chaining methods...\n```\n\n#### Single collection\n\nTo access a specific collection in a library, call `collections($collectionKey)` method with the collection key as a parameter.\n\n```php\n$api-\u003euser($userId)\n    -\u003ecollections($collectionKey)\n    // continue chaining methods...\n```\n\n#### Items in a collection\n\nTo access all items in a collection, call `items()` method after calling a specific collection.\n\n```php\n$api-\u003euser($userId)\n    -\u003ecollections($collectionKey)\n    -\u003eitems()\n    // continue chaining methods...\n```\n\n#### Top level items in a collection\n\nTo access only top items in a collection, call `top()` method after calling items in a specific collection.\n\n```php\n$api-\u003euser($userId)\n    -\u003ecollections($collectionKey)\n    -\u003eitems()\n    -\u003etop()\n    // continue chaining methods...\n```\n\n#### Collection tags\n\nTo access all tags associated with a specific collection, call `tags()` method just after `collections($collectionKey)` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003ecollections($collectionKey)\n    -\u003etags()\n    // continue chaining methods...\n```\n\n#### Sub collections\n\nTo access sub collections within a specific collection, call `subCollection()` method just after `collections($collectionKey)` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003ecollections($collectionKey)\n    -\u003esubCollections()\n    // continue chaining methods...\n```\n\n### Versions\n\nTo get all resources (either collections or items) versions, call `versions()` method after `items()` or `collections()` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems()\n    -\u003eversions()\n    // continue chaining methods...\n```\n\n### Tags\n\n#### All tags\n\nTo access all tags in a library, call `tags()` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003etags()\n    // continue chaining methods...\n```\n\n#### Matching tags\n\nTo access tags matching a specific name in a library, call `tags($tagName)` method with `$tagName` a string as a parameter.\n\n```php\n$api-\u003euser($userId)\n    -\u003etags($tagName)\n    // continue chaining methods...\n```\n\n### Searches\n\n#### Multiple searches\n\nTo access all saved searches in a library, call `searches()` method.\n\n```php\n$api-\u003euser($userId)\n    -\u003esearches()\n    // continue chaining methods...\n```\n\n#### Single search\n\nTo access a specific saved search in a library, call `searches($searchKey)` method with the search key as a parameter.\n\n```php\n$api-\u003euser($userId)\n    -\u003esearches($searchKey)\n    // continue chaining methods...\n```\n\n### Key\n\nTo access the privilege information of a given api key, call `key($apiKey)` method on the `ZoteroApi` instance.\n\n```php\n$response = $api-\u003ekey($apiKey)\n    -\u003esend();\n    \n$keyPrivileges = $response-\u003egetBody();\n```\n\n### Groups\n\nTo access all groups the current API key has access to, call `groups()` method just after `user($userId)` method.\n\n```php\n$response = $api-\u003euser($userId)\n    -\u003egroups()\n    -\u003esend()\n    \n$groups = $response-\u003egetBody();\n```\n\n### Sorting and pagination\n\nSorting and pagination methods can be called after calling a resource method.\n\n#### Sorting\n\nThe `sortBy($value)` method set by what type of value the response will by sorted.\n\nThe `$value` parameter has to be one of :\n  - dateAdded\n  - dateModified\n  - title\n  - creator\n  - type\n  - date\n  - publisher\n  - publicationTitle\n  - journalAbbreviation\n  - language\n  - accessDate\n  - libraryCatalog\n  - callNumber\n  - rights\n  - addedBy\n  - numItems\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems()\n    -\u003esortBy('publicationTitle')\n    // continue chaining methods...\n```\n\n#### Direction\n\nThe `direction($value)` method set the sorting direction of the field specified by the `sortBy($value)` method.\n\nThe `$value` parameter has to be one of :\n  - asc\n  - desc\n  \n```php\n$api-\u003euser($userId)\n    -\u003eitems()\n    -\u003esortBy('language')\n    -\u003edirection('desc')\n    // continue chaining methods...\n```\n\n#### Limit\n\nThe `limit($value)` method set the maximum number of results to return with a single request.\n\nThe `$value` parameter has to be an integer between 1 and 100. The default number of result provided by zotero web api is 50.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems()\n    -\u003elimit(70)\n    // continue chaining methods...\n```\n\n#### Start\n\nThe `start($value)` method determines the index of the first result.\n\nThe `$value` parameter has to be an integer. The default starting index is 0.\n\nCombine with the limit parameter to select a slice of the available results.\n\n```php\n$api-\u003euser($userId)\n    -\u003eitems()\n    -\u003estart(60)\n    -\u003elimit(70)\n    // continue chaining methods...\n```\n\n### Request timeout\n\nRequest timeout can be set using the `setTimeout($timeout)` method, with `$timeout` an integer in milliseconds as a parameter.\n\nDefault request timeout is 0.\n\n```php\n$api-\u003esetTimeout(3000)\n    // continue chaining methods...\n```\n\nYou can get the current request timeout value using the `getTimeout()` method.\n\n```php\n$timeout = $api-\u003egetTimeout();\n```\n\n### Connection timeout\n\nConnection timeout can be set using the `setConnectionTimeout($connectionTimeout)` method, with `$connectionTimeout` an integer in milliseconds as a parameter.\n\nDefault connection timeout is 0.\n\n```php\n$api-\u003esetConnectionTimeout(3000)\n    // continue chaining methods...\n```\n\nYou can get the current connection timeout value using the `getConnectionTimeout()` method.\n\n```php\n$connectionTimeout = $api-\u003egetConnectionTimeout();\n```\n\n### Sending a request and getting a response\n\n#### Sending the request\n\nTo send a request after chaining available methods, call the `send()` method.\n\n```php\n$response = $api-\u003euser($userId)\n    -\u003eitems()\n    -\u003esend();\n```\n\n#### Response body\n\nTo access the response body as an array, call the `getBody()` method on the response.\n\n```php\n$response = $api-\u003euser($userId)\n    -\u003eitems()\n    -\u003esend();\n    \n$body = $response-\u003egetBody(); // array\n```\n\n#### Response json\n\nTo access the response body as a json string, call the `getJson()` method on the response.\n\n```php\n$response = $api-\u003euser($userId)\n    -\u003eitems()\n    -\u003esend();\n    \n$json = $response-\u003egetJson(); // string\n```\n\n#### Response headers\n\nTo access the response headers as an array, call the `getHeaders()` method on the response.\n\n```php\n$response = $api-\u003euser($userId)\n    -\u003eitems()\n    -\u003esend();\n    \n$headers = $response-\u003egetHeaders(); // array\n```\n\n#### Response status code\n\nTo access the response status code, call the `getStatusCode()` method on the response.\n\n```php\n$response = $api-\u003euser($userId)\n    -\u003eitems()\n    -\u003esend();\n    \n$statusCode = $response-\u003egetStatusCode(); // int\n```\n\n#### Response reason phrase\n\nTo access the response reason phrase, call the `getReasonPhrase()` method on the response.\n\n```php\n$response = $api-\u003euser($userId)\n    -\u003eitems()\n    -\u003esend();\n    \n$reasonPhrase = $response-\u003egetReasonPhrase(); // string\n```\n\n### Raw query\n\nTo build the request url yourself, call the `raw($url)` method, with `$url` a string as a parameter.\n\n```php\n$response = $api-\u003eraw('https://api.zotero.org/users/12345/items?limit=30\u0026start=10')\n    -\u003esend();\n    \n$items = $response-\u003egetBody();\n```\n\n## Examples\n\n```php\n\u003c?php\n\n// require composer autoloader\nrequire __DIR__ . '/vendor/autoload.php';\n\nuse Hedii\\ZoteroApi\\ZoteroApi;\n\n// instantiate zotero api\n$api = new ZoteroApi('xxxxxxxxxxxxxxxxxxx');\n\n\n// get the item 'ABCDEF' in the user 12345 library\n$response = $api-\u003euser(12345)\n    -\u003eitems('ABCDEF')\n    -\u003esend();\n    \n$item = $response-\u003egetBody();\n\n\n// get 12 first top items in the group 12345 library and\n// sort them by descendant modification date.\n$response = $api-\u003egroup(12345)\n    -\u003eitems()\n    -\u003etop()\n    -\u003elimit(12)\n    -\u003esortBy('dateModified')\n    -\u003edirection('desc')\n    -\u003esend();\n\n$items = $response-\u003egetBody();\n\n\n// search for tags matching 'a name' in the user 12345 library\n$response = $api-\u003euser(12345)\n    -\u003etags('a name')\n    -\u003esend();\n    \n$tags = $response-\u003egetBody();\n  \n    \n// get all user 12345 collections\n$response = $api-\u003euser(12345)\n    -\u003ecollections()\n    -\u003esend();\n\n$collections = $response-\u003egetBody();\n    \n    \n// get top items within the collection 'ABCDEF' in the group 98765 library\n$response = $api-\u003egroup(98765)\n    -\u003ecollections('ABCDEF')\n    -\u003eitems()\n    -\u003etop()\n    -\u003esend();\n    \n$topItems = $response-\u003egetBody();\n\n// get an array of all items keys with their versions\n$response = $api-\u003euser(12345)\n    -\u003eitems()\n    -\u003eversions();\n    \n$itemKeysWithVersions = $response-\u003egetBody();\n```\n\n## Testing\n\n```\ncomposer test\n```\n\n## License\n\nhedii/zotero-api is released under the MIT Licence. See the bundled [LICENSE](https://github.com/hedii/zotero-api/blob/master/LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhedii%2Fzotero-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhedii%2Fzotero-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhedii%2Fzotero-api/lists"}