Folio
extends AbstractAPI
in package
implements
HttpServiceAwareInterface, TranslatorAwareInterface
Uses
SecretTrait, HttpServiceAwareTrait, TranslatorAwareTrait, LoggerAwareTrait, CacheTrait
FOLIO REST API driver
Tags
Interfaces, Classes, Traits and Enums
- HttpServiceAwareInterface
- TranslatorAwareInterface
- Lightweight translator aware marker interface (used as an alternative to \Laminas\I18n\Translator\TranslatorAwareInterface, which requires an excessive number of methods to be implemented).
Table of Contents
- $cache : StorageInterface
- Cache for storing data temporarily (e.g. patron blocks with the ILS driver)
- $cacheLifetime : int
- Lifetime of cache (in seconds).
- $config : array<string|int, mixed>
- Driver configuration
- $courseCache : array<string|int, mixed>|null
- Cache for course reserves course data (null if not yet populated)
- $dateConverter : Converter
- Date converter
- $defaultAvailabilityStatuses : array<string|int, string>
- Default availability messages, in case they are not defined in Folio.ini
- $defaultInTransitStatuses : array<string|int, string>
- Default in_transit messages, in case they are not defined in Folio.ini
- $sessionCache : Container
- Session cache
- $sessionFactory : callable
- Factory function for constructing the SessionContainer.
- $tenant : string
- Authentication tenant (X-Okapi-Tenant)
- $token : string
- Authentication token (X-Okapi-Token)
- $translator : TranslatorInterface
- Translator
- __construct() : mixed
- Constructor
- cancelHolds() : array<string|int, mixed>
- Cancel Holds
- checkRequestIsValid() : array<string|int, mixed>
- Check if request is valid
- findReserves() : mixed
- Find Reserves
- getCancelHoldDetails() : string
- Get FOLIO hold IDs for use in cancelHolds.
- getConfig() : array<string|int, mixed>
- Retrieves renew, hold and cancel settings from the driver ini file.
- getCourses() : array<string|int, mixed>
- Get Courses
- getDepartments() : array<string|int, mixed>
- Get Departments
- getFunds() : array<string|int, mixed>
- Get Funds
- getHolding() : array<string|int, mixed>
- This method queries the ILS for holding information.
- getInstructors() : array<string|int, mixed>
- Get Instructors
- getMyFines() : array<string|int, mixed>
- This method queries the ILS for a patron's current fines
- getMyHolds() : array<string|int, mixed>
- This method queries the ILS for a patron's current holds
- getMyProfile() : array<string|int, mixed>
- This method queries the ILS for a patron's current profile information
- getMyTransactionHistory() : array<string|int, mixed>
- Get Patron Loan History
- getMyTransactions() : array<string|int, mixed>
- This method queries the ILS for a patron's current checked out items
- getNewItems() : array<string|int, mixed>
- Get New Items
- getPickupLocations() : array<string|int, mixed>
- Get Pick Up Locations
- getProxiedUsers() : array<string|int, mixed>
- Get list of users for whom the provided patron is a proxy.
- getProxyingUsers() : array<string|int, mixed>
- Get list of users who act as proxies for the provided patron.
- getPurchaseHistory() : array<string|int, mixed>
- Get Purchase History Data
- getRenewDetails() : string
- Get FOLIO loan IDs for use in renewMyItems.
- getRequestBlocks() : array<string|int, mixed>|bool
- Check for request blocks.
- getStatus() : array<string|int, mixed>
- Get raw object of item from inventory/items/
- getStatuses() : array<string|int, mixed>
- This method calls getStatus for an array of records or implement a bulk method
- getTranslator() : TranslatorInterface
- Get translator object.
- getTranslatorLocale() : string
- Get the locale from the translator.
- init() : void
- Initialize the driver.
- makeRequest() : Response
- Make requests
- patronLogin() : mixed
- Patron Login
- placeHold() : mixed
- Place Hold
- preRequest() : array<string|int, mixed>
- (From AbstractAPI) Allow default corrections to all requests
- renewMyItems() : array<string|int, mixed>
- Attempt to renew a list of items for a given patron.
- setCacheStorage() : void
- Set a cache storage object.
- setConfig() : void
- Set the configuration for the driver.
- setTranslator() : TranslatorAwareInterface
- Set a translator
- translate() : string
- Translate a string (or string-castable object)
- translateWithPrefix() : string
- Translate a string (or string-castable object) using a prefix, or without the prefix if a prefixed translation is not found.
- checkTenantToken() : bool
- Check if our token is still valid. Return true if the token was already valid, false if it had to be renewed.
- chooseCallNumber() : array<string|int, mixed>
- Choose a call number and callnumber prefix.
- debug() : void
- Log a debug message.
- debugRequest() : void
- Function that obscures and logs debug data
- escapeCql() : string
- Escape a string for use in a CQL query.
- extractTextDomain() : array<string|int, mixed>
- Given a translation string with or without a text domain, return an array with the raw string and the text domain separated.
- extractTokenFromResponse() : string
- Given a response from performOkapiUsernamePasswordAuthentication(), extract the token value.
- failureCodeIsAllowed() : bool
- Does $code match the setting for allowed failure codes?
- fetchUserWithCql() : object
- Given a CQL query, fetch a single user; if we get an unexpected count, treat that as an unsuccessful login by returning null.
- formatHoldingItem() : array<string|int, mixed>
- Support method for getHolding() -- given a few key details, format an item for inclusion in the return value.
- formatNote() : string
- Support method: format a note for display
- formatUserNameForProxyList() : string
- Given a user object returned by getUserById(), return a string representing the user's name.
- getBibId() : string
- Given an instance object or identifier, or a holding or item identifier, determine an appropriate value to use as VuFind's bibliographic ID.
- getBibIdType() : string
- Get the type of FOLIO ID used to match up with VuFind's bib IDs.
- getBoundWithRecords() : array<string|int, mixed>
- Get all bib records bound-with this item, including the directly-linked bib record.
- getCachedData() : mixed|null
- Helper function for fetching cached data.
- getCacheKey() : string
- Add instance-specific context to a cache key suffix (to ensure that multiple drivers don't accidentally share values in the cache.
- getCourseDetails() : array<string|int, mixed>
- Given a course listing ID, get an array of associated courses.
- getCourseResourceList() : array<string|int, mixed>
- Obtain a list of course resources, creating an id => value associative array.
- getCurrentLoan() : stdClass|void
- Support method for getHolding(): obtaining any current loan from OKAPI by calling /circulation/loans with the item->id
- getDateTimeFromString() : DateTime
- Convert a FOLIO date string to a DateTime object.
- getDebugTranslation() : string
- Build a debug-mode translation
- getDueDate() : string
- Support method for getHolding(): obtaining the Due Date from the current loan, adjusting the timezone and formatting in universal time with or without due time
- getHoldingDetailsForItem() : array<string|int, mixed>
- Support method for getHolding(): extract details from the holding record that will be needed by formatHoldingItem() below.
- getInstanceByBibId() : object
- Retrieve FOLIO instance using VuFind's chosen bibliographic identifier.
- getInstanceById() : object
- Given some kind of identifier (instance, holding or item), retrieve the associated instance object from FOLIO.
- getInstructorIds() : array<string|int, mixed>
- Given a course listing ID, get an array of associated instructors.
- getInstructorsCourseListingsFilterCallback() : callable|null
- Get the callback (or null for no callback) for filtering the course listings used to retrieve instructor data.
- getItemById() : stdClass
- Get an item record by its UUID.
- getItemFieldsFromNonItemData() : array<string|int, mixed>
- Support method for getHolding() -- return an array of item-level details from other data: the location, the holdings record, and any current loan on the item.
- getLocationData() : array<string|int, mixed>
- Get Inventory Location Name
- getLocations() : array<string|int, mixed>
- Gets locations from the /locations endpoint and sets an array of location IDs to display names.
- getModuleMajorVersion() : int
- Get latest major version of a $moduleName enabled for a tenant.
- getPagedResults() : array<string|int, mixed>
- Helper function to retrieve paged results from FOLIO API
- getRequestTypeList() : array<string|int, mixed>
- Support method for placeHold(): get a list of request types to try.
- getSecretFromConfig() : string|null
- Load a secret value from the specified configuration and key.
- getUserById() : object|null
- Given a user UUID, return the user's profile object (null if not found).
- getUserWithCql() : string
- Support method for patronLogin(): authenticate the patron with a CQL looup.
- isHoldable() : bool
- Check whether an item is holdable based on its location and any current loan
- isHoldableByCurrentLoan() : bool
- Check whether an item is holdable based on any current loan
- isHoldableLocation() : bool
- Check item location against list of configured locations where holds should be offered
- loadProxyUserData() : array<string|int, mixed>
- Support method for getProxiedUsers() and getProxyingUsers() to load proxy user data.
- log() : void
- Send a message to the logger.
- logError() : void
- Log an error message.
- logWarning() : void
- Log a warning message.
- patronLoginWithOkapi() : string
- Support method for patronLogin(): authenticate the patron with an Okapi login attempt. Returns a CQL query for retrieving more information about the authenticated user.
- performHoldRequest() : array<string|int, mixed>
- Support method for placeHold(): send the request and process the response.
- performOkapiUsernamePasswordAuthentication() : Response
- Support method to perform a username/password login to Okapi.
- putCachedData() : void
- Helper function for storing cached data.
- removeCachedData() : void
- Helper function for removing cached data.
- renewTenantToken() : void
- Login and receive a new token
- sanitizeTranslationKey() : string
- Make sure there are not any illegal characters in the translation key that might prevent successful lookup in language files.
- shouldRetryAfterUnexpectedStatusCode() : bool
- Support method for makeRequest to process an unexpected status code. Can return true to trigger a retry of the API call or false to throw an exception.
- sortHoldings() : array<string|int, mixed>
- Given a holdings array and a sort field, sort the array.
- throwAsIlsException() : never
- Rethrow the provided exception as an ILS exception.
- translateString() : string
- Get translation for a string
- useLegacyAuthentication() : bool
- Should we use the legacy authentication mechanism?
- userObjectToNameString() : string
- Given a user object from the FOLIO API, return a name string.
Properties
$cache
Cache for storing data temporarily (e.g. patron blocks with the ILS driver)
protected
StorageInterface
$cache
= null
$cacheLifetime
Lifetime of cache (in seconds).
protected
int
$cacheLifetime
= 30
$config
Driver configuration
protected
array<string|int, mixed>
$config
= []
$courseCache
Cache for course reserves course data (null if not yet populated)
protected
array<string|int, mixed>|null
$courseCache
= null
$dateConverter
Date converter
protected
Converter
$dateConverter
$defaultAvailabilityStatuses
Default availability messages, in case they are not defined in Folio.ini
protected
array<string|int, string>
$defaultAvailabilityStatuses
= ['Open - Awaiting pickup']
$defaultInTransitStatuses
Default in_transit messages, in case they are not defined in Folio.ini
protected
array<string|int, string>
$defaultInTransitStatuses
= ['Open - In transit', 'Open - Awaiting delivery']
$sessionCache
Session cache
protected
Container
$sessionCache
$sessionFactory
Factory function for constructing the SessionContainer.
protected
callable
$sessionFactory
$tenant
Authentication tenant (X-Okapi-Tenant)
protected
string
$tenant
= null
$token
Authentication token (X-Okapi-Token)
protected
string
$token
= null
$translator
Translator
protected
TranslatorInterface
$translator
= null
Methods
__construct()
Constructor
public
__construct(Converter $dateConverter, callable $sessionFactory) : mixed
Parameters
- $dateConverter : Converter
-
Date converter object
- $sessionFactory : callable
-
Factory function returning SessionContainer object
Return values
mixed —cancelHolds()
Cancel Holds
public
cancelHolds(array<string|int, mixed> $cancelDetails) : array<string|int, mixed>
Attempts to Cancel a hold or recall on a particular item. The data in $cancelDetails['details'] is determined by getCancelHoldDetails().
Parameters
- $cancelDetails : array<string|int, mixed>
-
An array of item and patron data
Return values
array<string|int, mixed> —An array of data on each request including whether or not it was successful and a system message (if available)
checkRequestIsValid()
Check if request is valid
public
checkRequestIsValid(string $id, array<string|int, mixed> $data, array<string|int, mixed> $patron) : array<string|int, mixed>
This is responsible for determining if an item is requestable
Parameters
- $id : string
-
The record id
- $data : array<string|int, mixed>
-
An array of item data
- $patron : array<string|int, mixed>
-
An array of patron data
Return values
array<string|int, mixed> —Two entries: 'valid' (boolean) plus 'status' (message to display to user)
findReserves()
Find Reserves
public
findReserves(string $course, string $inst, string $dept) : mixed
Obtain information on course reserves.
Parameters
- $course : string
-
ID from getCourses (empty string to match all)
- $inst : string
-
ID from getInstructors (empty string to match all)
- $dept : string
-
ID from getDepartments (empty string to match all)
Return values
mixed —An array of associative arrays representing reserve items.
getCancelHoldDetails()
Get FOLIO hold IDs for use in cancelHolds.
public
getCancelHoldDetails(array<string|int, mixed> $hold[, array<string|int, mixed> $patron = [] ]) : string
Parameters
- $hold : array<string|int, mixed>
-
A single hold array from getMyHolds
- $patron : array<string|int, mixed> = []
-
Patron information from patronLogin
Tags
Return values
string —request ID for this request
getConfig()
Retrieves renew, hold and cancel settings from the driver ini file.
public
getConfig(string $function[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>
Parameters
- $function : string
-
The name of the feature to be checked
- $params : array<string|int, mixed> = []
-
Optional feature-specific parameters (array)
Tags
Return values
array<string|int, mixed> —An array with key-value pairs.
getCourses()
Get Courses
public
getCourses() : array<string|int, mixed>
Obtain a list of courses for use in limiting the reserves list.
Return values
array<string|int, mixed> —An associative array with key = ID, value = name.
getDepartments()
Get Departments
public
getDepartments() : array<string|int, mixed>
Obtain a list of departments for use in limiting the reserves list.
Return values
array<string|int, mixed> —An associative array with key = dept. ID, value = dept. name.
getFunds()
Get Funds
public
getFunds() : array<string|int, mixed>
Return a list of funds which may be used to limit the getNewItems list.
Return values
array<string|int, mixed> —An associative array with key = fund ID, value = fund name.
getHolding()
This method queries the ILS for holding information.
public
getHolding(string $bibId[, array<string|int, mixed> $patron = null ][, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>
Parameters
- $bibId : string
-
Bib-level id
- $patron : array<string|int, mixed> = null
-
Patron login information from $this->patronLogin
- $options : array<string|int, mixed> = []
-
Extra options (not currently used)
Tags
Return values
array<string|int, mixed> —An array of associative holding arrays
getInstructors()
Get Instructors
public
getInstructors() : array<string|int, mixed>
Obtain a list of instructors for use in limiting the reserves list.
Return values
array<string|int, mixed> —An associative array with key = ID, value = name.
getMyFines()
This method queries the ILS for a patron's current fines
public
getMyFines(array<string|int, mixed> $patron) : array<string|int, mixed>
Parameters
- $patron : array<string|int, mixed>
-
The patron array from patronLogin
Return values
array<string|int, mixed> —getMyHolds()
This method queries the ILS for a patron's current holds
public
getMyHolds(array<string|int, mixed> $patron) : array<string|int, mixed>
Input: Patron array returned by patronLogin method Output: Returns an array of associative arrays, one for each hold associated with the specified account. Each associative array contains these keys: type - A string describing the type of hold – i.e. hold vs. recall (optional). id - The bibliographic record ID associated with the hold (optional). source - The search backend from which the record may be retrieved (optional - defaults to Solr). Introduced in VuFind 2.4. location - A string describing the pickup location for the held item (optional). In VuFind 1.2, this should correspond with a locationID value from getPickUpLocations. In VuFind 1.3 and later, it may be either a locationID value or a raw ready-to-display string. reqnum - A control number for the request (optional). expire - The expiration date of the hold (a string). create - The creation date of the hold (a string). position – The position of the user in the holds queue (optional) available – Whether or not the hold is available (true/false) (optional) item_id – The item id the request item (optional). volume – The volume number of the item (optional) publication_year – The publication year of the item (optional) title - The title of the item (optional – only used if the record cannot be found in VuFind's index). isbn - An ISBN for use in cover image loading (optional) issn - An ISSN for use in cover image loading (optional) oclc - An OCLC number for use in cover image loading (optional) upc - A UPC for use in cover image loading (optional) cancel_details - The cancel token, or a blank string if cancel is illegal for this hold; if omitted, this will be dynamically generated using getCancelHoldDetails(). You should only fill this in if it is more efficient to calculate the value up front; if it is an expensive calculation, you should omit the value entirely and let getCancelHoldDetails() do its job on demand. This optional feature was introduced in release 3.1.
Parameters
- $patron : array<string|int, mixed>
-
Patron login information from $this->patronLogin
Return values
array<string|int, mixed> —Associative array of holds information
getMyProfile()
This method queries the ILS for a patron's current profile information
public
getMyProfile(array<string|int, mixed> $patron) : array<string|int, mixed>
Parameters
- $patron : array<string|int, mixed>
-
Patron login information from $this->patronLogin
Return values
array<string|int, mixed> —Profile data in associative array
getMyTransactionHistory()
Get Patron Loan History
public
getMyTransactionHistory(array<string|int, mixed> $patron, array<string|int, mixed> $params) : array<string|int, mixed>
This is responsible for retrieving all historic loans (i.e. items previously checked out and then returned), for a specific patron.
Parameters
- $patron : array<string|int, mixed>
-
The patron array from patronLogin
- $params : array<string|int, mixed>
-
Parameters
Tags
Return values
array<string|int, mixed> —Array of the patron's transactions on success.
getMyTransactions()
This method queries the ILS for a patron's current checked out items
public
getMyTransactions(array<string|int, mixed> $patron) : array<string|int, mixed>
Input: Patron array returned by patronLogin method Output: Returns an array of associative arrays. Each associative array contains these keys: duedate - The item's due date (a string). dueTime - The item's due time (a string, optional). dueStatus - A special status – may be 'due' (for items due very soon) or 'overdue' (for overdue items). (optional). id - The bibliographic ID of the checked out item. source - The search backend from which the record may be retrieved (optional - defaults to Solr). Introduced in VuFind 2.4. barcode - The barcode of the item (optional). renew - The number of times the item has been renewed (optional). renewLimit - The maximum number of renewals allowed (optional - introduced in VuFind 2.3). request - The number of pending requests for the item (optional). volume – The volume number of the item (optional). publication_year – The publication year of the item (optional). renewable – Whether or not an item is renewable (required for renewals). message – A message regarding the item (optional). title - The title of the item (optional – only used if the record cannot be found in VuFind's index). item_id - this is used to match up renew responses and must match the item_id in the renew response. institution_name - Display name of the institution that owns the item. isbn - An ISBN for use in cover image loading (optional – introduced in release 2.3) issn - An ISSN for use in cover image loading (optional – introduced in release 2.3) oclc - An OCLC number for use in cover image loading (optional – introduced in release 2.3) upc - A UPC for use in cover image loading (optional – introduced in release 2.3) borrowingLocation - A string describing the location where the item was checked out (optional – introduced in release 2.4)
Parameters
- $patron : array<string|int, mixed>
-
Patron login information from $this->patronLogin
Return values
array<string|int, mixed> —Transactions associative arrays
getNewItems()
Get New Items
public
getNewItems(int $page, int $limit, int $daysOld[, int $fundId = null ]) : array<string|int, mixed>
Retrieve the IDs of items recently added to the catalog.
Parameters
- $page : int
-
Page number of results to retrieve (counting starts at 1)
- $limit : int
-
The size of each page of results to retrieve
- $daysOld : int
-
The maximum age of records to retrieve in days (max. 30)
- $fundId : int = null
-
optional fund ID to use for limiting results (use a value returned by getFunds, or exclude for no limit); note that "fund" may be a misnomer - if funds are not an appropriate way to limit your new item results, you can return a different set of values from getFunds. The important thing is that this parameter supports an ID returned by getFunds, whatever that may mean.
Tags
Return values
array<string|int, mixed> —Associative array with 'count' and 'results' keys
getPickupLocations()
Get Pick Up Locations
public
getPickupLocations(array<string|int, mixed> $patron[, array<string|int, mixed> $holdInfo = null ]) : array<string|int, mixed>
This is responsible get a list of valid locations for holds / recall retrieval
Parameters
- $patron : array<string|int, mixed>
-
Patron information returned by $this->patronLogin
- $holdInfo : array<string|int, mixed> = null
-
Optional array, only passed in when getting a list in the context of placing or editing a hold. When placing a hold, it contains most of the same values passed to placeHold, minus the patron data. When editing a hold it contains all the hold information returned by getMyHolds. May be used to limit the pickup options or may be ignored. The driver must not add new options to the return array based on this data or other areas of VuFind may behave incorrectly.
Tags
Return values
array<string|int, mixed> —An array of associative arrays with locationID and locationDisplay keys
getProxiedUsers()
Get list of users for whom the provided patron is a proxy.
public
getProxiedUsers(array<string|int, mixed> $patron) : array<string|int, mixed>
Parameters
- $patron : array<string|int, mixed>
-
The patron array with username and password
Return values
array<string|int, mixed> —getProxyingUsers()
Get list of users who act as proxies for the provided patron.
public
getProxyingUsers(array<string|int, mixed> $patron) : array<string|int, mixed>
Parameters
- $patron : array<string|int, mixed>
-
The patron array with username and password
Tags
Return values
array<string|int, mixed> —getPurchaseHistory()
Get Purchase History Data
public
getPurchaseHistory(string $bibID) : array<string|int, mixed>
This is responsible for retrieving the acquisitions history data for the specific record (usually recently received issues of a serial). It is used by getHoldings() and getPurchaseHistory() depending on whether the purchase history is displayed by holdings or in a separate list.
Parameters
- $bibID : string
-
The record id to retrieve the info for
Tags
Return values
array<string|int, mixed> —An array with the acquisitions data on success.
getRenewDetails()
Get FOLIO loan IDs for use in renewMyItems.
public
getRenewDetails(array<string|int, mixed> $transaction) : string
Parameters
- $transaction : array<string|int, mixed>
-
An single transaction array from getMyTransactions
Return values
string —The FOLIO loan ID for this loan
getRequestBlocks()
Check for request blocks.
public
getRequestBlocks(array<string|int, mixed> $patron) : array<string|int, mixed>|bool
Parameters
- $patron : array<string|int, mixed>
-
The patron array with username and password
Tags
Return values
array<string|int, mixed>|bool —An array of block messages or false if there are no blocks
getStatus()
Get raw object of item from inventory/items/
public
getStatus(string $itemId) : array<string|int, mixed>
Parameters
- $itemId : string
-
Item-level id
Return values
array<string|int, mixed> —getStatuses()
This method calls getStatus for an array of records or implement a bulk method
public
getStatuses(array<string|int, mixed> $idList) : array<string|int, mixed>
Parameters
- $idList : array<string|int, mixed>
-
Item-level ids
Return values
array<string|int, mixed> —values from getStatus
getTranslator()
Get translator object.
public
getTranslator() : TranslatorInterface
Return values
TranslatorInterface —getTranslatorLocale()
Get the locale from the translator.
public
getTranslatorLocale([string $default = 'en' ]) : string
Parameters
- $default : string = 'en'
-
Default to use if translator absent.
Return values
string —init()
Initialize the driver.
public
init() : void
Check or renew our auth token
Return values
void —makeRequest()
Make requests
public
makeRequest([string $method = 'GET' ][, string $path = '/' ][, string|array<string|int, mixed> $params = [] ][, array<string|int, mixed> $headers = [] ][, true|array<string|int, int>|string $allowedFailureCodes = [] ][, string|array<string|int, mixed> $debugParams = null ][, int $attemptNumber = 1 ]) : Response
Parameters
- $method : string = 'GET'
-
GET/POST/PUT/DELETE/etc
- $path : string = '/'
-
API path (with a leading /)
- $params : string|array<string|int, mixed> = []
-
Query parameters
- $headers : array<string|int, mixed> = []
-
Additional headers
- $allowedFailureCodes : true|array<string|int, int>|string = []
-
HTTP failure codes that should NOT cause an ILSException to be thrown. May be an array of integers, a regular expression, or boolean true to allow all codes.
- $debugParams : string|array<string|int, mixed> = null
-
Value to use in place of $params in debug messages (useful for concealing sensitive data, etc.)
- $attemptNumber : int = 1
-
Counter to keep track of attempts (starts at 1 for the first attempt)
Tags
Return values
Response —patronLogin()
Patron Login
public
patronLogin(string $username, string $password) : mixed
This is responsible for authenticating a patron against the catalog.
Parameters
- $username : string
-
The patron username
- $password : string
-
The patron password
Return values
mixed —Associative array of patron info on successful login, null on unsuccessful login.
placeHold()
Place Hold
public
placeHold(array<string|int, mixed> $holdDetails) : mixed
Attempts to place a hold or recall on a particular item and returns an array with result details.
Parameters
- $holdDetails : array<string|int, mixed>
-
An array of item and patron data
Return values
mixed —An array of data on the request including whether or not it was successful and a system message (if available)
preRequest()
(From AbstractAPI) Allow default corrections to all requests
public
preRequest(Headers $headers, object $params) : array<string|int, mixed>
Add X-Okapi headers and Content-Type to every request
Parameters
- $headers : Headers
-
the request headers
- $params : object
-
the parameters object
Return values
array<string|int, mixed> —renewMyItems()
Attempt to renew a list of items for a given patron.
public
renewMyItems(array<string|int, mixed> $renewDetails) : array<string|int, mixed>
Parameters
- $renewDetails : array<string|int, mixed>
-
An associative array with patron and details
Return values
array<string|int, mixed> —$renewResult result of attempt to renew loans
setCacheStorage()
Set a cache storage object.
public
setCacheStorage([StorageInterface $cache = null ]) : void
Parameters
- $cache : StorageInterface = null
-
Cache storage interface
Return values
void —setConfig()
Set the configuration for the driver.
public
setConfig(array<string|int, mixed> $config) : void
Parameters
- $config : array<string|int, mixed>
-
Configuration array (usually loaded from a VuFind .ini file whose name corresponds with the driver class name).
Tags
Return values
void —setTranslator()
Set a translator
public
setTranslator(TranslatorInterface $translator) : TranslatorAwareInterface
Parameters
- $translator : TranslatorInterface
-
Translator
Return values
TranslatorAwareInterface —translate()
Translate a string (or string-castable object)
public
translate(string|object|array<string|int, mixed> $target[, array<string|int, mixed> $tokens = [] ][, string $default = null ][, bool $useIcuFormatter = false ][, array<string|int, string> $fallbackDomains = [] ]) : string
Parameters
- $target : string|object|array<string|int, mixed>
-
String to translate or an array of text domain and string to translate
- $tokens : array<string|int, mixed> = []
-
Tokens to inject into the translated string
- $default : string = null
-
Default value to use if no translation is found (null for no default).
- $useIcuFormatter : bool = false
-
Should we use an ICU message formatter instead of the default behavior?
- $fallbackDomains : array<string|int, string> = []
-
Text domains to check if no match is found in the domain specified in $target
Return values
string —translateWithPrefix()
Translate a string (or string-castable object) using a prefix, or without the prefix if a prefixed translation is not found.
public
translateWithPrefix(string $prefix, string|object|array<string|int, mixed> $target[, array<string|int, mixed> $tokens = [] ][, string $default = null ][, bool $useIcuFormatter = false ][, array<string|int, string> $fallbackDomains = [] ]) : string
Parameters
- $prefix : string
-
Translation key prefix
- $target : string|object|array<string|int, mixed>
-
String to translate or an array of text domain and string to translate
- $tokens : array<string|int, mixed> = []
-
Tokens to inject into the translated string
- $default : string = null
-
Default value to use if no translation is found (null for no default).
- $useIcuFormatter : bool = false
-
Should we use an ICU message formatter instead of the default behavior?
- $fallbackDomains : array<string|int, string> = []
-
Text domains to check if no match is found in the domain specified in $target
Return values
string —checkTenantToken()
Check if our token is still valid. Return true if the token was already valid, false if it had to be renewed.
protected
checkTenantToken() : bool
Method taken from Stripes JS (loginServices.js:validateUser)
Return values
bool —chooseCallNumber()
Choose a call number and callnumber prefix.
protected
chooseCallNumber(string $hCallNumP, string $hCallNum, string $iCallNumP, string $iCallNum) : array<string|int, mixed>
Parameters
- $hCallNumP : string
-
Holding-level call number prefix
- $hCallNum : string
-
Holding-level call number
- $iCallNumP : string
-
Item-level call number prefix
- $iCallNum : string
-
Item-level call number
Return values
array<string|int, mixed> —with call number and call number prefix.
debug()
Log a debug message.
protected
debug(string $msg[, array<string|int, mixed> $context = [] ][, bool $prependClass = true ]) : void
Parameters
- $msg : string
-
Log message
- $context : array<string|int, mixed> = []
-
Log context
- $prependClass : bool = true
-
Prepend class name to message?
Return values
void —debugRequest()
Function that obscures and logs debug data
protected
debugRequest(string $method, string $path, array<string|int, mixed> $params, Headers $req_headers) : void
Parameters
- $method : string
-
Request method (GET/POST/PUT/DELETE/etc.)
- $path : string
-
Request URL
- $params : array<string|int, mixed>
-
Request parameters
- $req_headers : Headers
-
Headers object
Return values
void —escapeCql()
Escape a string for use in a CQL query.
protected
escapeCql(string $in) : string
Parameters
- $in : string
-
Input string
Return values
string —extractTextDomain()
Given a translation string with or without a text domain, return an array with the raw string and the text domain separated.
protected
extractTextDomain(string|object|array<string|int, mixed> $target) : array<string|int, mixed>
Parameters
- $target : string|object|array<string|int, mixed>
-
String to translate or an array of text domain and string to translate
Return values
array<string|int, mixed> —extractTokenFromResponse()
Given a response from performOkapiUsernamePasswordAuthentication(), extract the token value.
protected
extractTokenFromResponse(Response $response) : string
Parameters
- $response : Response
-
Response from performOkapiUsernamePasswordAuthentication().
Return values
string —failureCodeIsAllowed()
Does $code match the setting for allowed failure codes?
protected
failureCodeIsAllowed(int $code, true|array<string|int, int>|string $allowedFailureCodes) : bool
Parameters
- $code : int
-
Code to check.
- $allowedFailureCodes : true|array<string|int, int>|string
-
HTTP failure codes that should NOT cause an ILSException to be thrown. May be an array of integers, a regular expression, or boolean true to allow all codes.
Return values
bool —fetchUserWithCql()
Given a CQL query, fetch a single user; if we get an unexpected count, treat that as an unsuccessful login by returning null.
protected
fetchUserWithCql(string $query) : object
Parameters
- $query : string
-
CQL query
Return values
object —formatHoldingItem()
Support method for getHolding() -- given a few key details, format an item for inclusion in the return value.
protected
formatHoldingItem(string $bibId, array<string|int, mixed> $holdingDetails, object $item, int $number, string $dueDateValue, array<string|int, mixed> $boundWithRecords, stdClass|null $currentLoan) : array<string|int, mixed>
Parameters
- $bibId : string
-
Current bibliographic ID
- $holdingDetails : array<string|int, mixed>
-
Holding details produced by getHoldingDetailsForItem()
- $item : object
-
FOLIO item record (decoded from JSON)
- $number : int
-
The current item number (position within current holdings record)
- $dueDateValue : string
-
The due date to display to the user
- $boundWithRecords : array<string|int, mixed>
-
Any bib records this holding is bound with
- $currentLoan : stdClass|null
-
Any current loan on this item
Return values
array<string|int, mixed> —formatNote()
Support method: format a note for display
protected
formatNote(object $note) : string
Parameters
- $note : object
-
Note object decoded from FOLIO JSON.
Return values
string —formatUserNameForProxyList()
Given a user object returned by getUserById(), return a string representing the user's name.
protected
formatUserNameForProxyList(object $proxy) : string
Parameters
- $proxy : object
-
User object from FOLIO
Return values
string —getBibId()
Given an instance object or identifier, or a holding or item identifier, determine an appropriate value to use as VuFind's bibliographic ID.
protected
getBibId([string $instanceOrInstanceId = null ][, string $holdingId = null ][, string $itemId = null ]) : string
Parameters
- $instanceOrInstanceId : string = null
-
Instance object or ID (will be looked up using holding or item ID if not provided)
- $holdingId : string = null
-
Holding-level id (optional)
- $itemId : string = null
-
Item-level id (optional)
Return values
string —Appropriate bib id retrieved from FOLIO identifiers
getBibIdType()
Get the type of FOLIO ID used to match up with VuFind's bib IDs.
protected
getBibIdType() : string
Return values
string —getBoundWithRecords()
Get all bib records bound-with this item, including the directly-linked bib record.
protected
getBoundWithRecords(object $item) : array<string|int, mixed>
Parameters
- $item : object
-
The item record
Return values
array<string|int, mixed> —An array of key metadata for each bib record
getCachedData()
Helper function for fetching cached data.
protected
getCachedData(string $key) : mixed|null
Data is cached for up to $this->cacheLifetime.
Parameters
- $key : string
-
Cache entry key
Return values
mixed|null —Cached entry or null if not cached or expired
getCacheKey()
Add instance-specific context to a cache key suffix (to ensure that multiple drivers don't accidentally share values in the cache.
protected
getCacheKey([string $key = null ]) : string
Parameters
- $key : string = null
-
Cache key suffix
Return values
string —getCourseDetails()
Given a course listing ID, get an array of associated courses.
protected
getCourseDetails(string $courseListingId) : array<string|int, mixed>
Parameters
- $courseListingId : string
-
Course listing ID
Return values
array<string|int, mixed> —getCourseResourceList()
Obtain a list of course resources, creating an id => value associative array.
protected
getCourseResourceList(string $type[, string $responseKey = null ][, string|array<string|int, mixed> $valueKey = 'name' ][, string $formatStr = '%s' ][, callable $filterCallback = null ]) : array<string|int, mixed>
Parameters
- $type : string
-
Type of resource to retrieve from the API.
- $responseKey : string = null
-
Key containing useful values in response (defaults to $type if unspecified)
- $valueKey : string|array<string|int, mixed> = 'name'
-
Key containing value(s) to extract from response (defaults to 'name')
- $formatStr : string = '%s'
-
A sprintf format string for assembling the parameters retrieved using $valueKey
- $filterCallback : callable = null
-
An optional callback that can return true to flag values that should be filtered out.
Return values
array<string|int, mixed> —getCurrentLoan()
Support method for getHolding(): obtaining any current loan from OKAPI by calling /circulation/loans with the item->id
protected
getCurrentLoan(string $itemId) : stdClass|void
Parameters
- $itemId : string
-
ID for the item to query
Return values
stdClass|void —getDateTimeFromString()
Convert a FOLIO date string to a DateTime object.
protected
getDateTimeFromString(string $str) : DateTime
Parameters
- $str : string
-
FOLIO date string
Return values
DateTime —getDebugTranslation()
Build a debug-mode translation
protected
getDebugTranslation(string $domain, string $str, array<string|int, mixed> $tokens) : string
Parameters
- $domain : string
-
Text domain
- $str : string
-
String to translate
- $tokens : array<string|int, mixed>
-
Tokens to inject into the translated string
Return values
string —getDueDate()
Support method for getHolding(): obtaining the Due Date from the current loan, adjusting the timezone and formatting in universal time with or without due time
protected
getDueDate(stdClass|string $loan, bool $showTime) : string
Parameters
- $loan : stdClass|string
-
The current loan, or its itemId for backwards compatibility
- $showTime : bool
-
Determines if date or date & time is returned
Return values
string —getHoldingDetailsForItem()
Support method for getHolding(): extract details from the holding record that will be needed by formatHoldingItem() below.
protected
getHoldingDetailsForItem(object $holding) : array<string|int, mixed>
Parameters
- $holding : object
-
FOLIO holding record (decoded from JSON)
Return values
array<string|int, mixed> —getInstanceByBibId()
Retrieve FOLIO instance using VuFind's chosen bibliographic identifier.
protected
getInstanceByBibId(string $bibId) : object
Parameters
- $bibId : string
-
Bib-level id
Return values
object —getInstanceById()
Given some kind of identifier (instance, holding or item), retrieve the associated instance object from FOLIO.
protected
getInstanceById([string $instanceId = null ][, string $holdingId = null ][, string $itemId = null ]) : object
Parameters
- $instanceId : string = null
-
Instance ID, if available.
- $holdingId : string = null
-
Holding ID, if available.
- $itemId : string = null
-
Item ID, if available.
Return values
object —getInstructorIds()
Given a course listing ID, get an array of associated instructors.
protected
getInstructorIds(string $courseListingId) : array<string|int, mixed>
Parameters
- $courseListingId : string
-
Course listing ID
Return values
array<string|int, mixed> —getInstructorsCourseListingsFilterCallback()
Get the callback (or null for no callback) for filtering the course listings used to retrieve instructor data.
protected
getInstructorsCourseListingsFilterCallback() : callable|null
Return values
callable|null —getItemById()
Get an item record by its UUID.
protected
getItemById(string $itemId) : stdClass
Parameters
- $itemId : string
-
UUID
Return values
stdClass —The item
getItemFieldsFromNonItemData()
Support method for getHolding() -- return an array of item-level details from other data: the location, the holdings record, and any current loan on the item.
protected
getItemFieldsFromNonItemData(string $locationId, array<string|int, mixed> $holdingDetails[, stdClass|null $currentLoan = null ]) : array<string|int, mixed>
Depending on where this method is called, $locationId will be the holdings record location (in the case where no items are attached to a holding) or the item record location (in cases where there are attached items).
Parameters
- $locationId : string
-
Location identifier from FOLIO
- $holdingDetails : array<string|int, mixed>
-
Holding details produced by getHoldingDetailsForItem()
- $currentLoan : stdClass|null = null
-
Any current loan on this item
Return values
array<string|int, mixed> —getLocationData()
Get Inventory Location Name
protected
getLocationData(string $locationId) : array<string|int, mixed>
Parameters
- $locationId : string
-
UUID of item location
Return values
array<string|int, mixed> —with the display name and code of location
getLocations()
Gets locations from the /locations endpoint and sets an array of location IDs to display names.
protected
getLocations() : array<string|int, mixed>
Display names are set from discoveryDisplayName, or name if discoveryDisplayName is not available.
Return values
array<string|int, mixed> —getModuleMajorVersion()
Get latest major version of a $moduleName enabled for a tenant.
protected
getModuleMajorVersion(string $moduleName) : int
Result is cached.
Parameters
- $moduleName : string
-
module name
Return values
int —module version or 0 if no module found
getPagedResults()
Helper function to retrieve paged results from FOLIO API
protected
getPagedResults(string $responseKey, string $interface[, array<string|int, mixed> $query = [] ][, int $limit = 1000 ]) : array<string|int, mixed>
Parameters
- $responseKey : string
-
Key containing values to collect in response
- $interface : string
-
FOLIO api interface to call
- $query : array<string|int, mixed> = []
-
Extra GET parameters (e.g. ['query' => 'your cql here'])
- $limit : int = 1000
-
How many results to retrieve from FOLIO per call
Return values
array<string|int, mixed> —getRequestTypeList()
Support method for placeHold(): get a list of request types to try.
protected
getRequestTypeList(string $preferred) : array<string|int, mixed>
Parameters
- $preferred : string
-
Method to try first.
Return values
array<string|int, mixed> —getSecretFromConfig()
Load a secret value from the specified configuration and key.
protected
getSecretFromConfig(Config|array<string|int, mixed>|null $config, string $key) : string|null
Will look for a _file-suffixed version of the key first, and load the data from a separate file if configured to do so.
Parameters
- $config : Config|array<string|int, mixed>|null
-
The config to read from
- $key : string
-
The key to retrieve
Return values
string|null —getUserById()
Given a user UUID, return the user's profile object (null if not found).
protected
getUserById(string $id) : object|null
Parameters
- $id : string
-
User UUID
Return values
object|null —getUserWithCql()
Support method for patronLogin(): authenticate the patron with a CQL looup.
protected
getUserWithCql(string $username, string $password) : string
Returns the CQL query for retrieving more information about the user.
Parameters
- $username : string
-
The patron username
- $password : string
-
The patron password
Return values
string —isHoldable()
Check whether an item is holdable based on its location and any current loan
protected
isHoldable(string $locationName[, stdClass|null $currentLoan = null ]) : bool
Parameters
- $locationName : string
-
locationName from getHolding
- $currentLoan : stdClass|null = null
-
The current loan, or null if none
Return values
bool —isHoldableByCurrentLoan()
Check whether an item is holdable based on any current loan
protected
isHoldableByCurrentLoan(stdClass $currentLoan) : bool
Parameters
- $currentLoan : stdClass
-
The current loan
Return values
bool —isHoldableLocation()
Check item location against list of configured locations where holds should be offered
protected
isHoldableLocation(string $locationName) : bool
Parameters
- $locationName : string
-
locationName from getHolding
Return values
bool —loadProxyUserData()
Support method for getProxiedUsers() and getProxyingUsers() to load proxy user data.
protected
loadProxyUserData(array<string|int, mixed> $patron, string $lookupField, string $displayField) : array<string|int, mixed>
This requires the FOLIO user configured in Folio.ini to have the permission: proxiesfor.collection.get
Parameters
- $patron : array<string|int, mixed>
-
The patron array with username and password
- $lookupField : string
-
Field to use for looking up matching users
- $displayField : string
-
Field in response to use for displaying user names
Return values
array<string|int, mixed> —log()
Send a message to the logger.
protected
log(string $level, string $message[, array<string|int, mixed> $context = [] ][, bool $prependClass = false ]) : void
Parameters
- $level : string
-
Log level
- $message : string
-
Log message
- $context : array<string|int, mixed> = []
-
Log context
- $prependClass : bool = false
-
Prepend class name to message?
Return values
void —logError()
Log an error message.
protected
logError(string $msg[, array<string|int, mixed> $context = [] ][, bool $prependClass = true ]) : void
Parameters
- $msg : string
-
Log message
- $context : array<string|int, mixed> = []
-
Log context
- $prependClass : bool = true
-
Prepend class name to message?
Return values
void —logWarning()
Log a warning message.
protected
logWarning(string $msg[, array<string|int, mixed> $context = [] ][, bool $prependClass = true ]) : void
Parameters
- $msg : string
-
Log message
- $context : array<string|int, mixed> = []
-
Log context
- $prependClass : bool = true
-
Prepend class name to message?
Return values
void —patronLoginWithOkapi()
Support method for patronLogin(): authenticate the patron with an Okapi login attempt. Returns a CQL query for retrieving more information about the authenticated user.
protected
patronLoginWithOkapi(string $username, string $password) : string
Parameters
- $username : string
-
The patron username
- $password : string
-
The patron password
Return values
string —performHoldRequest()
Support method for placeHold(): send the request and process the response.
protected
performHoldRequest(array<string|int, mixed> $requestBody) : array<string|int, mixed>
Parameters
- $requestBody : array<string|int, mixed>
-
Request body
Tags
Return values
array<string|int, mixed> —performOkapiUsernamePasswordAuthentication()
Support method to perform a username/password login to Okapi.
protected
performOkapiUsernamePasswordAuthentication(string $username, string $password) : Response
Parameters
- $username : string
-
The patron username
- $password : string
-
The patron password
Return values
Response —putCachedData()
Helper function for storing cached data.
protected
putCachedData(string $key, mixed $entry[, int $lifetime = null ]) : void
Data is cached for up to $this->cacheLifetime seconds.
Parameters
- $key : string
-
Cache entry key
- $entry : mixed
-
Entry to be cached
- $lifetime : int = null
-
Optional lifetime for the entry in seconds
Return values
void —removeCachedData()
Helper function for removing cached data.
protected
removeCachedData(string $key) : void
Parameters
- $key : string
-
Cache entry key
Return values
void —renewTenantToken()
Login and receive a new token
protected
renewTenantToken() : void
Return values
void —sanitizeTranslationKey()
Make sure there are not any illegal characters in the translation key that might prevent successful lookup in language files.
protected
sanitizeTranslationKey(string $key) : string
Parameters
- $key : string
-
Key to sanitize
Return values
string —Sanitized key
shouldRetryAfterUnexpectedStatusCode()
Support method for makeRequest to process an unexpected status code. Can return true to trigger a retry of the API call or false to throw an exception.
protected
shouldRetryAfterUnexpectedStatusCode(Response $response, int $attemptNumber) : bool
Parameters
- $response : Response
-
HTTP response
- $attemptNumber : int
-
Counter to keep track of attempts (starts at 1 for the first attempt)
Return values
bool —sortHoldings()
Given a holdings array and a sort field, sort the array.
protected
sortHoldings(array<string|int, mixed> $holdings, string $sortField) : array<string|int, mixed>
Parameters
- $holdings : array<string|int, mixed>
-
Holdings to sort
- $sortField : string
-
Sort field
Return values
array<string|int, mixed> —throwAsIlsException()
Rethrow the provided exception as an ILS exception.
protected
throwAsIlsException(Throwable $exception[, string $msg = null ]) : never
Parameters
- $exception : Throwable
-
Exception to rethrow
- $msg : string = null
-
Override exception message (optional)
Tags
Return values
never —translateString()
Get translation for a string
protected
translateString(string $rawStr[, array<string|int, mixed> $tokens = [] ][, string $default = null ][, string $domain = 'default' ][, bool $useIcuFormatter = false ]) : string
Parameters
- $rawStr : string
-
String to translate
- $tokens : array<string|int, mixed> = []
-
Tokens to inject into the translated string
- $default : string = null
-
Default value to use if no translation is found (null for no default).
- $domain : string = 'default'
-
Text domain (omit for default)
- $useIcuFormatter : bool = false
-
Should we use an ICU message formatter instead of the default behavior?
Return values
string —useLegacyAuthentication()
Should we use the legacy authentication mechanism?
protected
useLegacyAuthentication() : bool
Return values
bool —userObjectToNameString()
Given a user object from the FOLIO API, return a name string.
protected
userObjectToNameString(object $user) : string
Parameters
- $user : object
-
User object