About

This is a wrapper class for the sip2.class.php from google code. So far only wrapping the calls authenticate a patron and extract various bits of patron information from the patron status and patron information calls.

Documentation can be generated by running phpDocumentor with included phpdoc.dist.xml file.

More about SIP2

• Standard Interchange Protocol 2, Standard: http://mws9.3m.com/mws/mediawebserver.dyn?6666660Zjcf6lVs6EVs66S0LeCOrrrrQ-

Most recent changes

• 2022-05-06:
  • Added stream_socket_shutdown() to Sip2->disconnect(), because otherwise Gossip got stuck with a permanent high CPU usage under RHEL7.
• 2022-01-26:
  • Modified getPatronIsValid() to allow for missing CQ (valid Password) field. Reason: Gossip's ILL Deposit feature does not return CQ.
• 2016-03-19:
  • Added support for encrypted connections using TLS
  • Added support for Gossip

Usage

1. Basic

require_once 'Sip2Wrapper.php';

$sip2 = new Sip2Wrapper(
    array(
        'hostname' => $hostname,
        'port' => 6001,
        'withCrc' => false,
        'location' => $location,
        'institutionId' => $institutionId
    )
);

$sip2->login($user, $pass);

if ($sip2->startPatronSession($patron, $patronpwd)) {
    var_dump($sip2->getPatronScreenMessages());
}

All of the methods that are prefixed by the word "get" can also be used as properties, and all protected properties have appropriately named getter methods so that you can effectively have read-only access via the magic getter. For instance,

while you can't do this:

$sip2 = $mySip2Wrapper->_sip2;

You can do this:

$sip2 = $mySip2Wrapper->sip2;

The other get methods can be called in this way as well and can be used as virtual properties.

For instance, this works even though there is no property named patronStatus:

$patronStatus = $sip2->patronStatus;

Behind the scenes it calls the getPatronStatus() method and returns the value.

2. Using TLS (encrypted communication)

If the server supports encryption, you can connect accordingly. Be aware that the following example only shows a likely use case for creating the object. The outcommented options (these are all PHP provides) might be important for you.

$sip2 = new Sip2Wrapper(
    array(
        // As usually
        'hostname' => 'mySipServer.somwhere.net',
        'port' => 1290,
        'withCrc' => true,
        'location' => 'Reading Room 1',
        'institutionId' => 'My Library',
        'language' => '001',

        // TLS options
        'socket_tls_enable' => true,
        'socket_timeout'    => 10,
        'socket_tls_options' => array(
            //'peer_name'               => 'mySipServer.somwhere.net',                      // since PHP 5.6, If this value is not set, then the name is guessed based on the hostname used when opening the stream
            'verify_peer'               => true,
            'verify_peer_name'          => true,                                            // since PHP 5.6
            'allow_self_signed'         => true,
            //'cafile'                  => 'path/to/cafile/cacert.pem',
            //'capath'                  => 'path/to/ca_certificates/directory',
            //'local_cert'              => 'path/to/local_cert/cert_and_privateKey.pem',
            //'local_pk'                => 'path/to/local_certs_and_keys/',
            //'passphrase'              => 'My local_cert password',
            //'CN_match'                => $this->hostname,                                 // until PHP 5.6: use peer_name instead
            //'verify_depth'            => Defaults to no verification,
            'ciphers'                   => 'HIGH:!SSLv2:!SSLv3',
            'capture_peer_cert'         => true,
            'capture_peer_cert_chain'   => true,
            //'SNI_enabled'             => true,                                            // since PHP 5.3.2
            //'SNI_server_name'         => 'NAME',                                          // until PHP 5.6: use peer_name instead
            'disable_compression'       => true,                                            // since PHP 5.4.13
            //'peer_fingerprint'          => 'SOME_HASH_STRING or an ARRAY'                 // since PHP 5.6
        ),

        'debug' => false
    )
);

3. Using Gossip

3.1 Creating Gossip object

It's nearly the same as for Sip2. Just add 'Gossip' to create the object

$gossip = new Sip2Wrapper(
    array(
        // As usually
        'hostname' => 'mySipServer.somwhere.net',
        'port' => 1290,

        ... more options ...

        'debug' => false
    ), true, 'Gossip'
);

3.2 About Gossip

Gossip is short for "Good Old Server for Standard Interchange Protocol". Gossip is an SIP2 server implementation (Java) with an extension for enhanced payment options. It's possible to pay

• a single outstanding position; "subtotal-payment"
• an amount being below the total fees (but that sums up to complete positions being paid); "subtotal-payment"
• an amount being below the total fees (but that might only pay one or more positions partially); "subtotal-payment + partial-fee-payment"

SIP2 already provides everything for the payment part with positions. Example

$transid = time();
$ammount    = '0.10';    // this is what you get doing a msgPatronInformation(feeItems) - FA
$feeId      = '1059648'; // this is what you get doing a msgPatronInformation(feeItems) - FB
$msg = $gossip->msgFeePaid('01', '00', $ammount, 'EUR', $feeId, $transid);
print_r($gossip->parseFeePaidResponse( $gossip->get_message($msg) ));

Fee positions can be fetched using a Y a position 7 (counting from 0 as in the standard it really is the 6th) in a Patron Information request (code 63). It returns these additional fields:

FIELD    USED IN (Responses) Description
FA       64, 38              Ammount of for fee position (alway dot as decimal seperator)
FB       64, 38              ItemId of media for fee position
FC       64, 38              Date when fee was generated (alway "dd.MM.yyyy")
FD       64, 38              Description/title of fee position
FE       64, 38              Cost type of fee position
FF       64, 38              Description of cost type of fee position
FG       38                  Paid ammount for fee position

Notes:

• Sadly no official documentation for Gossip is available online. You can only contact the developer via https://www.gbv.de/Verbundzentrale/serviceangebote/gossip-service-der-vzg
• As of 2019-07 Gossip 2.1 can provide the borrower type in field FU and the borrower type description in field FV. This functionality is enabled by default but may be disabled by setting. Also a field FI holds a message if patrons are required to return books before paying the overdue fees (like FIYou have to return the book before paying the fee).

Todo

• Finish implementing the methods relating to checking out books etc.
• Add payment stuff to wrapper