README

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

InsertRequest

All setters return $this for fluent chaining.

InsertResponse

All properties are readonly.

RequestType (enum)

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

Testing

composer install
vendor/bin/phpunit

License

GPL-2.0-or-later