A PHP library for creating InterLibrary Loan (ILL) requests using the RapidILL API InsertRequest method.

7.4 KiB

Raw Permalink Blame History

RapidILL Request

A PHP library for creating InterLibrary Loan (ILL) requests using the RapidILL API InsertRequest method.

Built on PHP's native SoapClient with no framework dependencies, making it easy to use in any PHP project including Drupal 10.

Requirements

PHP 8.1 or higher
PHP SOAP extension (ext-soap)

Installation

Composer

composer require roblib/rapidillrequest

Drupal 10

composer require roblib/rapidillrequest

Quick Start

use RapidIll\RapidIllClient;
use RapidIll\InsertRequest;
use RapidIll\RequestType;

// Create a client with your RapidILL credentials.
$client = new RapidIllClient(
    username: 'your_username',
    password: 'your_password',
    rapidCode: 'YOUR_RAPID_CODE',
    branchName: 'Main',
);

// Build and submit a request.
$request = (new InsertRequest())
    ->setRequestType(RequestType::Article)
    ->setJournalTitle('Nature')
    ->setArticleTitle('A breakthrough in quantum computing')
    ->setArticleAuthor('Smith, J.')
    ->addIssn('0028-0836');

$response = $client->insertRequest($request);

if ($response->isSuccessful) {
    echo "Request submitted. Rapid ID: {$response->rapidRequestId}\n";
}

Examples

Request a journal article

use RapidIll\RapidIllClient;
use RapidIll\InsertRequest;
use RapidIll\RequestType;

$client = new RapidIllClient(
    username: 'your_username',
    password: 'your_password',
    rapidCode: 'YOUR_RAPID_CODE',
    branchName: 'Main',
);

$request = (new InsertRequest())
    ->setRequestType(RequestType::Article)
    ->setJournalTitle('Nature')
    ->setJournalYear('2024')
    ->setJournalVolume('625')
    ->setJournalIssue('7994')
    ->setJournalMonth('January')
    ->setArticleTitle('A breakthrough in quantum computing')
    ->setArticleAuthor('Smith, J.')
    ->setArticlePages('100-105')
    ->addIssn('0028-0836')
    ->addIssn('1476-4687')
    ->setOclcNumber('1234567')
    ->setPatronName('Jane Doe')
    ->setPatronEmail('jane.doe@university.edu')
    ->setPatronDepartment('Physics')
    ->setXrefRequestId('ILL-2024-00042');

$response = $client->insertRequest($request);

if ($response->isSuccessful) {
    echo "Request ID: {$response->rapidRequestId}\n";
    echo "Match found: " . ($response->foundMatch ? 'yes' : 'no') . "\n";
    echo "Available holdings: {$response->numberOfAvailableHoldings}\n";
} else {
    echo "Request failed: {$response->verificationNote}\n";
}

Request a book

$request = (new InsertRequest())
    ->setRequestType(RequestType::Book)
    ->setJournalTitle('Introduction to Algorithms')
    ->setArticleAuthor('Cormen, Thomas H.')
    ->addIsbn('978-0262033848')
    ->setPublisher('MIT Press')
    ->setEdition('3rd')
    ->setPatronName('John Smith')
    ->setPatronEmail('john.smith@university.edu');

$response = $client->insertRequest($request);

Request a book chapter

$request = (new InsertRequest())
    ->setRequestType(RequestType::BookChapter)
    ->setJournalTitle('The Oxford Handbook of Innovation')
    ->setArticleTitle('Open Innovation')
    ->setArticleAuthor('Chesbrough, Henry')
    ->setArticlePages('191-213')
    ->addIsbn('978-0199286805')
    ->setPatronName('Alice Johnson')
    ->setPatronEmail('alice@university.edu');

$response = $client->insertRequest($request);

Check holdings only (without submitting a request)

$request = (new InsertRequest())
    ->setRequestType(RequestType::Article)
    ->setHoldingsCheckOnly(true)
    ->setJournalTitle('Science')
    ->addIssn('0036-8075');

$response = $client->insertRequest($request);

if ($response->isLocalHolding) {
    echo "Item is available locally:\n";
    foreach ($response->localHoldings as $holding) {
        echo "  Branch: {$holding['branchName']}\n";
        echo "  Location: {$holding['location']}\n";
        echo "  Call Number: {$holding['callNumber']}\n";
    }
} else {
    echo "Not held locally. {$response->numberOfAvailableHoldings} remote holdings available.\n";
}

Error handling

use RapidIll\RapidIllException;

try {
    $response = $client->insertRequest($request);
} catch (RapidIllException $e) {
    // SOAP or connection error.
    error_log('RapidILL error: ' . $e->getMessage());
}

Debugging SOAP requests

The client records the raw SOAP XML when trace is enabled (the default):

$response = $client->insertRequest($request);

// Inspect the XML that was sent and received.
echo $client->getLastRequest();
echo $client->getLastResponse();

API Reference

`RapidIllClient`

Constructor Parameter	Type	Required	Description
`username`	string	yes	RapidILL API username
`password`	string	yes	RapidILL API password
`rapidCode`	string	yes	Your library's Rapid code
`branchName`	string	yes	Your library branch name
`wsdlUrl`	string	no	Override the default WSDL URL
`soapOptions`	array	no	Additional options passed to `SoapClient`

`InsertRequest`

All setters return $this for fluent chaining.

Method	Description
`setRequestType(RequestType)`	`Article`, `Book`, or `BookChapter` (default: `Article`)
`setHoldingsCheckOnly(bool)`	If true, only checks holdings without submitting
`setBlockLocalOnly(bool)`	Block request if only local holdings exist
`setInsertLocalHolding(bool)`	Insert a local holding record
`addIssn(string)`	Add an ISSN
`setIssns(array)`	Set all ISSNs at once
`addIsbn(string)`	Add an ISBN
`setIsbns(array)`	Set all ISBNs at once
`addLccn(string)`	Add an LCCN
`setLccns(array)`	Set all LCCNs at once
`setOclcNumber(string)`	OCLC number
`setJournalTitle(string)`	Journal or book title
`setJournalYear(string)`	Publication year
`setJournalVolume(string)`	Volume number
`setJournalIssue(string)`	Issue number
`setJournalMonth(string)`	Publication month
`setArticleTitle(string)`	Article or chapter title
`setArticleAuthor(string)`	Author name
`setArticlePages(string)`	Page range
`setEdition(string)`	Edition
`setPublisher(string)`	Publisher
`setPatronId(string)`	Patron identifier
`setPatronName(string)`	Patron full name
`setPatronDepartment(string)`	Patron department
`setPatronEmail(string)`	Patron email address
`setPatronPhone(string)`	Patron phone number
`setPatronNotes(string)`	Additional notes
`setXrefRequestId(string)`	Cross-reference ID from your ILL system

`InsertResponse`

All properties are readonly.

Property	Type	Description
`isSuccessful`	bool	Whether the API call succeeded
`foundMatch`	bool	Whether a lending match was found
`rapidRequestId`	int	The assigned Rapid request ID
`numberOfAvailableHoldings`	int	Count of available holdings
`isLocalHolding`	bool	Whether the item is held locally
`verificationNote`	?string	Error or informational message
`matchingStandardNumber`	?string	The matched ISSN/ISBN
`matchingStandardNumberType`	?string	Type of the matched number
`duplicateRequestId`	?string	ID if request is a duplicate
`localHoldings`	array	Array of local holding records

`RequestType` (enum)

RequestType::Article
RequestType::Book
RequestType::BookChapter

Testing

composer install
vendor/bin/phpunit

License

GPL-2.0-or-later

7.4 KiB Raw Permalink Blame History