PHPackages upgplc/php-clientlibrary - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. upgplc/php-clientlibrary ActiveLibrary[Utility & Helpers](/categories/utility) upgplc/php-clientlibrary ======================== The Client Library for UPG 1.0.1(9y ago)02181PHPPHP >=5.3 Since May 20Pushed 9y ago3 watchersCompare [ Source](https://github.com/UPGcarts/clientlibrary)[ Packagist](https://packagist.org/packages/upgplc/php-clientlibrary)[ RSS](/packages/upgplc-php-clientlibrary/feed)WikiDiscussions master Synced today READMEChangelog (2)Dependencies (5)Versions (4)Used By (0) UPG Client Library for PHP ========================== [](#upg-client-library-for-php) [![Build Status](https://camo.githubusercontent.com/5bd0f0b33036cfc87d2a5dabc855dd222519c12c90e1864ae63fda483c286897/68747470733a2f2f7472617669732d63692e6f72672f55504763617274732f636c69656e746c6962726172792e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/UPGcarts/clientlibrary)[![Codacy Badge](https://camo.githubusercontent.com/a7c90faafacbdc60c80bb55e8be97156968ad97c097768040699e89edc78ddf3/68747470733a2f2f6170692e636f646163792e636f6d2f70726f6a6563742f62616467652f67726164652f3737313064313466336439663466353462633463623138393266313963636533)](https://www.codacy.com/app/christine-jamieson/clientlibrary) PHP Client Library for the UPG API. Based on the API Documentation found here: Current Issues -------------- [](#current-issues) Currently there are issues with some of the calls these are: - CreateTransaction : The url field was renamed from the API documentation - UpdateTransaction : Currently Incomplete Using the Library ----------------- [](#using-the-library) ### Config Object [](#config-object) The API requires the configuration to work correctly. All classes and methods that require cofiguration can be passed a populated instance of Upg\\Library\\Config. The config object should be fully populated at instantiation by providing an associative array. ``` $configData = array('merchantID' => 1, 'storeID' => 1); $config = new Upg\Library\Config($configData); ``` The fields for the config that must be provided are: - \['merchantPassword'\] *string* This is the merchant password for mac calculation - \['merchantID'\] *string* This is the merchantID assigned by UPG. - \['storeID'\] *string* This is the store ID of a merchant. - \['logEnabled'\] *bool* Should logging be enabled - \['logLevel'\] *int* Log level See class constants for possible values - \['logLocationMain'\] *string* Main log location file path - \['logLocationRequest'\] *string* Log location file path for API requests - \['defaultRiskClass'\] *string* Default risk class - \['defaultLocale'\] *string* Default locale (see [Supported Languages](http://documentation.upgplc.com/hostedpagesdraft/en/topic/supported-languages)) - \['sendRequestsWithSalt'\] *bool* Automatically add salt to requests. In live this should be set to true and not false. However, for testing this can be false. By default this will be true if not specified. - \['baseUrl'\] *string* Base URL of requests that should contain either or #### Log Levels [](#log-levels) When referencing log levels be sure to use the Psr\\Log\\LogLevel static constants E.g. `\Psr\Log\LogLevel::ALERT` ### Starting an API request [](#starting-an-api-request) The Library for requests is split in three parts: **Upg\\Library\\Request** contains the request classes. **Upg\\Library\\Request\\Objects** contains classes for the JSON objects that are documented in the API docs. If a request has a property that requires a JSON object please pass in the appropriately populated **Upg\\Library\\Request\\Objects** class for that property. All properties in the request and JSON objects have getters and setters. For example, to set a field called userType on the request or object you would call `setUserType` and to get it you would call `getUserType`. #### Notes on Date fields [](#notes-on-date-fields) Any field in the Requests and JSON Objects that requires a Date should be passed a PHP DateTime object - even if the field only requires month and year. For fields that require only a month and year such as the validity of a payment instrument, please look at [DateTime::setDate](http://php.net/manual/en/datetime.setdate.php). Simply running the code like this would give you a DateTime object to populate the field ``` $expiryMonth = 2 $expiryYear = 2020 $date = new \DateTime(); $date->setDate($expiryYear, $expiryMonth, 1); ``` The serializer will serialize the date to a correctly formatted string for the request. #### Notes on Amount Fields [](#notes-on-amount-fields) Any field that requires a JSON amount fields should be provided the **Upg\\Library\\Request\\Objects\\Amount** object. This object has three properties: - amount: Full amount (subtotal+tax) in the lowest currency unit. - vatAmount: The amount of VAT if available in the lowest currency unit - vatRate: If a vatAmount is provided please provide details of the VAT rate up to 2 decimal places. All amount values must be in the lowest currency unit (i.e. Cents, Pence, etc). So for example a 10 Euro transaction with 20% VAT would need to be populated: - amount: 1200 - vatAmount: 200 - vatRate: 20 #### Sending the request [](#sending-the-request) Once you have populated a request object with the appropriate values simply instantiate an instance of a **Upg\\Library\\Api**class for the appropriate method call. Pass in a config object and the request you want to send. Then, calling the `sendRequest()` method will send the response. Raise any exception or provide a success response. The exceptions which can be raised are in **Upg\\Library\\Api\\Exception**. For any parsed responses you will have access to an **Upg\\Library\\Response\\SuccessResponse** or **Upg\\Library\\Response\\FailureResponse** object. The success object is returned if no exception is thrown. The failure object is returned in **Upg\\Library\\Api\\Exception\\ApiError** exception. The response object has two types of properties: Fixed properties such as the resultCode which are in every request, and Dynamic properties such as allowedPaymentMethods which are not in every request. To access a property that is Fixed or Dynamic, simply use the following: ``` $response->getData('resultCode'); $response->getData('allowedPaymentMethods'); ``` If any response contains JSON objects or an array of objects then the library will attempt to serialize them into **Upg\\Library\\Request\\Objects** classes. The properties names in responses that will be serialized are as follows: - allowedPaymentInstruments, paymentInstruments : Array of Upg\\Library\\Request\\Objects\\PaymentInstrument - billingAddress, shippingAddress : Upg\\Library\\Request\\Objects\\Address - amount : Upg\\Library\\Request\\Objects\\Amount - companyData : Upg\\Library\\Request\\Objects\\Company - paymentInstrument : Upg\\Library\\Request\\Objects\\PaymentInstrument - userData : Upg\\Library\\Request\\Objects\\Person For example the response on the getUser API call contains the following properties that will be serialized to the following objects - companyData field would be an Upg\\Library\\Request\\Objects\\Company object - userData field would be an Upg\\Library\\Request\\Objects\\Person object - billingAddress, shippingAddress would be Upg\\Library\\Request\\Objects\\Address objects The MAC validation/calculation for requests and responses is handled by the library and if these fail an exception will be raised. All variables that are not ISO values are defined in classes as constants for you to use in the request. For possible fixed field values please see the following constants: - locale: Upg\\Library\\Locale\\Codes - riskClasses: Upg\\Library\\Risk\\RiskClass - userType: Upg\\Library\\User\\Type - salutation: Upg\\Library\\Request\\Objects\\Person::SALUTATIONFEMALE Upg\\Library\\Request\\Objects\\Person::SALUTATIONMALE - companyRegisterType: Upg\\Library\\Request\\Objects\\Company - paymentInstrumentType: Upg\\Library\\Request\\Objects\\PaymentInstrument - issuer: Upg\\Library\\Request\\Objects\\PaymentInstrument The library implements stubs for all the methods except for registerMerchant as at this time UPG is restricting this to authorised parties only. ### Handling Callback [](#handling-callback) For the reserve API call you may be provided a callback from the API as a POST/GET request. For this the client library implements a helper for you to use: **Upg\\Library\\Callback\\Handler**. This takes in the following for the constructor: - $config: The config object for the integration - $data: The data from the post\\get variables which should be an associated array containing contain the following: - merchantID - storeID - orderID - resultCode - merchantReference : Optional field - message : Optional field - salt - mac - $processor: An instance of an object that implements the **Upg\\Library\\Callback\\ProcessorInterface** interface, which the method will invoke after validation The processor should implement two methods: `sendData` which the handler uses to pass data to the processor to use and another method called `run`, which will get invoked to handle call back processing. This processor should return a string which contains a URL where the user should be redirected to after UPG has processed the transaction. To run the handler simply call the `run` method on the object. Please note the following exceptions can be raised in which case the store must still send a URL, but respond with a non 200 HTTP result code to indicate there has been an issue. The following exceptions may be raised: - Upg\\Library\\Callback\\Exception\\ParamNotProvided : If a required parameter is not provided - Upg\\Library\\Callback\\Exception\\MacValidation : If there is a MAC validation issue with the callback parameters ### Handling MNS notifications [](#handling-mns-notifications) For the MNS notification the API provides a helper class to validate MNS notification. This class is **Upg\\Library\\Mns\\Handler**. It takes the following as a constructor: - $config: The config object for the integration - $data: The data from the post\\get variables which should be an associated array of the MNS callback - $processor: An instance of an object which implements the Upg\\Library\\Mns\\ProcessorInterface interface which the method will invoke after validation. The processor object should implement `sendData` to get data from the handler and a `run` method which executes your callback after successful validation. The processor callback should avoid processing the request, instead it should save it to a database for asynchronous processing via a cron script. Please note the MNS call must always return a 200 response to UPG otherwise no other MNS would be sent until a given MNS notification is accepted with a HTTP 200 response. ### Working with PayCoBridge.js [](#working-with-paycobridgejs) Please note this plugin does not provide any javascript libraries for the paybridge. Integrations using paybridge are expected to implement the javascript library. However, this library can be used to implement the server side functionality for any paybridge integrations, using PHP on the backend. If you use the handler class to save a MNS to the database for later processing you can assume the MNS is perfectly valid with out checking the MAC. Working on the plugin --------------------- [](#working-on-the-plugin) If you want to contribute o the library, please note that all code should be written according to the **PSR2 standard**. This is very easy to set up in PHPStorm by using PHP-Codesniffer. To configure PHP-Codesniffer for PHPStorm follow these steps: 1. Run the following. ``` composer global require 'squizlabs/php_codesniffer=*' ``` 2. In PHPStorm open the settings dialog and navigate to Languages & Framework -> PHP -> Code Sniffer 3. On configuration option click the ... button and in that prompt point PHPStorm to the path of Code Sniffer 4. To set the code style navigate to Editor -> Code Style -> PHP 5. In the setting click on Set From and go to Predefined Style -> PSR1/PSR2 6. Click on the OK button ### Health Score 29 — LowBetter than 57% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity12 Limited adoption so far Community13 Small or concentrated contributor base Maturity60 Established project with proven stability Bus Factor1 Top contributor holds 55.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~52 days Total 2 Last Release 3547d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/e7b15381952292a3001977a473d2ee33d53acaede3dad148c5b9c20ba51832f3?d=identicon)[UPG Plc](/maintainers/UPG%20Plc) --- Top Contributors [![everon](https://avatars.githubusercontent.com/u/375251?v=4)](https://github.com/everon "everon (5 commits)")[![edmondscommerce](https://avatars.githubusercontent.com/u/62842?v=4)](https://github.com/edmondscommerce "edmondscommerce (3 commits)")[![CJamies](https://avatars.githubusercontent.com/u/15160215?v=4)](https://github.com/CJamies "CJamies (1 commits)") --- Tags libraryUpg ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/upgplc-php-clientlibrary/health.svg) ``` [![Health](https://phpackages.com/badges/upgplc-php-clientlibrary/health.svg)](https://phpackages.com/packages/upgplc-php-clientlibrary) ``` ### Alternatives [matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.6k38.2k](/packages/matomo-matomo)[google/cloud-core Google Cloud PHP shared dependency, providing functionality useful to all components. 346132.9M110](/packages/google-cloud-core)[brianhenryie/strauss Prefixes dependencies namespaces so they are unique to your plugin 190438.1k31](/packages/brianhenryie-strauss)[checkout/checkout-sdk-php Checkout.com SDK for PHP 563.6M12](/packages/checkout-checkout-sdk-php)[kisma/kisma PHP Utility Belt 178.5k8](/packages/kisma-kisma) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)