HorizonXMLAPI
extends Horizon
in package
implements
HttpServiceAwareInterface
Uses
HttpServiceAwareTrait
Horizon ILS Driver (w/ XML API support)
Tags
Interfaces, Classes, Traits and Enums
- HttpServiceAwareInterface
Table of Contents
- $config : array<string|int, mixed>
- Driver configuration
- $dateFormat : Converter
- Date converter object
- $db : PDO
- Database connection
- $wsDateFormat : string
- Date format used by API
- $wsDefaultPickUpLocation : string
- Default pickup location for holds
- $wsPickUpLocations : array<string|int, mixed>
- Available pickup locations for holds
- $wsProfile : string
- API profile
- $wsURL : string
- API URL
- __construct() : mixed
- Constructor
- cancelHolds() : array<string|int, mixed>
- Cancel Holds
- checkRequestIsValid() : bool
- Check if Request is Valid
- getCancelHoldDetails() : string
- Get Cancel Hold Details
- getConfig() : array<string|int, mixed>
- Public Function which retrieves renew, hold and cancel settings from the driver ini file.
- getDefaultPickUpLocation() : string
- Get Default Pick Up Location
- getFunds() : array<string|int, mixed>
- Get Funds
- getHolding() : array<string|int, mixed>
- Get Holding
- getMyFines() : mixed
- Get Patron Fines
- getMyHolds() : array<string|int, mixed>
- Get Patron Holds
- getMyProfile() : array<string|int, mixed>
- Get Patron Profile
- getMyTransactions() : array<string|int, mixed>
- Get Patron Transactions
- getNewItems() : array<string|int, mixed>
- Get New Items
- getPickUpLocations() : array<string|int, mixed>
- Get Pick Up Locations
- getPurchaseHistory() : array<string|int, mixed>
- Get Purchase History
- getRenewDetails() : string
- Get Renew Details
- getStatus() : mixed
- Get Status
- getStatuses() : array<string|int, mixed>
- Get Statuses
- getSuppressedRecords() : array<string|int, mixed>
- Get suppressed records.
- init() : void
- Initialize the driver.
- patronLogin() : mixed
- Patron Login
- placeHold() : mixed
- Place Hold
- renewMyItems() : array<string|int, mixed>
- Renew My Items
- setConfig() : void
- Set configuration.
- buildSqlFromArray() : array<string|int, mixed>
- Protected support method for building sql strings.
- cancelRequest() : array<string|int, mixed>
- Cancel Request
- checkHzVersion() : bool
- Check Horizon Version
- debug() : void
- Log a debug message.
- determineRenewability() : array<string|int, mixed>
- Determine Renewability
- getHoldingSQL() : array<string|int, mixed>
- Protected support method for getHolding.
- getHoldsSQL() : array<string|int, mixed>
- Protected support method for getMyHolds.
- getItems() : obj
- Get Items
- getSession() : mixed
- Get Session
- getStatusesSQL() : array<string|int, mixed>
- Protected support method for getStatus.
- getTransactionSQL() : array<string|int, mixed>
- Protected support method for getMyTransactions.
- log() : void
- Send a message to the logger.
- logError() : void
- Log an error message.
- logWarning() : void
- Log a warning message.
- makeRequest() : obj
- Make Request
- parseStatus() : array<string|int, mixed>
- Protected support method determine availability, reserve and duedate values based on item status. Used by getHolding, getStatus and getStatuses.
- placeRequest() : array<string|int, mixed>
- Place Request
- processHoldingRow() : array<string|int, mixed>
- Protected support method for getHolding.
- processHoldsRow() : array<string|int, mixed>
- Protected support method for getMyHolds.
- processRenewals() : array<string|int, mixed>
- Process Renewals
- processStatusRow() : array<string|int, mixed>
- Protected support method for getStatuses.
- processTransactionsRow() : array<string|int, mixed>
- Protected support method for getMyTransactions.
- registerUser() : bool
- Register User
- renewItems() : obj
- Renew Items
- throwAsIlsException() : never
- Rethrow the provided exception as an ILS exception.
Properties
$config
Driver configuration
protected
array<string|int, mixed>
$config
= []
$dateFormat
Date converter object
protected
Converter
$dateFormat
$db
Database connection
protected
PDO
$db
$wsDateFormat
Date format used by API
protected
string
$wsDateFormat
$wsDefaultPickUpLocation
Default pickup location for holds
protected
string
$wsDefaultPickUpLocation
$wsPickUpLocations
Available pickup locations for holds
protected
array<string|int, mixed>
$wsPickUpLocations
$wsProfile
API profile
protected
string
$wsProfile
$wsURL
API URL
protected
string
$wsURL
Methods
__construct()
Constructor
public
__construct(Converter $dateConverter) : mixed
Parameters
- $dateConverter : Converter
-
Date converter 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 $bibId, string $itemData, array<string|int, mixed> $patron) : bool
Determines if a user can place a hold or recall on a specific item
Parameters
- $bibId : string
-
An item's Bib ID
- $itemData : string
-
Array containing item id and hold level
- $patron : array<string|int, mixed>
-
Patron Array Data
Return values
bool —true if the request can be made, false if it cannot
getCancelHoldDetails()
Get Cancel Hold Details
public
getCancelHoldDetails(array<string|int, mixed> $holdDetails[, array<string|int, mixed> $patron = [] ]) : string
In order to cancel a hold, Voyager requires the patron details an item ID and a recall ID. This function returns the item id and recall id as a string separated by a pipe, which is then submitted as form data in Hold.php. This value is then extracted by the CancelHolds function.
Parameters
- $holdDetails : array<string|int, mixed>
-
A single hold array from getMyHolds
- $patron : array<string|int, mixed> = []
-
Patron information from patronLogin
Tags
Return values
string —Data for use in a form field
getConfig()
Public Function which 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.
getDefaultPickUpLocation()
Get Default Pick Up Location
public
getDefaultPickUpLocation([array<string|int, mixed> $patron = false ][, array<string|int, mixed> $holdDetails = null ]) : string
This is responsible for retrieving the pickup location for a logged in patron.
Parameters
- $patron : array<string|int, mixed> = false
-
Patron information returned by the patronLogin method.
- $holdDetails : array<string|int, mixed> = null
-
Optional array, only passed in when getting a list in the context of placing a hold; contains most of the same values passed to placeHold, minus the patron data. May be used to limit the pickup options or may be ignored.
Tags
Return values
string —The default pickup location for the patron.
getFunds()
Get Funds
public
getFunds() : array<string|int, mixed>
Return a list of funds which may be used to limit the getNewItems list.
Tags
Return values
array<string|int, mixed> —An associative array with key = fund ID, value = fund name.
getHolding()
Get Holding
public
getHolding(string $id[, array<string|int, mixed> $patron = null ][, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>
This is responsible for retrieving the holding information of a certain record.
Parameters
- $id : string
-
The record id to retrieve the holdings for
- $patron : array<string|int, mixed> = null
-
Patron data
- $options : array<string|int, mixed> = []
-
Extra options (not currently used)
Tags
Return values
array<string|int, mixed> —On success, an associative array with the following keys: id, availability (boolean), status, location, reserve, callnumber, duedate, number, barcode.
getMyFines()
Get Patron Fines
public
getMyFines(array<string|int, mixed> $patron) : mixed
This is responsible for retrieving all fines by a specific patron.
Parameters
- $patron : array<string|int, mixed>
-
The patron array from patronLogin
Tags
Return values
mixed —Array of the patron's fines on success.
getMyHolds()
Get Patron Holds
public
getMyHolds(array<string|int, mixed> $patron) : array<string|int, mixed>
This is responsible for retrieving all holds by a specific patron.
Parameters
- $patron : array<string|int, mixed>
-
The patron array from patronLogin
Tags
Return values
array<string|int, mixed> —Array of the patron's holds on success.
getMyProfile()
Get Patron Profile
public
getMyProfile(array<string|int, mixed> $patron) : array<string|int, mixed>
This is responsible for retrieving the profile for a specific patron.
Parameters
- $patron : array<string|int, mixed>
-
The patron array
Tags
Return values
array<string|int, mixed> —Array of the patron's profile data on success, throw ILSException if none found
getMyTransactions()
Get Patron Transactions
public
getMyTransactions(array<string|int, mixed> $patron) : array<string|int, mixed>
This is responsible for retrieving all transactions (i.e. checked out items) by a specific patron.
Parameters
- $patron : array<string|int, mixed>
-
The patron array from patronLogin
Tags
Return values
array<string|int, mixed> —Array of the patron's transactions on success.
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.
The logic in this function follows the pattern used for the "New Additions" functionality of the Horizon staff client. New Additions was delivered with Horizon 7.4 and requires setup. Follow instructions in the "Circulation Setup Guide". The minimum setup is to set the "Track First Availability" flag for each appropriate item status.
Parameters
- $page : int
-
Not implemented in this driver - Sybase does not have SQL query paging functionality.
- $limit : int
-
The maximum number of results to retrieve
- $daysOld : int
-
The maximum age of records to retrieve in days (max. 30)
- $fundId : int = null
-
Not implemented in this driver - The contributing library does not use acquisitions.
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> $holdDetails = null ]) : array<string|int, mixed>
This is responsible for getting a list of valid library locations for holds / recall retrieval
Parameters
- $patron : array<string|int, mixed>
-
Patron information returned by the patronLogin method.
- $holdDetails : 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
getPurchaseHistory()
Get Purchase History
public
getPurchaseHistory(string $id) : array<string|int, mixed>
This is responsible for retrieving the acquisitions history data for the specific record (usually recently received issues of a serial).
Parameters
- $id : 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 Renew Details
public
getRenewDetails(array<string|int, mixed> $checkOutDetails) : string
In order to renew an item, Voyager requires the patron details and an item id. This function returns the item id as a string which is then used as submitted form data in checkedOut.php. This value is then extracted by the RenewMyItems function.
Parameters
- $checkOutDetails : array<string|int, mixed>
-
An array of item data
Return values
string —Data for use in a form field
getStatus()
Get Status
public
getStatus(string $id) : mixed
This is responsible for retrieving the status information of a specific record. It is a proxy to getStatuses.
Parameters
- $id : string
-
The record id to retrieve the holdings for
Return values
mixed —On success, an associative array with the following keys: id, availability (boolean), status, location, reserve, and callnumber.
getStatuses()
Get Statuses
public
getStatuses(array<string|int, mixed> $idList) : array<string|int, mixed>
This is responsible for retrieving the status information for a collection of records.
Parameters
- $idList : array<string|int, mixed>
-
The array of record ids to retrieve the status for
Tags
Return values
array<string|int, mixed> —An array of getStatus() return values on success.
getSuppressedRecords()
Get suppressed records.
public
getSuppressedRecords() : array<string|int, mixed>
Get a list of Horizon bib numbers that have the staff-only flag set.
Return values
array<string|int, mixed> —ID numbers of suppressed records in the system.
init()
Initialize the driver.
public
init() : void
Validate configuration and perform all resource-intensive tasks needed to make the driver active.
Tags
Return values
void —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's password
Tags
Return values
mixed —Associative array of patron info on successful login, ILSException 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 or throws an exception on failure of support classes
Parameters
- $holdDetails : array<string|int, mixed>
-
An array of item and patron data
Tags
Return values
mixed —An array of data on the request including whether or not it was successful and a system message (if available)
renewMyItems()
Renew My Items
public
renewMyItems(array<string|int, mixed> $renewDetails) : array<string|int, mixed>
Function for attempting to renew a patron's items. The data in $renewDetails['details'] is determined by getRenewDetails().
Parameters
- $renewDetails : array<string|int, mixed>
-
An array of data required for renewing items including the Patron ID and an array of renewal IDS
Return values
array<string|int, mixed> —An array of renewal information keyed by item ID
setConfig()
Set configuration.
public
setConfig(array<string|int, mixed> $config) : void
Set the configuration for the driver.
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 —buildSqlFromArray()
Protected support method for building sql strings.
protected
buildSqlFromArray(array<string|int, mixed> $sql) : array<string|int, mixed>
Parameters
- $sql : array<string|int, mixed>
-
An array of keyed sql data
Return values
array<string|int, mixed> —An string query string
cancelRequest()
Cancel Request
protected
cancelRequest(string $session, array<string|int, mixed> $data) : array<string|int, mixed>
Submits a cancel request to the Horizon API and processes the result
Parameters
- $session : string
-
A valid Horizon session key
- $data : array<string|int, mixed>
-
An array of item data
Return values
array<string|int, mixed> —An array of cancel information keyed by item ID plus the number of successful cancels
checkHzVersion()
Check Horizon Version
protected
checkHzVersion(string $hzVersionRequired) : bool
Check the Horizon version found in the matham table to make sure it is at least the required version.
Parameters
- $hzVersionRequired : string
-
Minimum version required
Return values
bool —True or False the required version is the same or higher.
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 —determineRenewability()
Determine Renewability
protected
determineRenewability(string $requested) : array<string|int, mixed>
This is responsible for determining if an item is renewable
Parameters
- $requested : string
-
The number of times an item has been requested
Return values
array<string|int, mixed> —$renewData Array of the renewability status and associated message
getHoldingSQL()
Protected support method for getHolding.
protected
getHoldingSQL(array<string|int, mixed> $id) : array<string|int, mixed>
Parameters
- $id : array<string|int, mixed>
-
A Bibliographic id
Return values
array<string|int, mixed> —Keyed data for use in an sql query
getHoldsSQL()
Protected support method for getMyHolds.
protected
getHoldsSQL(array<string|int, mixed> $patron) : array<string|int, mixed>
Parameters
- $patron : array<string|int, mixed>
-
Patron data for use in an sql query
Return values
array<string|int, mixed> —Keyed data for use in an sql query
getItems()
Get Items
protected
getItems(string $session) : obj
Gets a list of items on loan
Parameters
- $session : string
-
A valid Horizon session key
Return values
obj —A Simple XML Object
getSession()
Get Session
protected
getSession() : mixed
Gets a Horizon session
Return values
mixed —A session string on success, boolean false on failure
getStatusesSQL()
Protected support method for getStatus.
protected
getStatusesSQL(array<string|int, mixed> $idList) : array<string|int, mixed>
Parameters
- $idList : array<string|int, mixed>
-
A list of Bibliographic id
Return values
array<string|int, mixed> —Keyed data for use in an sql query
getTransactionSQL()
Protected support method for getMyTransactions.
protected
getTransactionSQL(array<string|int, mixed> $patron) : array<string|int, mixed>
Parameters
- $patron : array<string|int, mixed>
-
Patron data for use in an sql query
Return values
array<string|int, mixed> —Keyed data for use in an sql query
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 —makeRequest()
Make Request
protected
makeRequest([array<string|int, mixed> $params = false ][, string $mode = 'GET' ]) : obj
Makes a request to the Horizon API
Parameters
- $params : array<string|int, mixed> = false
-
A keyed array of query data
- $mode : string = 'GET'
-
The http request method to use (Default of GET)
Return values
obj —A Simple XML Object loaded with the xml data returned by the API
parseStatus()
Protected support method determine availability, reserve and duedate values based on item status. Used by getHolding, getStatus and getStatuses.
protected
parseStatus(string $status) : array<string|int, mixed>
Parameters
- $status : string
-
Item status code
Return values
array<string|int, mixed> —placeRequest()
Place Request
protected
placeRequest(string $session, array<string|int, mixed> $requestDetails) : array<string|int, mixed>
Submits a hold request to the Horizon XML API and processes the result
Parameters
- $session : string
-
A valid Horizon session key
- $requestDetails : array<string|int, mixed>
-
An array of request details
Return values
array<string|int, mixed> —An array with keys indicating the success (boolean), status (string) and sysMessage (string) if available
processHoldingRow()
Protected support method for getHolding.
protected
processHoldingRow(string $id, array<string|int, mixed> $row, array<string|int, mixed> $patron) : array<string|int, mixed>
Parameters
- $id : string
-
Bib Id
- $row : array<string|int, mixed>
-
SQL Row Data
- $patron : array<string|int, mixed>
-
Patron Array
Return values
array<string|int, mixed> —Keyed data
processHoldsRow()
Protected support method for getMyHolds.
protected
processHoldsRow(array<string|int, mixed> $row) : array<string|int, mixed>
Parameters
- $row : array<string|int, mixed>
-
An sql row
Tags
Return values
array<string|int, mixed> —Keyed data
processRenewals()
Process Renewals
protected
processRenewals(array<string|int, mixed> $renewIDs, array<string|int, mixed> $origData, array<string|int, mixed> $renewData) : array<string|int, mixed>
This is responsible for processing renewals and is necessary as result of renew attempt is not returned
Parameters
- $renewIDs : array<string|int, mixed>
-
A list of the items being renewed
- $origData : array<string|int, mixed>
-
A Simple XML array of loan data before the renewal attempt
- $renewData : array<string|int, mixed>
-
A Simple XML array of loan data after the renewal attempt
Return values
array<string|int, mixed> —An Array specifying the results of each renewal attempt
processStatusRow()
Protected support method for getStatuses.
protected
processStatusRow(string $id, array<string|int, mixed> $row) : array<string|int, mixed>
Parameters
- $id : string
-
Bib Id
- $row : array<string|int, mixed>
-
SQL Row Data
Return values
array<string|int, mixed> —Keyed data
processTransactionsRow()
Protected support method for getMyTransactions.
protected
processTransactionsRow(array<string|int, mixed> $row) : array<string|int, mixed>
Parameters
- $row : array<string|int, mixed>
-
An array of keyed data
Return values
array<string|int, mixed> —Keyed data for display by template files
registerUser()
Register User
protected
registerUser(string $userBarcode, string $userPassword) : bool
Associates a user with a session
Parameters
- $userBarcode : string
-
A valid Horizon user barcode
- $userPassword : string
-
A valid Horizon user password (pin)
Return values
bool —true on success, false on failure
renewItems()
Renew Items
protected
renewItems(string $session, array<string|int, mixed> $items) : obj
Submits a renewal request to the Horizon API and returns the results
Parameters
- $session : string
-
A valid Horizon session key
- $items : array<string|int, mixed>
-
A list of items to be renewed
Return values
obj —A Simple XML Object
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)