|
| 1 | +Changelog |
| 2 | +========= |
| 3 | + |
| 4 | +## v3.2 - 2021-06-01 |
| 5 | + |
| 6 | +Omnipay 3.2 is compatible with PHP8. This is done by upgrading the test suite to PHPUnit 9, with the release of omnipay/tests v4 and omnipay/common v3.1. This change is primarily for gateway developers, to make it possible to actually test PHP8, but they will need to upgrade their tests to use PHPUnit 9 (the currently supported PHPUnit version). The minimum PHP versions is bumped to 7.3 because of this. |
| 7 | + |
| 8 | +## v3.1 - 2020-10-29 |
| 9 | + |
| 10 | +Omnipay 3.1 uses Guzzle 7 by default (using the Guzzle 7 adapter). This doesn't change omnipay-common because they will work with any compatible Http Client. |
| 11 | +The minimum PHP versions is bumped to 7.2 because of this. |
| 12 | + |
| 13 | +## v3.0 - 2018-05-14 |
| 14 | + |
| 15 | +Omnipay 3.0 focuses on separation of the HTTP Client, to be independent of Guzzle. |
| 16 | +This release brings compatibility with the latest Symfony 3+4 and Laravel 5. |
| 17 | +The breaking changes for applications using Omnipay are kept to a minimum. |
| 18 | + |
| 19 | +The `omnipay/omnipay` package name has been changed to `league/omnipay` |
| 20 | + |
| 21 | +### Upgrading applications from Omnipay 2.x to 3.x |
| 22 | + |
| 23 | +#### Breaking changes |
| 24 | + - The `redirect()` method no calls `exit()` after sending the content. This is up to the developer now. |
| 25 | + - An HTTP Client is required. Guzzle will be installed when using `league/omnipay`, |
| 26 | + but otherwise you need to required your own implementation (see [PHP HTTP Clients](http://docs.php-http.org/en/latest/clients.html)) |
| 27 | +- The `omnipay/omnipay` package name has been changed to `league/omnipay` and no longers installs all the gateways directly. |
| 28 | + |
| 29 | +#### Added |
| 30 | + - It is now possible to use `setAmountInteger(integer $value)` to set the amount in the base units of the currency. |
| 31 | + - Support for [Money for PHP](http://moneyphp.org/) objects are added, by using `setMoney(Money $money)` the Amount and Currency are set. |
| 32 | + |
| 33 | +### Upgrading Gateways from 2.x to 3.x |
| 34 | + |
| 35 | +The primary difference is the HTTP Client. We are now using HTTPlug (http://httplug.io/) but rely on our own interface. |
| 36 | + |
| 37 | +### Breaking changes |
| 38 | +- Change typehint from Guzzle ClientInterface to `Omnipay\Common\Http\ClientInterface` |
| 39 | +- `$client->get('..')`/`$client->post('..')` etc are removed, you can call `$client->request('GET', '')`. |
| 40 | +- No need to call `$request->send()`, requests are sent directly. |
| 41 | +- Instead of `$client->createRequest(..)` you can create+send the request directly with `$client->request(..)`. |
| 42 | +- When sending a JSON body, convert the body to a string with `json_encode()` and set the correct Content-Type. |
| 43 | +- The response is a PSR-7 Response object. You can call `$response->getBody()->getContents()` to get the body as string. |
| 44 | +- `$response->json()` and `$response->xml()` are gone, but you can implement the logic directly. |
| 45 | +- An HTTP Client is no longer added by default by `omnipay/common`, but `league/omnipay` will add Guzzle. |
| 46 | +Gateways should not rely on Guzzle or other clients directly. |
| 47 | +- `$body` should be a string (eg. `http_build_query($data)` or `json_encode($data)` instead of just `$data`). |
| 48 | +- The `$headers` parameters should be an `array` (not `null`, but can be empty) |
| 49 | + |
| 50 | +Examples: |
| 51 | +```php |
| 52 | +// V2 XML: |
| 53 | + $response = $this->httpClient->post($this->endpoint, null, $data)->send(); |
| 54 | + $result = $httpResponse->xml(); |
| 55 | + |
| 56 | +// V3 XML: |
| 57 | + $response = $this->httpClient->request('POST', $this->endpoint, [], http_build_query($data)); |
| 58 | + $result = simplexml_load_string($httpResponse->getBody()->getContents()); |
| 59 | +``` |
| 60 | + |
| 61 | +```php |
| 62 | +// Example JSON request: |
| 63 | + |
| 64 | + $response = $this->httpClient->request('POST', $this->endpoint, [ |
| 65 | + 'Accept' => 'application/json', |
| 66 | + 'Content-Type' => 'application/json', |
| 67 | + ], json_encode($data)); |
| 68 | + |
| 69 | + $result = json_decode($response->getBody()->getContents(), true); |
| 70 | +``` |
| 71 | + |
| 72 | +#### Testing changes |
| 73 | + |
| 74 | +PHPUnit is upgraded to PHPUnit 6. Common issues: |
| 75 | + |
| 76 | +- `setExpectedException()` is removed |
| 77 | + |
| 78 | +```php |
| 79 | +// PHPUnit 5: |
| 80 | +$this->setExpectedException($class, $message); |
| 81 | + |
| 82 | +// PHPUnit 6: |
| 83 | +$this->expectException($class); |
| 84 | +$this->expectExceptionMessage($message); |
| 85 | +``` |
| 86 | + |
| 87 | +- Tests that do not perform any assertions, will be marked as risky. This can be avoided by annotating them with ` @doesNotPerformAssertions` |
| 88 | + |
| 89 | +- You should remove the `Mockery\Adapter\Phpunit\TestListener` in phpunit.xml.dist |
| 90 | + |
| 91 | + |
| 92 | +## v2.0.0 - 2013-11-17 |
| 93 | + |
| 94 | +### Package Separation |
| 95 | + |
| 96 | +As of 2.0, Omnipay has been split into separate packages. Core functionality is contained within the [omnipay/common](https://github.com/omnipay/common) repository, and all gateways have their own repositories. This means that if your project only requires on a single gateway, you can load it without installing all of the other gateways. All officially supported gateways can be found under the [Omnipay GitHub organization](//github.com/omnipay). |
| 97 | + |
| 98 | +If you want to install all gateways, you can still use the `omnipay/omnipay` metapackage in `composer.json`: |
| 99 | + |
| 100 | +~~~ javascript |
| 101 | +{ |
| 102 | + "require": { |
| 103 | + "omnipay/omnipay": "~2.0" |
| 104 | + } |
| 105 | +} |
| 106 | +~~~ |
| 107 | + |
| 108 | +Alternatively, if you want to migrate to an individual gateway, simply change your `composer.json` file to reference the specific gateway (`omnipay/common` will be included for you automatically): |
| 109 | + |
| 110 | +~~~ javascript |
| 111 | +{ |
| 112 | + "require": { |
| 113 | + "omnipay/paypal": "~2.0" |
| 114 | + } |
| 115 | +} |
| 116 | +~~~ |
| 117 | + |
| 118 | +### Breaking Changes |
| 119 | + |
| 120 | +The `GatewayFactory` class can no longer be called in a static fashion. To help those who want to use dependency injection, you can now create an instance of GatewayFactory: |
| 121 | + |
| 122 | +~~~ php |
| 123 | +$factory = new GatewayFactory(); |
| 124 | +$gateway = $factory->create('PayPal_Express'); |
| 125 | +~~~ |
| 126 | + |
| 127 | +The following code is invalid and will no longer work: |
| 128 | + |
| 129 | +~~~ php |
| 130 | +$gateway = GatewayFactory::create('PayPal_Express'); // will cause PHP error! |
| 131 | +~~~ |
| 132 | + |
| 133 | +If you want to continue to use static methods for simplicity, you can use the new Omnipay class: |
| 134 | + |
| 135 | +~~~ php |
| 136 | +// at the top of your PHP file |
| 137 | +use Omnipay\Omnipay; |
| 138 | + |
| 139 | +// further down when you need to create the gateway |
| 140 | +$gateway = Omnipay::create('PayPal_Express'); |
| 141 | +~~~ |
| 142 | + |
| 143 | +Behind the scenes, this will create a GatewayFactory instance for you and call the appropriate method on it. |
| 144 | + |
| 145 | +### Additions |
| 146 | + |
| 147 | +**Omnipay now supports sending line-item data to gateways.** Currently this is only supported by the PayPal gateway. Line item details can be added to a request like so: |
| 148 | + |
| 149 | +~~~ php |
| 150 | +$request->setItems(array( |
| 151 | + array('name' => 'Food', 'quantity' => 1, 'price' => '40.00'), |
| 152 | + array('name' => 'Drinks', 'quantity' => 2, 'price' => '6.00'), |
| 153 | +)); |
| 154 | +~~~ |
| 155 | + |
| 156 | +For more details, see the [pull request](https://github.com/omnipay/omnipay/pull/154). |
| 157 | + |
| 158 | +**Omnipay now also supports modifying request data before it is sent to the gateway.**. This allows you to send arbitrary custom data with a request, even if Omnipay doesn't support a parameter directly. To modify the request data, instead of calling `send()` directly on the request, you may use the new `sendData()` method: |
| 159 | + |
| 160 | +~~~ php |
| 161 | +// standard method - send default data |
| 162 | +$response = $request->send(); |
| 163 | + |
| 164 | +// new method - get and send custom data |
| 165 | +$data = $request->getData(); |
| 166 | +$data['customParameter'] = true; |
| 167 | + |
| 168 | +$response = $request->sendData($data); |
| 169 | +~~~ |
| 170 | + |
| 171 | +For more details, see the [pull request](https://github.com/omnipay/omnipay/pull/162). |
0 commit comments