newsupernova/vendor/vertex/sdk

Vertex API Library

The Vertex API Library provides data models for storing information related to Vertex requests and responses, mappers for converting these data models to a format compatible with the PHP SOAP extension, and services for calling the Vertex API endpoints.

Public API

The Vertex API Library provides backwards-compatibility in line with Magento 2 versioning constraints.

As such, classes that can be relied upon are marked with an @api annotation.

• Interfaces in Vertex\Data
  • These are interfaces representing data models. They are used for assembling requests and responses to the Vertex SOAP API.
• Exceptions in Vertex\Exception
  • All exceptions may be thrown by Service interfaces. There are three primary exception types:
  • ConfigurationException - thrown when the configuration is known to be invalid
  • ValidationException - thrown when mapping a request has failed due to known value constraints
  • ApiException - thrown when the API returns an error. This exception is subclassed for more specific errors
    • AuthenticationException - thrown when Vertex responds that authentication data is incorrect
    • ConnectionFailureException - thrown when the library fails to connect to the Vertex SOAP API
• Interfaces in Vertex\Mapper
  • These are interfaces utilized for providing contracts for mapping a Vertex data model to a SOAP compatible format or building a SOAP compatible format into a Vertex data model.
• Vertex\Mapper\MapperFactory provides methods for retrieving a mapper based on the class it should be mapping and the version of Vertex it needs to map for. It is configured through the constructor
• Interfaces in Vertex\Services\*\
  • These are interfaces representing request and response data models.
• Vertex\Services\Invoice records an invoice in the Vertex Tax Log
• Vertex\Services\Quote requests a quotation for tax costs
• Vertex\Services\TaxAreaLookup attempts to validate an address and provide relevant jurisdictions where is taxed.
• Classes in Vertex\Utility\FaultConverter determine if a SoapFault matches their conditions for being thrown and return the proper exception if so
• Vertex\Utility\SoapClientFactory contains the default options for communicating with the Vertex SOAP API
• Vertex\Utility\SoapFaultConverterFactory creates a PooledSoapFaultConverter for converting any SoapFault into one of the library's exceptions
• Vertex\Utility\SoapFaultConverterInterface provides the contract all SoapFault Converters must adhere to in order to be useful.
• Vertex\Utility\VersionDeterminer provides the version of the Vertex API based on the WSDL URL

Testing

The Vertex API Library comes with Unit and Integration tests.

• composer test:unit runs the unit test suite
• composer test:integration runs the integration test suite

Architecture

The Vertex API Library expects that a consumer of the library will assemble the Request and data models necessary for it by hand. The consumer will then call one of the Service methods.

The service method will utilize MapperFactory to retrieve the mapper for its Request Interface, and then use the result with a SoapClient created through the use of the SoapClientFactory.

If the response received from Vertex is an Exception (SoapFault), the service will run the fault through the SoapFault converter returned from SoapFaultConverterFactory. If this converter returns an exception, the service will throw it. If it does not, the service will throw an ApiException.

If the response received is not an Exception, the service will run it through the mapper for its Response Interface and return this result to the caller.