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 rapidill/request

Drupal 10

Add the package to your Drupal project's composer.json as a path repository if installing from a local copy:

{
    "repositories": [
        {
            "type": "path",
            "url": "/path/to/rapidILL-request"
        }
    ],
    "require": {
        "rapidill/request": "*"
    }
}

Then run:

composer require rapidill/request

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