PHP Client for Middleware NetID Web Services

Obtaining the Client

Composer

The recommended way to obtain this client is with Composer. The following minimal composer.json file will pull the client into your project:

{
	"repositories": [
		{
			"type": "vcs",
			"url": "git@bitbucket.uwmadison_doit/rpc-netid-php"
		}
	],
	"require": {
		"uwmadison_doit/rpc-netid-php": "1.*"
	}
}

Your public SSH key will need to be linked to your Bitbucket account. You can alternatively use HTTP and specify your Bitbucket username and password. The composer.json Schema - Repositories

Git

Users can clone this repository. The client library files are located in src/main/edu/wisc/doit.

Getting Started

Loading the Library

If you are using Composer, you simply need to include ./vendor/autoload.php once in your application. Any references to the client classes will be automatically imported at runtime.

Otherwise, you will need to include specific classes in the src/main/edu/wisc/doit directory of the git repository.

Client Authentication

The NetID web services is protected by IP restriction and client certificate authentication. Requesting a client certificate

You will need the client authentication certificate issued to you by Middleware and the corresponding private key. These should be combined, unencrypted, into a single PEM file. This client provides a helper function to do this.

use edu\wisc\doit\CertificateService;

CertificateService::createPem( 'path/to/certificate', 'path/to/key', 'path/to/save/pem' );

Initializing the client

In addition to the client certificate described above, you will need to provide paths to 2 files:

1. A PEM file that contains the public key of the certificate authority used to sign the webservice endpoint's certificate.
2. Either the URL or the path to a local copy of the WSDL file presented by the target endpoint environment.

IMPORTANT: This particular service is known not to version it's data model and API. It is a regular scenario that the test environment for this service presents a different WSDL contract than the production environment.

use edu\wisc\doit\RpcNetidClientSoap;
use edu\wisc\doit\RpcNetidClientSoapConfig;

$config = new RpcNetidClientSoapConfig(
	'/path/to/webservices.endpoint.wsdl',
	'/path/to/webservices.endpoint.certificate.authority.pem',
	'/path/to/pem' );

$client = RpcNetidClientSoap::create( $config );

Sample Call

use edu\wisc\doit\RpcNetidClientSoap;
use edu\wisc\doit\RpcNetidStructGetQuestionsRequest;
use edu\wisc\doit\RpcNetidStructGetQuestionsResponse;

$questions = $client->getQuestions( 'mynetid' );

Available calls you can make and their related documentation can be found in the RpcNetidClient interface.

API Documentation

Documentation for the client can be viewed by loading docs/index.html into your browser. You will need to run phpdoc at the root of the project in order to generate them, until they can be published for everyone. Installing phpdoc

Contributing

The rest of this README is for those wishing to contribute to the project.

This project uses the forking workflow. Please fork this project and submit pull requests to the blessed repository. It is expected that unit tests are created for new and updated functionality. Pull requests should be descriptive.

Development Requirements

1. phing

Developer Setup

Vagrant

A vagrant file has been created for your convenience. This will install a Vagrant development virutal box with all the necessary build tools. Simply run at the project root:

vagrant up

Building

At the root of the project, run the following command:

php phing.phar

This will retrieve dependencies and run PHPUnit.

Note: If you are not using Vagrant, you will need to obtain Phing. (I recommend downloading the Phar file to stay consistent with this documentation.)

Testing

PHPUnit tests are located in src/test. To run the tests, at the root of the project, enter:

php phpunit.phar

or:

php phing.phar test

Integration Testing

Integration with the MST NetID web service can be tested by running:

php phpunit.phar --configuration phpunit-it.xml

or:

php phing.phar integration-test

A valid client certificate is required to authenticate with Middleware's web service. Test data must be supplied in src/test/resources/integration-test-data.ini. See the class summary in src/test/integration-tests/RpcNetidClientSoapIT.php and the comments in src/test/resources/integration-test-data.SAMPLE.ini.

Release Management

To release a branch as a new version of the software:

php phing.phar release -Dversion=1.2.3 -Dbranch=myBranch

The branch property is optional and will default to master if not set.

See README-release.md for detailed information.