VuFind API Documentation

HorizonXMLAPI extends Horizon
in package

ILS

Drivers

implements HttpServiceAwareInterface Uses HttpServiceAwareTrait

Horizon ILS Driver (w/ XML API support)

Interfaces, Classes, Traits and Enums

HttpServiceAwareInterface

$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: Defaut 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.

$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

Defaut 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

__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

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)

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.

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.

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)

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

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

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

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

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.

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.

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

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

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.

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

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

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 witk keys indicating the a 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

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


    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)

Return values

never —

HorizonXMLAPI extends Horizon in package ILS Drivers implements HttpServiceAwareInterface Uses HttpServiceAwareTrait

Tags

Interfaces, Classes, Traits and Enums

Table of Contents

Properties

$config

$dateFormat

$db

$wsDateFormat

$wsDefaultPickUpLocation

$wsPickUpLocations

$wsProfile

$wsURL

Methods

__construct()

Parameters

Return values

cancelHolds()

Parameters

Return values

checkRequestIsValid()

Parameters

Return values

getCancelHoldDetails()

Parameters

Tags

Return values

getConfig()

Parameters

Tags

Return values

getDefaultPickUpLocation()

Parameters

Tags

Return values

getFunds()

Tags

Return values

getHolding()

Parameters

HorizonXMLAPI extends Horizon
in package

ILS

Drivers

implements HttpServiceAwareInterface Uses HttpServiceAwareTrait