PHP Sample and API documentation

PHP Sample / PHP API using SignWare B-API

Signware includes a sample php package that displays capabilities of SignWare B-API API's.
The PHP sample is located in the b-api\samples\php folder. It uses php to build the desired web contents.

The sample requires PHP Version 5.2.6 or newer. The sample will only run within a Windows PHP runtime environment, it uses the PHP COM extension to access SignWare (the PHP COM module is only available for Windows).

Installation and configuration is covered in Installation and configuration Instructions.

Note:

The PHP implementation has sample status, it may be removed in future versions of SignWare. This module is distributed in the hope that it will be useful but without any warranty or support.

Short Description of the PHP sample

The file index.php is the main entry point, which mainly offers links to the subfunctions 'Query Plugin version', 'Capture a signature', 'Query tablet information' and 'Capture an Image'. Signature capture and Image Capture are both implemented as a 'simple' (single page) and as a 'complex' (multiple page) demonstration.

Each function sends a response to the browser plugins, the response page is built in the *_query.php files. The *_query.php files direct the plugin result to the according *_result files, which finally return a result summary.

The SignWare abstraction layer in the provided PHP samples is found in these two files:

• signware_xapi.php implements PHP classes SPCompare, SPImage, SPFlatFile, SPReference, SPSignature, SPSignWare, SPTablet, SPTicket and SPWeightedFrames, which are PHP equivalents of the SignWare COM objects; the current implementation is limited to the functionality as required in this context.
• signware_bapi.php implements PHP PlCoordinate, PlAction, PlFont, PlTablet, PlButton, PlText, PlTextEntry, PlImage, PlSlider, PlComboBox, PlComboItem, PadEntryDialog, PadEntryOptions, ScannerSetting, ScannerWindow, ScannerDialog, ScannerMessage, ScannerMessages, PlIdleTimeout, ServiceAccess, and ScannerEntryOptions which are PHP equivalents of the corresponding elements in PadEntryOptions.dtd. The class CapPlugin builds HTML requests to call the Plugins with the appropriate functions and parameters.
  Class PluginParameters is a parameter container.

Both files throw exceptions if an error occurs, e. g. incomplete SignWare installation etc. See the *_query.php and *_result.php files on how to use the classes implemented in signware_bapi.php and signware_xapi.php files.

Documentation for the PHP abstraction classes is accessible SignWare PHP-API.

Please note that parameter names and HTML tags are case sensitive!

Note:

PHP has limited builtin COM support, e. g. PHP cannot pass parameters of type SAFEARRAY(byte). The sample uses the base64 en- and decoded equivalents to exchange strings with SPFlatFile. The same applies to unsigned long variables, the sample uses the builtin time() function rather than the SignWare equivalent SPSignWareGetCurrentTime.

SignWare PHP-API

The Win32 Version of the SDK is also accessible from a PHP environment.
The implemented SignWare core objects include:

• SPCompare SignWare compare object
• SPImage SignWare image object
• SPFlatFile SignWare serialization object
• SPReference SignWare (dynamic) reference object
• SPSignature SignWare (dynamic) signature object
• SPSignWare SignWare base object
• SPTablet SignWare tablet object
• SPTicket SignWare license ticket object
• SPWeightedFrames SignWare weighted frames object

Please include "signware_xapi.php" in your PHP scripts that access the above classes.

The PHP wrappers do not implement the entire functionality of SignWare core objects but rather implement the subset which is typically required to access SignWare within a web application.

The implemented PadPlugin XML objects include:

• PlCoordinate Size and location of a GUI element
• PlAction Action descriptor of an element
• PlFont Size, Face and style of a PlText PlTextEntry or PlButton element
• PlTablet Tablet flags within a PadEntryDialog
• PlButton Button representation
• PlText Text representation
• PlTextEntry Text entry representation
• PlImage Image representation
• PlDocument Document representation
• PlSlider Slider representation
• PlComboBox ComboBox representation
• PlComboItem ComboBox items
• PlIdleTimeout Idle timeout after pad inactivity
• PadEntryDialog Pad entry page representation
• PadEntryOptions root element for a multi-page Pad entry dialog
• ScannerSetting Container to pass predefined scanner settings
• ScannerWindow Scanner window representation
• ScannerDialog Scanner dialog representation
• ScannerMessage Scanner message translation
• ScannerMessages predefined english / german translations of scanner messages
• ServiceAccess, Container to discribe access to a cleaning web service
• ScannerEntryOptions root element for a multi-page scanner capture dialog

Please include "signware_bapi.php" in your PHP scripts that access the above classes.

Above classes generate the XML string as described in the document type declaration in PadEntryOptions.dtd.

SignWare PHP-API Error handling and Debugging

The core PHP classes throw an exception if an error occurs. The exception text should help localising the problem.

The samples catch the exception and write the exception text to the default logging facility of PHP via a trace handler.

The trace handler is included in the file helpers.php. The method is called trace. the trace handler will log into the default PHP logging facilities, which typically is the Apache errorlogs.

The trace handler uses a global variable $iTraceLevel to determine which messages to pass to the logging facility.

The SignWare B-API browser plugin is invoked as a HTML object, the PHP-API creates and passes an options string which is typically base-64 encoded.
The raw encoding string will be dumped (for debugging purposes) in a separate browser window if the defined variable 'DUMP_OPTIONSSTRING' in helpers.php is set to TRUE.