Search by

vincentauger / orcid-php-sdk

vincentauger

A modern, framework-agnostic PHP SDK for the ORCID API

Package info

github.com/vincentauger/orcid-php-sdk

pkg:composer/vincentauger/orcid-php-sdk

Statistics

Installs: 83

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 8

v0.2.0 2026-11-03 20:03 UTC

This package is auto-updated.

Last update: 2026-11-03 20:06:26 UTC


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 doi review identifier) and its reviewUrl
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.