Skip to content

Commit 3bbe6a1

Browse files
authored
Create CHANGELOG.md
1 parent fae41fa commit 3bbe6a1

File tree

1 file changed

+171
-0
lines changed

1 file changed

+171
-0
lines changed

CHANGELOG.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
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

Comments
 (0)