VuFind API Documentation

Folio extends AbstractAPI
in package

ILS

Drivers

implements HttpServiceAwareInterface, TranslatorAwareInterface Uses HttpServiceAwareTrait, TranslatorAwareTrait, LoggerAwareTrait, CacheTrait

FOLIO REST API driver

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).

$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
$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
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() : void: Check if our token is still valid
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 identifer, 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.
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 OKAPI by calling /circulation/loans with the item->id, 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.
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.
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 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.
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.

$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
     = []

$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

__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)

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

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)

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)

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

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.

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.

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

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

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

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 ]) : 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.)

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).

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


    protected
                    checkTenantToken() : void

Method taken from Stripes JS (loginServices.js:validateUser)

Return values

void —

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

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 identifer, 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' ]) : 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

Return values

array<string|int, mixed> —

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 OKAPI by calling /circulation/loans with the item->id, adjusting the timezone and formatting in universal time with or without due time


    protected
                    getDueDate(string $itemId, bool $showTime) : string

Parameters

$itemId : string: ID for the item to query
$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> —

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> = []: CQL query
$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> —

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 item location against list of configured locations where holds should be offered


    protected
                    isHoldable(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

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()


    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

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)

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

Return values

string —

Folio extends AbstractAPI in package ILS Drivers implements HttpServiceAwareInterface, TranslatorAwareInterface Uses HttpServiceAwareTrait, TranslatorAwareTrait, LoggerAwareTrait, CacheTrait

Tags

Interfaces, Classes, Traits and Enums

Table of Contents

Properties

$cache

$cacheLifetime

$config

$dateConverter

$defaultAvailabilityStatuses

$defaultInTransitStatuses

$sessionCache

$sessionFactory

$tenant

$token

$translator

Methods

__construct()

Parameters

Return values

cancelHolds()

Parameters

Return values

findReserves()

Parameters

Return values

getCancelHoldDetails()

Parameters

Tags

Return values

getConfig()

Parameters

Tags

Return values

getCourses()

Return values

getDepartments()

Return values

getFunds()

Return values

Folio extends AbstractAPI
in package

ILS

Drivers

implements HttpServiceAwareInterface, TranslatorAwareInterface Uses HttpServiceAwareTrait, TranslatorAwareTrait, LoggerAwareTrait, CacheTrait