# RapidILL Request

A PHP library for creating InterLibrary Loan (ILL) requests using the [RapidILL](https://exlibrisgroup.com/products/rapidill-interlibrary-loan/) 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

```bash
composer require roblib/rapidillrequest
```

### Drupal 10

```bash
composer require roblib/rapidillrequest
```

## Quick Start

```php
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

```php
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

```php
$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

```php
$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)

```php
$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

```php
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):

```php
$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

```bash
composer install
vendor/bin/phpunit
```

## License

GPL-2.0-or-later