-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #15 from madmatt/pulls/add-linting-and-codecov
- Loading branch information
Showing
30 changed files
with
725 additions
and
889 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,5 @@ | ||
| /.artifacts | ||
| /.idea | ||
| /.phpunit.result.cache | ||
| /composer.lock | ||
| /vendor | ||
| .phpunit.result.cache | ||
| *.lock |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14,124 +14,52 @@ The WSDL file gives an overview of the values that can be provided, these will v | |
| * [Online WSDL viewer](http://www.id3globalsupport.com/Website/content/Web-Service/WSDL%20Page/WSDL%20HTML/ID3%20Global%20WSDL-%20Live.xhtml) | ||
| * [Sample code per country](http://www.id3globalsupport.com/Website/Sample-Code.html) | ||
|
|
||
| *Note:* The code below is entirely subject to change. It is primarily focused at the moment around the `AuthenticateSP` method of the ID3global API, and specifically on New Zealand (Aotearoa), however it should be generic enough to easily support other countries. | ||
| Please see the [Full Code Example](docs/full-code-example.md) that provides a complete overview of usage of this module. | ||
|
|
||
| ### Accessing the underlying ID3global request and response | ||
| Depending on your use case, you may need to access the underlying request sent to ID3global, or the response returned by the ID3global API. Typical use cases of this are for auditing purposes - to confirm that identity information hasn't changed since the last time an identity verification was performed for example. | ||
|
|
||
| In order to facilitate this, the `GlobalAuthenticationService` class has a number of helper methods to give you access to the underlying data. All of the below code assumes that you have already called the `->verifyIdentity()` method and that either you have a valid BandText, or you have caught the `IdentityVerificationFailureException` that may be thrown. | ||
|
|
||
| ```php | ||
| /** | ||
| * Namespaces: | ||
| * | ||
| * \ID3Global\Constants\Identity | ||
| * \ID3Global\Gateways\GlobalAuthenticationGateway | ||
| * \ID3Global\Services\GlobalAuthenticationService | ||
| * \ID3Global\Identity\Address\FreeFormatAddress | ||
| * \ID3Global\Identity\Address\FixedFormatAddress | ||
| * \ID3Global\Identity\ContactDetails | ||
| * \ID3Global\Identity\ContactDetails\LandTelephone | ||
| * \ID3Global\Identity\ContactDetails\MobileTelephone | ||
| * \ID3Global\Identity\ContactDetails\WorkTelephone | ||
| * \ID3Global\Identity\Documents\NZ\DrivingLicence | ||
| * \ID3Global\Identity\PersonalDetails | ||
| * | ||
| * \ID3Global\Identity\Addresses<\ID3Global\Identity\Address\FreeFormatAddress, \ID3Global\Identity\Address\FixedFormatAddress> | ||
| * - CurrentAddress | ||
| * - PreviousAddress[1-3] | ||
| * - HistoricAddresses<\ID3Global\Identity\Address\FreeFormatAddress, \ID3Global\Identity\Address\FixedFormatAddress> | ||
| * | ||
| * \ID3Global\Identity\Documents | ||
| * | ||
| * Not core for implementation | ||
| * \ID3Global\Identity\Aliases | ||
| * \ID3Global\Identity\AlternateName | ||
| * \ID3Global\Identity\BankingDetails\BankAccount | ||
| * \ID3Global\Identity\BankingDetails\CreditDebitCard | ||
| * \ID3Global\Identity\Documents\Address\UK\ElectricitySupplier | ||
| * \ID3Global\Identity\Documents\Identity\Global\InternationalPassport | ||
| * \ID3Global\Identity\Documents\Identity\Europe\EuropeanIdentityCard | ||
| * \ID3Global\Identity\Documents\Identity\AU\ShortPassport | ||
| * \ID3Global\Identity\Documents\Identity\AU\Medicare | ||
| * \ID3Global\Identity\Documents\Identity\BR\CPFNumber | ||
| * \ID3Global\Identity\Documents\Identity\CA\SocialInsuranceNumber | ||
| * \ID3Global\Identity\Documents\Identity\CN\ResidentIdentityCard | ||
| * \ID3Global\Identity\Documents\Identity\ES\TaxIDNumber | ||
| * \ID3Global\Identity\Documents\Identity\MX\TaxIdentificationNumber | ||
| * \ID3Global\Identity\Documents\Identity\UK\Passport | ||
| * \ID3Global\Identity\Documents\Identity\UK\DrivingLicence | ||
| * \ID3Global\Identity\Documents\Identity\UK\NationalInsuranceNumber | ||
| * \ID3Global\Identity\Documents\Identity\UK\DrivingLicence | ||
| * \ID3Global\Identity\Documents\Identity\US\DrivingLicence | ||
| * \ID3Global\Identity\Documents\Identity\US\SocialSecurity | ||
| * \ID3Global\Identity\Documents\Identity\US\IdentityCard | ||
| * \ID3Global\Identity\Employment | ||
| * \ID3Global\Identity\GlobalGeneric | ||
| * \ID3Global\Identity\Images | ||
| * \ID3Global\Identity\Location | ||
| * \ID3Global\Identity\PersonalDetails\BirthInfo | ||
| */ | ||
|
|
||
| $birthday = DateTime::createFromFormat('Y-m-d', '1922-08-20'); | ||
| $personalDetails = new \ID3Global\Identity\PersonalDetails(); | ||
| $personalDetails | ||
| ->setTitle('Mr') | ||
| ->setForeName('Dworkin') | ||
| ->setMiddleName('John') | ||
| ->setSurname('Barimen') | ||
| ->setGender('male') | ||
| ->setDateOfBirth($birthday); | ||
|
|
||
| $currentAddress = new \ID3Global\Identity\Address\FreeFormatAddress(); | ||
| $currentAddress | ||
| ->setCountry('New Zealand') | ||
| ->setPostCode('90210') | ||
| // You can set up to 8 address lines if required using ->setAddressLine3(), ->setAddressLine8() etc. | ||
| ->setAddressLine1('Dungeon 1') | ||
| ->setAddressLine2('Courts of Amber'); | ||
|
|
||
| $addressContainer = new \ID3Global\Identity\Address\AddressContainer(); | ||
| $addressContainer->setCurrentAddress($currentAddress); | ||
|
|
||
| $phone = new \ID3Global\Identity\ContactDetails\PhoneNumber(); | ||
| $phone->setNumber(1234567890); | ||
|
|
||
| $contactDetails = new \ID3Global\Identity\ContactDetails(); | ||
| $contactDetails | ||
| ->setLandTelephone($phone) | ||
| ->setMobileTelephone($phone) | ||
| ->setWorkTelephone($phone) | ||
| ->setEmail('[email protected]'); | ||
|
|
||
| $internationalPassport = new \ID3Global\Identity\Documents\InternationalPassport(); | ||
| $documentContainer = new \ID3Global\Identity\Documents\DocumentContainer(); | ||
| $documentContainer->addIdentityDocument(new \ID3Global\Identity\Documents\NZ\DrivingLicence(), 'New Zealand'); | ||
|
|
||
| /** | ||
| * $result will be a string representing the 'BandText' as returned by the ID3global API. By default, this may be a word | ||
| * like 'PASS', 'REFER' or 'ALERT' but could also be any string value e.g. 'Name, Address and DOB Match'. The exact | ||
| * string returned is entirely dependent on how the profile is configured within ID3global, and can vary if you adjust | ||
| * the profile id and profile version. | ||
| * | ||
| * It is up to your implementation how these are handled. Note that generally there is only a single value that | ||
| * represents an identity that has passed the necessary verification, and multiple BandTexts that represent a failing | ||
| * identity. You **must** handle this in your own code, as the ID3Global API does not provide any kind of boolean value | ||
| * for whether a given identity passed identity verification or not. | ||
| * | ||
| * An exception is thrown if the web service fails or cannot be contacted. | ||
| */ | ||
| $validIdentityBandText = 'PASS'; // See note above about how this may differ for you | ||
|
|
||
| $identity = new \ID3Global\Identity\Identity(); | ||
| $identity | ||
| ->setPersonalDetails($personalDetails) | ||
| ->setAddresses($addressContainer) | ||
| ->setContactDetails($contactDetails) | ||
| ->setIdentityDocuments($documentContainer); | ||
|
|
||
| $gateway = new \ID3Global\Gateway\GlobalAuthenticationGateway('username', 'password'); | ||
| $id3Service = new \ID3Global\Service\GlobalAuthenticationService($gateway); | ||
| $result = $id3Service | ||
| ->setProfileId('Profile ID as provided by ID3global interface') | ||
| ->verifyIdentity($identity, 'Unique customer reference'); | ||
|
|
||
| if($result === $validIdentityBandText) { | ||
| // Identity is verified, continue processing | ||
| // Assumes $service is an instance of ID3Global\Service\GlobalAuthenticationService | ||
|
|
||
| // Return the last SOAP request made to the ID3global API as a string | ||
| $lastRawRequest = $service->getLastRawRequest(); | ||
|
|
||
| // Returns the SoapClient interpreted response from the API (this will be an object of type \stdClass, or null if the SOAP request failed entirely | ||
| // For example you can access the BandText of a valid response with $lastResponse->AuthenticateSPResult->BandText | ||
| $lastResponse = $service->getLastVerifyIdentityResponse(); | ||
|
|
||
| // Access the underlying SoapClient object to perform more detailed debugging | ||
| $gateway = $service->getGateway(); // Returns a ID3Global\Gateway\GlobalAuthenticationGateway object | ||
| $soapClient = $gateway->getSoapClient(); // Returns a ID3Global\Gateway\SoapClient\ID3GlobalSoapClient object | ||
|
|
||
| // You can then do anything you'd normally do on SoapClient, such as: | ||
| $lastRawRequestHeaders = $soapClient->__getLastRequestHeaders(); // Returns an array of the headers sent to the API | ||
| $lastRawResponse = $soapClient->__getLastResponse(); // Returns the last response returned by the API | ||
| ``` | ||
|
|
||
| ### Debugging identity verification failures | ||
| In certain circumstances, generally when the ID3Global API produces unexpected results, you may get an `IdentityVerificationFailureException` returned to you. This can happen in a number of scenarios, such as required fields being missing from the request, or data being in an invalid format. | ||
|
|
||
| You should also wrap your `->verifyIdentity()` calls within a try/catch to prevent users from seeing these exceptions. | ||
|
|
||
| By default, this library does not expose information in the exception message that would leak personally identifiable information, however this can be enabled if you are confident that the exception is properly handled (e.g. is being forwarded to a GDPR-compliant logging service). Sometimes this level of detail is necessary to determine why the API request failed. | ||
|
|
||
| You can enable logging of this information via the exception message with the following configuration: | ||
|
|
||
| ```php | ||
| $service = new ID3Global\Service\GlobalAuthenticationService; | ||
|
|
||
| // Must be set before calling ->verifyIdentity() | ||
| $service->setVerboseExceptionHandling(true); | ||
|
|
||
| // Either way, regardless of whether or not you enable verbose exception handling, IdentityVerificationFailureException will still contain the response | ||
| try { | ||
| $service->verifyIdentity($identity, 'customer reference'); | ||
| } catch (IdentityVerificationFailureException $e) { | ||
| /** @var stdClass $response */ | ||
| $response = $e->getResponse(); | ||
| } | ||
| ``` | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| # id3global-service | ||
|
|
||
| ## Key classes | ||
|
|
||
| **Core services:** | ||
| * `ID3Global\Service\GlobalAuthenticationService`: The core service class used to request identity verification | ||
| * `ID3Global\Gateway\GlobalAuthenticationGateway`: The internal gateway class that communicates (via SOAP) with ID3global | ||
|
|
||
| **Identity information:** | ||
| * `ID3Global\Identity\Identity`: The base class for a single person's identity | ||
| * `ID3Global\Identity\PersonalDetails`: A class to capture core identity information (name, date of birth etc) | ||
| * `ID3Global\Identity\ContactDetails\PhoneNumber`: Include a single phone number (can be used for landline, mobile etc) | ||
|
|
||
| **Address specification:** | ||
| * `ID3Global\Identity\Address\FreeFormatAddress`: A 'free-form' address where individual address fields aren't specified | ||
| * `ID3Global\Identity\Address\FixedFormatAddress`: A fixed address format (e.g. fields for street, city, subcity etc) | ||
|
|
||
| **Additional identity documents:** | ||
| * `ID3Global\Identity\Documents\DocumentContainer`: Class that contains all below documents | ||
| * `ID3Global\Identity\Documents\InternationalPassport`: Contains details about a passport | ||
| * `ID3Global\Identity\Documents\NZ\DrivingLicence`: Contains details about a New Zealand drivers licence | ||
|
|
||
| ## Full code example | ||
|
|
||
| Below is a complete example of how to utilise this module, configuring personal details, a single address, multiple phone numbers and a passport. | ||
|
|
||
| Once the identity is created, we create and submit it to the `GlobalAuthenticationService`. | ||
|
|
||
| In the below example, we enable the 'pilot' site, which is the ID3global test environment. Leave this line out to query production (this will incur costs). | ||
|
|
||
| Finally, please review the comment below regarding the value of `$validIdentityBandText` - it's critically important that this is correct. | ||
|
|
||
| ```php | ||
| $birthday = DateTime::createFromFormat('Y-m-d', '1922-08-20'); | ||
| $personalDetails = new \ID3Global\Identity\PersonalDetails(); | ||
| $personalDetails | ||
| ->setTitle('Mr') | ||
| ->setForeName('Dworkin') | ||
| ->setMiddleName('John') | ||
| ->setSurname('Barimen') | ||
| ->setGender('male') | ||
| ->setDateOfBirth($birthday); | ||
|
|
||
| $currentAddress = new \ID3Global\Identity\Address\FreeFormatAddress(); | ||
| $currentAddress | ||
| ->setCountry('New Zealand') | ||
| ->setPostCode('90210') | ||
| // You can set up to 8 address lines if required using ->setAddressLine3(), ->setAddressLine8() etc. | ||
| ->setAddressLine1('Dungeon 1') | ||
| ->setAddressLine2('Courts of Amber'); | ||
|
|
||
| $addressContainer = new \ID3Global\Identity\Address\AddressContainer(); | ||
| $addressContainer->setCurrentAddress($currentAddress); | ||
|
|
||
| $phone = new \ID3Global\Identity\ContactDetails\PhoneNumber(); | ||
| $phone->setNumber(1234567890); | ||
|
|
||
| $contactDetails = new \ID3Global\Identity\ContactDetails(); | ||
| $contactDetails | ||
| ->setLandTelephone($phone) | ||
| ->setMobileTelephone($phone) | ||
| ->setWorkTelephone($phone) | ||
| ->setEmail('[email protected]'); | ||
|
|
||
| $internationalPassport = new \ID3Global\Identity\Documents\InternationalPassport(); | ||
| $documentContainer = new \ID3Global\Identity\Documents\DocumentContainer(); | ||
| $documentContainer->addIdentityDocument(new \ID3Global\Identity\Documents\NZ\DrivingLicence(), 'New Zealand'); | ||
|
|
||
| /** | ||
| * $result will be a string representing the 'BandText' as returned by the ID3global API. By default, this may be a word | ||
| * like 'PASS', 'REFER' or 'ALERT' but could also be any string value e.g. 'Name, Address and DOB Match'. The exact | ||
| * string returned is entirely dependent on how the profile is configured within ID3global, and can vary if you adjust | ||
| * the profile id and profile version. | ||
| * | ||
| * It is up to your implementation how these are handled. Note that generally there is only a single value that | ||
| * represents an identity that has passed the necessary verification, and multiple BandTexts that represent a failing | ||
| * identity. You **must** handle this in your own code, as the ID3Global API does not provide any kind of boolean value | ||
| * for whether a given identity passed identity verification or not. | ||
| * | ||
| * An exception is thrown if the web service fails or cannot be contacted. | ||
| */ | ||
| $validIdentityBandText = 'PASS'; // See note above about how this may differ for you | ||
|
|
||
| $identity = new \ID3Global\Identity\Identity(); | ||
| $identity | ||
| ->setPersonalDetails($personalDetails) | ||
| ->setAddresses($addressContainer) | ||
| ->setContactDetails($contactDetails) | ||
| ->setIdentityDocuments($documentContainer); | ||
|
|
||
| $gateway = new \ID3Global\Gateway\GlobalAuthenticationGateway('username', 'password'); | ||
| $id3Service = new \ID3Global\Service\GlobalAuthenticationService($gateway); | ||
| $result = $id3Service | ||
| ->setProfileId('Profile ID as provided by ID3global interface') | ||
| ->setProfileVersion(0) | ||
| ->setPilotSiteEnabled(true) | ||
| ->verifyIdentity($identity, 'Unique customer reference'); | ||
|
|
||
| if($result === $validIdentityBandText) { | ||
| // Identity is verified, continue processing | ||
| } | ||
| ``` |
Oops, something went wrong.