Download the PHP package scriptotek/alma-client without Composer

php-alma-client

Simple PHP package for working with the Alma REST APIs. SOAP APIs will not be supported. Currently, this package supports Bibs (read/write), Users and Analytics (read only). It is integrated with php-marc for editing MARC records. If the package doesn't fit your needs, you might take a look at the alternative php-alma package.

Table of Contents

• Install using Composer
• Initializing a client
• Quick intro
• Note about lazy-loading and existence-checking
• Bibs: Bibliographic records, Holdings, Representations, Portfolios
  • Getting a single record
  • The MARC21 record
  • Searching for records
  • Getting linked record from network zone
  • Editing records
  • Holdings and items
  • Item by barcode
  • Electronic portfolios and collections
  • Digital representation and files
• Users, loans, fees and requests
  • Search
  • Loans
  • Fees
  • Requests
• Analytics reports
  • Column names
  • Filters
• Task lists
  • Lending requests
  • Requested resources (pick from shelf)
• Jobs
  • Listing jobs
  • Retrieving information about a specific job
  • Submitting a job
• Automatic retries on errors
• Laravel integration
  • Customizing the HTTP client stack
• Future plans

Created by gh-md-toc

Install using Composer

Use Composer to install sru-client with a HTTP library such as Guzzle:

We use HTTP discovery to discover HTTP client and HTTP factory implementations, so Guzzle can be swapped with any other PSR-17/PSR-18-compatible library.

Initializing a client

Start by initiating a new client with the API key you get at Ex Libris Developer Network:

where 'eu' is the region code for Europe (use 'na' for North America or 'ap' for Asia Pacific). By default, the API entry point URL is generated from the region code, but if you're connecting to the API through a proxy, you can configure a different URL:

If your Alma instance is connected to a network zone and you want to work with bib records there, you can also add an API key for the network zone:

If you want search support, connect an SRU client:

You can also connect an SRU client to the network zone SRU service:

Quick intro

The library provides access to Bibs, Holdings and Items through $alma->bibs, Users ($alma->users), Analytics reports ($alma->analytics), Libraries ($alma->libraries), Task Lists ($alma->taskLists) and Jobs ($alma->jobs).

To fetch a Bib record:

Note about lazy-loading and existence-checking

Lazy loading: Note that the client uses lazy loading to reduce the number of HTTP requests. Requests are not made when you instantiate objects, but when you request data from them. So in this case, a HTTP request for the holding record is first made when you call getRecord(). The response is then cached on the object for re-use. In the same way, no HTTP request is made for the Bib record in this case, since we don't request any data from that.

In general the library delays fetching data until it's actually needed, a practice called lazy-loading. This means you can for instance initialize a Bib object and echo back the MMS id without any network requests taking place, since there is no need to fetch any data yet:

If you request anything else on the Bib object, like the title, the data will automatically be fetched and populated on the object:

If the resource did not exist, a ResourceNotFound exception would be thrown at this point. So you could go ahead and handle that case like so:

But you can also use the exists() method, which is often more convenient:

Bibs: Bibliographic records, Holdings, Representations, Portfolios

Getting a single record

A bibliographic record can be fetched either by MMS ID:

or by barcode:

Note: This methods returns null if the barcode is not found, as does the two methods below.

There are also two lookup methods that use SRU search and require that you have an SRU client attached. The first lets you use a generic CQL query:

The second is a shorthand for looking up records from ISBN:

All the methods above returns either a single Bib record or null if not found.

The MARC21 record

The MARC21 record is available as $bib->record in the form of a php-marc Record object that extends File_MARC_Record from File_MARC, meaning you can use all File_MARC methods in addition to the convenience methods from php-marc.

Searching for records

If you have connected an SRU client (described above), you can search using CQL search syntax like so:

Getting linked record from network zone

If you have configured a network zone API key (see above), you can easily get the network zone record connected to the institution zone record like so:

Editing records

The MARC21 record can be edited using the File_MARC_Record interface (see File_MARC for documentation), and then saved back to Alma using the save() method on the Bib object. In the example below we delete a subject heading and add another:

Holdings and items

The Bib object provides easy access to holdings through the holdings iterator:

As with the Bib object, the MARC record for the Holding object is available either from the getRecord() method or the record property:

Note: Editing holding records is not yet supported. Will be added in the future.

Items can be listed from holdings in the same manner as holdings can be fetched from bibs. Here's an example:

In this case, the client makes one request to fetch the list of holdings, and then one request per holding to fetch items.

Item by barcode

There is a special entrypoint to retrieve an item by barcode:

Electronic portfolios and collections

Electronic portfolios and collections are available on the Bib object in the same way as holdings.

Digital representation and files

Users, loans, fees and requests

Note: Editing is not yet implemented.

Search

Example:

Loans

Example:

Note that $user->loans is an iterator. To get an array instead, you can use iterator_to_array($user->loans).

Fees

Example:

Requests

Example:

Requests can also be retrieved from a Bib object or an Item object.

Analytics reports

To retrieve the results from a single report:

The rows are returned using a generator that takes care of fetching more rows until the result set is depleted, so you don't have to think about continuation. If you only want a subset of the rows, you must take care of breaking out of the loop yourself.

Column names

The column names can be accessed through headers:

The column names can be accessed through can also be used to access columns for a given row:

If you would rather use other column names than the ones defined in Analytics it is also possible to override them by passing in an array of names that must follow the same order as the columns in the report:

Filters

The method also accepts a filter.

There isn't much official documentation on filters, and error responses from the API are generally not useful, but there's some helpful hints in this blog post.

My experience so far is that including a "is prompted" filter in the report is really needed. Otherwise the query returns a 400 No more rows to fetch (after a looong wait).

Furthermore, I've not been successful with pure SQL filters. In OBI you can convert a filter to SQL. The results looks like this:

But used with the API, the response is the same as if you forget to include an "is prompted" filter: a loong wait follow by a "400 No more rows to fetch".

Task lists

Lending requests

``

Note: As of 2018-10-13, there is a bug preventing you from retrieving more than 100 lending requests.

Requested resources (pick from shelf)

Jobs

Listing jobs

To list all jobs and their instances:

This is a generator, so you can start processing results before the full list has been retrieved (it fetches jobs in batches of 10).

Retrieving information about a specific job

Submitting a job

Automatic retries on errors

If the client receives a 429 (rate limiting) response from Alma, it will sleep for a short time (0.5 seconds by default) and retry the request a configurable number of times (10 by default), before giving up and throwing a Scriptotek\Alma\Exception\MaxNumberOfAttemptsExhausted. Both the max number of attempts and the sleep time can be configured:

If the client receives a 5XX server error, it will by default not retry the request, but this can be configured. This can be useful when retrieving large Analytics reports, which have a tendency to fail intermittently.

When the number of retries have been exhausted, a Scriptotek\Alma\Exception\RequestFailed exception is thrown.

Laravel integration

This project ships with an auto-discoverable service provider and facade. Run

$ php artisan vendor:publish --provider="Scriptotek\Alma\Laravel\ServiceProvider"

to create the config/alma.php configuration file.

If you are on Laravel 5.4 or older, you must manually add the service provider to the $providers array in your config/app.php:

Scriptotek\Alma\Laravel\ServiceProvider::class,

And the facade:

'Alma' => Scriptotek\Alma\Laravel\Facade::class,

Customizing the HTTP client stack

If the Laravel Service Container contains a PSR-18 HTTP Client bound to Psr\Http\Client\ClientInterface, Alma Client will use that implementation instead of instantiating its own HTTP client.

Here's an example service provider that registers a HTTP client with some middleware from php-http/client-common:

Future plans

• Better support for editing, perhaps better integration with the php-marc package to provide a fluent editing interface:

• Support for creating records and users: