vincentauger / orcid-php-sdk
A modern, framework-agnostic PHP SDK for the ORCID API
Requires
- php: ^8.4.0
- saloonphp/saloon: ^4.5
Requires (Dev)
- laravel/pint: ^1.22.1
- pestphp/pest: ^4.0.0
- phpstan/phpstan: ^2.1.16
- rector/rector: ^2.0.16
- symfony/var-dumper: ^7.2.6
- vlucas/phpdotenv: ^5.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A modern, framework-agnostic PHP SDK for the ORCID API v3.0, built on Saloon.
Before
1.0, a minor release may break the API: see the changelog when upgrading.
Requirements
- PHP 8.4+
Installation
composer require vincentauger/orcid-php-sdk
Usage
use VincentAuger\OrcidSdk\Enums\Environment; use VincentAuger\OrcidSdk\Orcid; use VincentAuger\OrcidSdk\OrcidOAuth; // Member API, bound to the record a 3-legged token was granted on: store the token's // access token, ORCID iD and scopes, and pass them back here $orcid = Orcid::member( accessToken: $accessToken, orcid: '0000-0002-1825-0097', scopes: $scopes, // optional: a missing scope throws MissingScopeException before sending environment: Environment::Sandbox, ); // Member API without a record, e.g. a /read-public client credentials token: reads only, through record($id) $orcid = Orcid::member(accessToken: $readPublicToken); // Public API, ideally with a /read-public client credentials token $orcid = Orcid::public($readPublicToken); // OAuth endpoints (orcid.org) $oauth = new OrcidOAuth($clientId, $clientSecret, Environment::Sandbox);
OAuth
OrcidOAuth wraps ORCID's token endpoints. It never stores tokens: keep the ones it returns wherever your
application keeps secrets, and pass them to Orcid::member().
use VincentAuger\OrcidSdk\Enums\Scope; // 1. send the researcher to ORCID; generating and checking `state` is up to you $url = $oauth->authorizationUrl(Scope::completeAccess(), 'https://example.org/orcid/callback', state: $state); // 2. back on your redirect URI: exchange the code for a 3-legged token $token = $oauth->exchangeCode($_GET['code'], 'https://example.org/orcid/callback'); // store all four $token->accessToken; $token->orcid; // the record the researcher granted access to $token->scopes; // list<Scope>: pass them to Orcid::member(scopes:) to check them before sending $token->refreshToken; $token->expiresIn; // seconds (about 20 years for a 3-legged token) $orcid = Orcid::member(accessToken: $token->accessToken, orcid: $token->orcid, scopes: $token->scopes); // a 2-legged token for this client, e.g. /read-public for the Member API's higher limits (no refresh token) $readPublic = $oauth->clientCredentials([Scope::ReadPublic]); // a new token from a refresh token: same or fewer scopes, optionally revoking the old access token $narrowed = $oauth->refresh($token->refreshToken, scopes: [Scope::ReadLimited], revokeOld: true); // the researcher disconnects: revoke the access token (and its refresh token) $oauth->revoke($token->accessToken); // OpenID Connect: who granted an `openid` token, without a call to the record API $userInfo = $oauth->userInfo($openIdToken); // ->orcid, ->givenName, ->familyName
A bad, revoked or expired token makes record calls throw an OrcidAuthException (401); a token missing the scope a
call needs, an OrcidForbiddenException whose isMissingScope() is true (403, error 9038).
Affiliations
Employments, educations, qualifications, invited positions, distinctions, memberships and services all work the same way:
use VincentAuger\OrcidSdk\Data\Affiliations\AffiliationInput; use VincentAuger\OrcidSdk\Data\Common\FuzzyDate; use VincentAuger\OrcidSdk\Data\Organization\DisambiguatedOrganization; use VincentAuger\OrcidSdk\Data\Organization\Organization; use VincentAuger\OrcidSdk\Data\Organization\OrganizationAddress; use VincentAuger\OrcidSdk\Enums\AffiliationType; $affiliations = Orcid::member(accessToken: $accessToken, orcid: $orcidId)->affiliations(); $input = new AffiliationInput( organization: new Organization( 'Fisheries and Oceans Canada', new OrganizationAddress(city: 'Ottawa', country: 'CA'), DisambiguatedOrganization::ror('https://ror.org/02qa1x782'), ), roleTitle: 'Research Scientist', startDate: FuzzyDate::fromString('2021-01'), ); $putCode = $affiliations->create(AffiliationType::Employment, $input); // store it $affiliations->update(AffiliationType::Employment, $putCode, $input); // replaces the whole item $affiliations->delete(AffiliationType::Employment, $putCode); $employments = $affiliations->list(AffiliationType::Employment); // find the items your client added, e.g. to sync them $ours = array_filter($employments, fn ($employment) => $employment->source?->isClient($clientId));
ORCID applies the researcher's default visibility to new items; clients can't set or change it. Read classes
expose it as a Visibility enum.
Works
A work needs a title, a type and an external identifier with the relationship self (usually its DOI), which
identifies it: ORCID refuses a second work from your client with the same one. WorkInput checks what ORCID
would reject before anything is sent.
ExternalId has a named constructor for the common types: doi(), isbn(), issn(), pmid(), pmc(), arxiv(),
handle(), rrid(), uri(), grantNumber(), proposalId() and sourceWorkId(); new ExternalId($type, ...) takes
any other type ORCID knows. Pass the value bare (10.5555/x) or as its resolver URL (https://doi.org/10.5555/x):
it is sent as written and linked to ORCID's resolver for the type. Any other URL as the value throws; pass another
resolver of the same identifier as url:, and a landing page as the work's own url.
use VincentAuger\OrcidSdk\Data\Common\Contributor; use VincentAuger\OrcidSdk\Data\Common\ExternalId; use VincentAuger\OrcidSdk\Data\Common\FuzzyDate; use VincentAuger\OrcidSdk\Data\Common\Title; use VincentAuger\OrcidSdk\Data\Common\Url; use VincentAuger\OrcidSdk\Data\Works\WorkInput; use VincentAuger\OrcidSdk\Enums\ContributorRole; use VincentAuger\OrcidSdk\Enums\WorkType; use VincentAuger\OrcidSdk\Exceptions\OrcidConflictException; $works = Orcid::member(accessToken: $accessToken, orcid: $orcidId)->works(); $input = new WorkInput( title: new Title('Ocean acidification', subtitle: 'A review'), type: WorkType::JournalArticle, externalIds: [ ExternalId::doi('10.5555/12345678'), // self, linked to https://doi.org/10.5555/12345678 ExternalId::issn('1234-5679'), // part-of by default: the journal's ISSN ], journalTitle: 'Journal of Oceans', publicationDate: FuzzyDate::fromString('2021-03'), url: new Url('https://example.org/articles/12345678'), contributors: [new Contributor('Josiah Carberry', $orcidId, ContributorRole::WritingOriginalDraft)], ); try { $putCode = $works->create($input); // store it } catch (OrcidConflictException $e) { // already there: your client added a work with this DOI before $putCode = $e->existingPutCode() ?? throw $e; } $work = $works->get($putCode); $work->title?->title; $work->type; // WorkType, or null for a type ORCID added later... $work->rawType; // ...whose value is kept here $works->update($putCode, $input); // replaces the whole item $works->delete($putCode); Orcid::public()->record($orcidId)->works()->get($putCode); // reads only
ORCID groups the works from different sources that share a self external identifier (the same DOI from a
publisher and from your system), so list() returns groups. Each summary and group carries ORCID's normalized
identifiers, so 10.1/ABC and https://doi.org/10.1/abc compare equal:
$list = $works->list(); // or Orcid::public()->record($orcidId)->works()->list() foreach ($list->preferred() as $summary) { // one per group, the one ORCID displays echo $summary->title, PHP_EOL; } foreach ($list->summaries() as $summary) { // every summary: yours may not be the preferred one if ($summary->source?->isClient($clientId)) { // one of your works: $summary->putCode } } foreach ($list->groups as $group) { // is this DOI already on the record, from any source? foreach ($group->externalIds as $id) { if ($id->type === 'doi' && $id->normalizedValue === strtolower($doi)) { // $doi: a bare DOI // already there } } }
createMany() and getMany() send up to 100 works or put-codes in one request (Orcid::BULK_LIMIT). Each item
succeeds or fails on its own, so a duplicate doesn't stop the others: the failures are in the result, as
OrcidErrors, not thrown. Above 100 items they throw an InvalidArgumentException before sending anything: one
call is one request, so split the batch yourself (e.g. one queue job per 100).
foreach (array_chunk($inputs, Orcid::BULK_LIMIT) as $chunk) { $result = $works->createMany($chunk); foreach ($result->created as $position => $putCode) { // keyed by position in $chunk // store $putCode for $chunk[$position] } foreach ($result->failed as $position => $error) { if ($error->isDuplicate()) { $putCode = $error->existingPutCode(); // already there, as with create() } else { // $error->errorCode, $error->developerMessage } } } $read = $works->getMany([123, 456]); // or record($orcidId)->works()->getMany(...) $read->works[123]->title?->title; // keyed by put-code $read->failed[456] ?? null; // an unknown put-code (error 9034), not a 404
Fundings
A funding needs a title, a type, the funder (an organization with an address and a disambiguated organization, e.g.
its ROR identifier) and an external identifier, usually the grant number. Unlike a work, the identifier may be
part-of or funded-by only, but a self one is what ORCID uses to group fundings and to refuse duplicates. A
start date is required whenever an end date is given. FundingInput checks this before anything is sent.
use VincentAuger\OrcidSdk\Data\Common\Amount; use VincentAuger\OrcidSdk\Data\Common\ExternalId; use VincentAuger\OrcidSdk\Data\Common\FuzzyDate; use VincentAuger\OrcidSdk\Data\Common\Title; use VincentAuger\OrcidSdk\Data\Fundings\FundingContributor; use VincentAuger\OrcidSdk\Data\Fundings\FundingInput; use VincentAuger\OrcidSdk\Data\Organization\DisambiguatedOrganization; use VincentAuger\OrcidSdk\Data\Organization\Organization; use VincentAuger\OrcidSdk\Data\Organization\OrganizationAddress; use VincentAuger\OrcidSdk\Enums\FundingContributorRole; use VincentAuger\OrcidSdk\Enums\FundingType; $fundings = Orcid::member(accessToken: $accessToken, orcid: $orcidId)->fundings(); $input = new FundingInput( title: new Title('Ocean acidification'), // no subtitle on fundings type: FundingType::Grant, organization: new Organization( 'Natural Sciences and Engineering Research Council', new OrganizationAddress('Ottawa', 'CA'), DisambiguatedOrganization::ror('https://ror.org/01h531d29'), ), externalIds: [ExternalId::grantNumber('RGPIN-2021-1234')], // self by default organizationDefinedType: 'Discovery grant', // the funder's own name for the type amount: new Amount('125000.50', 'CAD'), // a decimal string and an ISO 4217 currency startDate: FuzzyDate::fromString('2021-04'), endDate: FuzzyDate::fromString('2026-03'), contributors: [new FundingContributor('Josiah Carberry', $orcidId, FundingContributorRole::Lead)], ); $putCode = $fundings->create($input); // a duplicate grant number throws OrcidConflictException, as with works $funding = $fundings->get($putCode); $funding->amount?->value; // "125000.5": ORCID normalizes the number $funding->type; // FundingType, or null for a type ORCID added later... $funding->rawType; // ...whose value is kept here $fundings->update($putCode, $input); // replaces the whole item $fundings->delete($putCode); $list = $fundings->list(); // groups, as for works: preferred() and summaries() Orcid::public()->record($orcidId)->fundings()->get($putCode); // reads only
Summaries in a list carry no amount, contributors or description: read the funding by put-code for those.
Peer reviews
A peer review belongs to a review group, usually the journal: issn: and its ISSN. ORCID creates an ISSN group on
first use; it only checks the check digit, not that a journal has that ISSN. Other groups (ringgold:,
orcid-generated:, ...) must already exist in ORCID's group-id registry, or ORCID answers 400 (error 9020).
A peer review also needs the reviewer's role, the review type, a review identifier (your own id for the review), the
completion date and the convening organization (who organized the review, usually the publisher) with an address.
PeerReviewInput checks this, the group id's shape and the ISSN's check digit, before anything is sent.
How open the review is depends on the optional fields you send:
- anonymous: the required fields only, so nothing names the reviewed item
- named subject: add the subject (
subjectExternalId, e.g. the article's DOI,subjectName,subjectContainerName,subjectType,subjectUrl) - published review: give the review its public identifier (e.g. a
doireview identifier) and itsreviewUrl
use VincentAuger\OrcidSdk\Data\Common\ExternalId; use VincentAuger\OrcidSdk\Data\Common\FuzzyDate; use VincentAuger\OrcidSdk\Data\Common\Title; use VincentAuger\OrcidSdk\Data\Organization\Organization; use VincentAuger\OrcidSdk\Data\Organization\OrganizationAddress; use VincentAuger\OrcidSdk\Data\PeerReviews\PeerReviewInput; use VincentAuger\OrcidSdk\Enums\PeerReviewRole; use VincentAuger\OrcidSdk\Enums\PeerReviewSubjectType; use VincentAuger\OrcidSdk\Enums\PeerReviewType; $peerReviews = Orcid::member(accessToken: $accessToken, orcid: $orcidId)->peerReviews(); $input = new PeerReviewInput( role: PeerReviewRole::Reviewer, // or Editor, Member, Chair, Organizer type: PeerReviewType::Review, // Evaluation: after publication reviewIdentifiers: [ExternalId::sourceWorkId('review-1234')], // self by default completionDate: FuzzyDate::fromString('2025-03'), reviewGroupId: 'issn:0706-652X', conveningOrganization: new Organization('Canadian Science Publishing', new OrganizationAddress('Ottawa', 'CA')), // optional: name the reviewed item subjectExternalId: ExternalId::doi('10.1139/cjfas-2024-0001'), subjectType: PeerReviewSubjectType::JournalArticle, subjectName: new Title('Salmon in a warming ocean'), // no subtitle: ORCID drops it ); $putCode = $peerReviews->create($input); // a duplicate review identifier throws OrcidConflictException $peerReview = $peerReviews->get($putCode); $peerReviews->update($putCode, $input); // replaces the whole item $peerReviews->delete($putCode); $list = $peerReviews->list(); // groups, as for works: preferred() and summaries() $list->byReviewGroup(); // the same groups by review group id, e.g. journal by journal Orcid::public()->record($orcidId)->peerReviews()->get($putCode); // reads only
ORCID groups peer reviews by review group, then by self review identifier: the subject's identifier groups nothing.
Summaries in a list carry nothing about the subject: read the peer review by put-code for that.
Research resources
For infrastructure providers (research vessels, facilities, collections, ...): a research resource records that a
researcher was granted access through a proposal, and which resource items it gave access to. ORCID requires the
proposal's title (no subtitle), at least one host and an external identifier, and at least one resource item, each
with a name, a ResearchResourceType, a host and an external identifier. Every host needs an address (a city or a
country) and a disambiguated organization. Any relationship will do for the identifiers; give the proposal a self
one, since ORCID groups research resources by it. The inputs check all this before anything is sent.
use VincentAuger\OrcidSdk\Data\Common\ExternalId; use VincentAuger\OrcidSdk\Data\Common\FuzzyDate; use VincentAuger\OrcidSdk\Data\Common\Title; use VincentAuger\OrcidSdk\Data\Organization\DisambiguatedOrganization; use VincentAuger\OrcidSdk\Data\Organization\Organization; use VincentAuger\OrcidSdk\Data\Organization\OrganizationAddress; use VincentAuger\OrcidSdk\Data\ResearchResources\ResearchResourceInput; use VincentAuger\OrcidSdk\Data\ResearchResources\ResearchResourceItemInput; use VincentAuger\OrcidSdk\Data\ResearchResources\ResearchResourceProposalInput; use VincentAuger\OrcidSdk\Enums\ResearchResourceType; $researchResources = Orcid::member(accessToken: $accessToken, orcid: $orcidId)->researchResources(); $host = new Organization( 'Fisheries and Oceans Canada', new OrganizationAddress('Ottawa', 'CA'), DisambiguatedOrganization::ror('https://ror.org/02qa1x782'), ); $input = new ResearchResourceInput( proposal: new ResearchResourceProposalInput( title: new Title('Ship time on the CCGS Amundsen'), hosts: [$host], // who granted the access externalIds: [ExternalId::proposalId('AMD-2021-07')], // self by default startDate: FuzzyDate::fromString('2021-07'), // an end date needs a start date endDate: FuzzyDate::fromString('2021-08'), ), items: [new ResearchResourceItemInput( name: 'CCGS Amundsen', type: ResearchResourceType::Infrastructures, // or Collections, Equipment, Services hosts: [$host], // who provides the resource externalIds: [ExternalId::sourceWorkId('amundsen')], )], ); $putCode = $researchResources->create($input); // a duplicate `self` proposal identifier throws OrcidConflictException $researchResource = $researchResources->get($putCode); // ->proposal and ->items $researchResources->update($putCode, $input); // replaces the whole item $researchResources->delete($putCode); $list = $researchResources->list(); // groups, as for works: preferred() and summaries() Orcid::public()->record($orcidId)->researchResources()->get($putCode); // reads only
Summaries in a list only carry the proposal: read the research resource by put-code for its items.
Person, activities and the whole record
The bound member connector reads its own record ($orcid->person(), $orcid->activities(), including limited
items with /read-limited). Every connector reads any record's public items through record($id):
$record = Orcid::public()->record('https://orcid.org/0000-0002-1825-0097'); // bare iD or URL $person = $record->person(); $person->name?->displayName(); $person->biography?->content; foreach ($person->keywords as $keyword) { $keyword->content; // "psychoceramics" $keyword->putCode; // every item has its put-code, visibility and source $keyword->visibility; // Visibility::Public $keyword->source?->isClient($myClientId); } $person->otherNames; // OtherName (content) $person->researcherUrls; // ResearcherUrl (url, name) $person->addresses; // Address (country) $person->externalIdentifiers; // PersonExternalIdentifier (externalId: type, value, url) $person->emails; // Email (email, primary, verified) // fetch only what you show, as the same classes $record->biography(); // ?Biography $record->emails(); // list<Email>: public ones only $orcid->emails(); // own record (bound member connector): limited ones too, with /read-limited $details = $record->personalDetails(); // PersonalDetails: name, otherNames, biography $details->name?->displayName(); // every activity section, as the same classes as each section's list() $activities = $record->activities(); $activities->affiliations(AffiliationType::Education); // list<Affiliation> $activities->works->preferred(); // WorkGroups, as works()->list() $activities->fundings->summaries(); // FundingGroups $activities->peerReviews->byReviewGroup(); // PeerReviewGroups $activities->researchResources->groups; // ResearchResourceGroups $activities->workCount(); // the number of groups (review groups for peerReviewCount()) // the whole record in one call: the same Person and ActivitiesSummary $whole = $record->wholeRecord(); // or $orcid->wholeRecord() for the bound record $whole->person->keywords; $whole->activities->works->preferred(); $whole->history?->claimed; $record->affiliations()->list(AffiliationType::Employment); // reads only: no create, update or delete
The record summary is ORCID's short overview of a record: counts by section, split into validated (added by a
client) and self-asserted (added by the researcher), the affiliations in a short form and the person external
identifiers. ORCID only serves it on the Member API, with any token that reads the record (a 3-legged one or a
/read-public client credentials one); on a Public API connector, recordSummary() throws a LogicException before
sending.
$summary = Orcid::member(accessToken: $readPublicToken)->record($orcidId)->recordSummary(); // or $orcid->recordSummary() $summary->works->validated; // ActivityCounts: validated, selfAsserted, total() $summary->peerReviews->total(); $summary->employmentCount; // ORCID's count foreach ($summary->employments as $employment) { // RecordSummaryAffiliation: no department or source $employment->organizationName; $employment->role; $employment->validated; } $summary->educationQualifications; // educations and qualifications $summary->professionalActivities; // invited positions, distinctions, memberships and services $summary->externalIdentifiers; // RecordSummaryExternalIdentifier (type, value, url, validated)
Own-record calls (affiliations(), works(), fundings(), peerReviews(), researchResources(), keywords(),
otherNames(), researcherUrls(), externalIdentifiers(), addresses(), person(), biography(), emails(),
personalDetails(), activities(), wholeRecord(), recordSummary()) on a connector without an orcid throw a
LogicException before anything is sent.
Keywords
Writes need the /person/update scope (Member API). keywords()->list() returns the same Keyword items as
person()->keywords. ORCID refuses a blank keyword or one over 255 characters, which KeywordInput checks before
sending (it also trims the content: ORCID would store "ocean " and "ocean" as two keywords), and a keyword whose
content this client already added (compared case-sensitively).
use VincentAuger\OrcidSdk\Data\Person\KeywordInput; use VincentAuger\OrcidSdk\Exceptions\OrcidConflictException; $keywords = Orcid::member(accessToken: $accessToken, orcid: $orcidId)->keywords(); try { $putCode = $keywords->create(new KeywordInput('fisheries science')); } catch (OrcidConflictException $exception) { $exception->isDuplicate(); // true (error 9030); ORCID does not give the existing put-code } $keywords->get($putCode); // Keyword $keywords->update($putCode, new KeywordInput('fish science')); // returns the updated Keyword $keywords->delete($putCode); $keywords->list(); // list<Keyword>, in the researcher's order Orcid::public()->record($orcidId)->keywords()->list(); // reads only
ORCID ignores a visibility or display index sent by a client: a new keyword gets the researcher's default visibility.
Other names, websites, external identifiers and countries
The other writable person sections work like keywords (/person/update, list|get|create|update|delete, reads
only through record($id)), each returning the same items as person():
use VincentAuger\OrcidSdk\Data\Person\AddressInput; use VincentAuger\OrcidSdk\Data\Person\OtherNameInput; use VincentAuger\OrcidSdk\Data\Person\PersonExternalIdentifierInput; use VincentAuger\OrcidSdk\Data\Person\ResearcherUrlInput; $orcid = Orcid::member(accessToken: $accessToken, orcid: $orcidId); $orcid->otherNames()->create(new OtherNameInput('J. Carberry')); // OtherName $orcid->researcherUrls()->create(new ResearcherUrlInput('https://example.org', 'Lab')); // ResearcherUrl; the name is optional $orcid->externalIdentifiers()->create(new PersonExternalIdentifierInput( // PersonExternalIdentifier 'Scopus Author ID', // free text '1234567', 'https://www.scopus.com/authid/detail.uri?authorId=1234567', // required )); $orcid->addresses()->create(new AddressInput('CA')); // Address: ORCID only stores the country
What the inputs check before sending: a non-blank other name of at most 255 characters (ORCID would store a blank
one); a non-blank URL of at most 2000 characters and a name of at most 350 (ORCID does not check that the URL is
one); a non-blank type, value and URL, type and value of at most 255 characters (always sent as self); an ISO
3166-1 alpha-2 country (uppercased; only its form is checked, ORCID refuses a code it doesn't know). A duplicate is a 409 OrcidConflictException with isDuplicate() (error 9030):
an other name with the same content, a website with the same URL, an identifier with the same type and value.
ORCID accepts the same country twice.
Search
Search is on the connector, not under a record: every connector can search, bound or not. The query is a raw
Solr query (no
query builder). ORCID recommends the Member API with a /read-public client credentials token (higher limits); the
Public API, with or without a token, works the same way.
use VincentAuger\OrcidSdk\Enums\CsvSearchField; $token = $oauth->clientCredentials([Scope::ReadPublic]); $orcid = Orcid::member(accessToken: $token->accessToken); $results = $orcid->search('family-name:Carberry AND affiliation-org-name:"Brown University"'); $results->orcids; // list<string>: the iDs on this page $results->numFound; // every match, across all pages $expanded = $orcid->expandedSearch('ringgold-org-id:5884', start: 0, rows: 200); foreach ($expanded->results as $result) { // ExpandedSearchResult $result->orcid; $result->displayName(); // the credit name, else the given and family names $result->otherNames; $result->emails; // public emails only $result->institutionNames; // current and past affiliations } // a CSV string: a header row, then one row per record (no total found) $csv = $orcid->csvSearch('orcid:0000-0002-1825-0097', [CsvSearchField::Orcid, CsvSearchField::FamilyName]);
A page holds at most Orcid::SEARCH_ROWS_LIMIT (1000) results, ORCID's default and largest page: page through more
with start (ORCID sets no upper bound on it). A blank query, a negative start or rows outside 0 to 1000 throws an
InvalidArgumentException before anything is sent. A query Solr can't parse (e.g. orcid:() is a 500 from ORCID,
so an OrcidServerException whose isRetryable() is true: retrying won't help, fix the query.
Errors
Every convenience method throws a VincentAuger\OrcidSdk\Exceptions\OrcidException. Use isRetryable() to
decide whether to try again later (rate limits, ORCID outages, connection failures):
try { $affiliations->update(AffiliationType::Employment, $putCode, $input); } catch (OrcidAuthException $e) { // 401: the token was revoked or expired; the user must authorize again } catch (OrcidForbiddenException $e) { // 403: $e->isNotSource() (another client created the item) or $e->isMissingScope() } catch (OrcidException $e) { if ($e->isRetryable()) { // retry later } }
Each OrcidRequestException carries ORCID's errorCode, developerMessage and userMessage (or oauthError and
oauthErrorDescription for the OAuth endpoints), and the raw Response:
| Status | Exception | ORCID errors met on the sandbox |
|---|---|---|
| 400 | OrcidValidationException |
9047 (schema), 9020, 9023 (external ids), 9045/9046/9060 (organization), 9050, ... |
| 401 | OrcidAuthException |
invalid_token: bad, revoked or expired token |
| 403 | OrcidForbiddenException |
9010 isNotSource(), 9038 isMissingScope(), 9035 (visibility change) |
| 404 | OrcidNotFoundException |
9016 (unknown put-code), 9001 (unknown endpoint) |
| 409 | OrcidConflictException |
9021 and 9030 isDuplicate(); existingPutCode() for 9021 |
| 429 | OrcidRateLimitException |
retryable |
| 5xx | OrcidServerException |
retryable; 9008 (e.g. a Solr query ORCID can't parse) |
| none | OrcidConnectionException |
retryable: ORCID could not be reached |
Any other status is a plain OrcidRequestException. Many 400s never reach ORCID: the input classes refuse what
ORCID would reject, with an InvalidArgumentException, before sending (and a call ORCID only serves on the Member
API throws a LogicException on a Public API connector).
The SDK is stateless: it never stores or refreshes tokens, and it never retries failed requests. Your application decides where tokens live and when a failed call should be retried (for example, in a queued job).
API coverage
Every call in ORCID's v3.0 guide
(JSON), apart from webhooks for premium members (#17).
"Bound" is a member connector bound to its record, Orcid::member(accessToken:, orcid:); "any" is
$orcid->record($id) on every connector, which only reads.
| ORCID call | SDK |
|---|---|
GET /record |
bound or any: wholeRecord() |
GET /summary (Member API only) |
bound or any: recordSummary() |
GET /activities |
bound or any: activities() |
GET /person, /biography, /email, /personal-details |
bound or any: person(), biography(), emails(), personalDetails() |
/employment, /education, /qualification, /invited-position, /distinction, /membership, /service |
bound: affiliations()->list|get|create|update|delete(AffiliationType, ...); any: list|get |
/work, /works |
bound: works()->list|get|create|update|delete; any: list|get |
POST /works, GET /works/{a,b,...} (bulk) |
bound: works()->createMany(), getMany(); any: getMany() |
/funding, /fundings |
fundings(), as for works |
/peer-review, /peer-reviews |
peerReviews(), as for works |
/research-resource, /research-resources |
researchResources(), as for works |
/keywords, /other-names, /researcher-urls, /external-identifiers, /address |
bound: keywords(), otherNames(), researcherUrls(), externalIdentifiers(), addresses() with list|get|create|update|delete; any: list|get |
GET /search (and /expanded-search, /csv-search) |
every connector: search(), expandedSearch(), csvSearch() |
| OAuth: authorize, token, revoke, userinfo | OrcidOAuth: authorizationUrl(), exchangeCode(), clientCredentials(), refresh(), revoke(), userInfo() |
Testing
composer test
See CONTRIBUTING.md for recording fixtures against the ORCID sandbox.
License
The MIT License (MIT). Please see License File for more information.