Skip to content

Commit 8004b1f

Browse files
bakura10bakura10
committed
Prepare v3
1 parent 778b1c8 commit 8004b1f

File tree

7 files changed

+146
-10841
lines changed

7 files changed

+146
-10841
lines changed

‎CHANGELOG.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,23 @@
1+
# 3.0.0
2+
3+
* [BC] For all descriptors, `closeDispute` and `updateDispute` now uses the new endpoints that do not require a charge ID but instead a dispute
4+
ID. In previous versions:
5+
6+
```php
7+
$stripeClient->closeDispute(['charge' => 'ch_abc']);
8+
```
9+
10+
In new version:
11+
12+
```php
13+
$stripeClient->closeDispute(['id' => 'dp_abc']);
14+
```
15+
16+
Also, new endpoints have been added that allow to retrieve a specific dispute by its id, as well as retrieving all disputes.
17+
18+
* [BC] Descriptor cleanup: older descriptors have been removed. ZfrStripe now supports Stripe API version from 2015-02-18. If you are using an older
19+
version of the API, you should stay on 2.x branch.
20+
121
# 2.20.0
222

323
* [BC] Set default Stripe API to "2015-07-28"

‎README.md‎

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ZfrStripe is a modern PHP library based on Guzzle for [Stripe payment system](ht
1515
Installation of ZfrStripe is only officially supported using Composer:
1616

1717
```sh
18-
php composer.phar require 'zfr/zfr-stripe:2.*'
18+
php composer.phar require 'zfr/zfr-stripe:3.*'
1919
```
2020

2121
## Tutorial
@@ -39,21 +39,24 @@ $client = new StripeClient('my-api-key', '2015-07-28');
3939

4040
### Versioning
4141

42-
Stripe versions its API using a dated version ("2013-12-03", "2014-01-31"...). Their [versioning policy](https://stripe.com/docs/upgrades)
43-
is to release a new dated version each time something changes in their API (for instance, if a response returns
44-
new attributes, if new endpoint is added)...
42+
Stripe API has an odd (yet very useful) [versioning policy](https://stripe.com/docs/upgrades) that makes it hard to version it correctly. The trick
43+
is that Stripe may change how some properties are passed on return on new versions (hence being a BC for older version), but still introduce new endpoints
44+
that will be available to older versions too.
4545

46-
Starting from v2, ZfrStripe does not follow this mechanism strictly, because new endpoints are actually also available for older versions of Stripe. We therefore only release a new descriptor each time an endpoint is **removed** or if its URL changes.
46+
Therefore, each time a new dated version of Stripe API is released, ZfrStripe will adopt this policy:
4747

48-
However, each new minor version (2.1.0 to 2.2.0 for instance) will update the Stripe API version to the latest available. This means that Stripe responses *may* change. This means that to keep BC you should either tighten your dependency (2.1.* instead of 2.* for instance) OR always specify the exact version you want, as shown above.
48+
* If new endpoints are introduced, without changing old ones, the new endpoints are added for all supported versions. A minor version is tagged, and set
49+
the default Stripe version as the latest one.
50+
* If no new endpoints are introduced, but some parameter change, a new descriptor is created, hence supporting multiple versions. A minor version is tagged,
51+
and set the default Stripe version as the latest one.
52+
* If no new endpoints are introduced, and no parameter are changed, a minor version is tagged, and set the default Stripe version as the latest one.
53+
* If existing endpoints are updating by changing their URL, a major release of ZfrStripe is released as compatibility cannot be assured.
4954

50-
Currently, the following Stripe API versions are accepted by ZfrStripe: `2014-03-28`, `2014-05-19`, `2014-06-13`,
51-
`2014-06-17`, `2014-07-22`, `2014-07-26`, `2014-08-04`, `2014-08-20`, `2014-09-08`, `2014-10-07`, `2014-11-05`,
52-
`2014-11-20`, `2014-12-08`, `2014-12-17`, `2014-12-22`, `2015-01-11`, `2015-01-26`, `2015-02-10`, `2015-02-16`,
53-
`2015-02-18`, `2015-03-24`, `2015-04-07`, `2015-06-15`, `2015-07-07`, `2015-07-13`, `2015-07-28`. I will try
54-
to update the library as soon as new version are released.
55+
Currently, the following Stripe API versions are accepted by ZfrStripe: `2015-02-18`, `2015-03-24`, `2015-04-07`, `2015-06-15`, `2015-07-07`,
56+
`2015-07-13`, `2015-07-28`. I will try to update the library as soon as new version are released.
5557

56-
> If you need support for older versions, please use branch v1 of ZfrStripe.
58+
> If you need support for versions as old as 2014-03-28, please use branch v2 of ZfrStripe.
59+
> If you need support for even older versions, please use branch v1 of ZfrStripe.
5760
5861
### How to use it?
5962

@@ -359,6 +362,8 @@ INVOICE ITEM RELATED METHODS:
359362

360363
DISPUTE RELATED METHODS:
361364

365+
* array getDispute(array $args = array()
366+
* array getDisputes(array $args = array())
362367
* array closeDispute(array $args = array())
363368
* array updateDispute(array $args = array())
364369

‎src/Client/ServiceDescription/Stripe-v1.0.php‎

Lines changed: 104 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@
113113
'CreateCharge' => [
114114
'httpMethod' => 'POST',
115115
'uri' => '/v1/charges',
116-
'summary' => 'Create a new charge (either card or customer is needed)',
116+
'summary' => 'Create a new charge (either source or customer is needed)',
117117
'errorResponses' => $errors,
118118
'parameters' => [
119119
'amount' => [
@@ -134,8 +134,8 @@
134134
'type' => 'string',
135135
'required' => false
136136
],
137-
'card' => [
138-
'description' => 'Unique card identifier (can either be an ID or a hash)',
137+
'source' => [
138+
'description' => 'Unique source (can either be an ID or a hash)',
139139
'location' => 'query',
140140
'type' => ['string', 'array'],
141141
'required' => false
@@ -159,8 +159,8 @@
159159
'type' => 'array',
160160
'required' => false
161161
],
162-
'statement_description' => [
163-
'description' => 'An arbitrary string to be displayed alongside your company name on your customer\'s credit card statement',
162+
'statement_descriptor' => [
163+
'description' => 'An arbitrary string to be displayed alongside your customer\'s credit card statement',
164164
'location' => 'query',
165165
'type' => 'string',
166166
'required' => false
@@ -400,8 +400,8 @@
400400
'type' => 'integer',
401401
'required' => false
402402
],
403-
'card' => [
404-
'description' => 'Unique card identifier (can either be an ID or a hash)',
403+
'source' => [
404+
'description' => 'Unique source identifier (can either be an ID or a hash)',
405405
'location' => 'query',
406406
'type' => ['string', 'array'],
407407
'required' => false
@@ -578,8 +578,8 @@
578578
'type' => 'integer',
579579
'required' => false
580580
],
581-
'card' => [
582-
'description' => 'Unique card identifier (can either be an ID or a hash)',
581+
'source' => [
582+
'description' => 'Unique source identifier (can either be an ID or a hash)',
583583
'location' => 'query',
584584
'type' => ['string', 'array'],
585585
'required' => false
@@ -1424,8 +1424,8 @@
14241424
'type' => 'array',
14251425
'required' => false
14261426
],
1427-
'statement_description' => [
1428-
'description' => 'An arbitrary string to be displayed alongside your company name on your customer\'s credit card statement',
1427+
'statement_descriptor' => [
1428+
'description' => 'An arbitrary string to be displayed alongside your customer\'s credit card statement',
14291429
'location' => 'query',
14301430
'type' => 'string',
14311431
'required' => false
@@ -1553,8 +1553,8 @@
15531553
'type' => 'array',
15541554
'required' => false
15551555
],
1556-
'statement_description' => [
1557-
'description' => 'An arbitrary string to be displayed alongside your company name on your customer\'s credit card statement',
1556+
'statement_descriptor' => [
1557+
'description' => 'An arbitrary string to be displayed alongside your customer\'s credit card statement',
15581558
'location' => 'query',
15591559
'type' => 'string',
15601560
'required' => false
@@ -1859,7 +1859,7 @@
18591859
'type' => 'string',
18601860
'required' => false
18611861
],
1862-
'statement_description' => [
1862+
'statement_descriptor' => [
18631863
'description' => 'Extra information about a charge for the customer\'s credit card statement',
18641864
'location' => 'query',
18651865
'type' => 'string',
@@ -2134,7 +2134,7 @@
21342134
'type' => 'string',
21352135
'required' => false
21362136
],
2137-
'statement_description' => [
2137+
'statement_descriptor' => [
21382138
'description' => 'Extra information about a charge for the customer\'s credit card statement',
21392139
'location' => 'query',
21402140
'type' => 'string',
@@ -2411,14 +2411,14 @@
24112411
* --------------------------------------------------------------------------------
24122412
*/
24132413

2414-
'CloseDispute' => [
2415-
'httpMethod' => 'POST',
2416-
'uri' => '/v1/charges/{charge}/dispute/close',
2417-
'summary' => 'Close a dispute',
2414+
'GetDispute' => [
2415+
'httpMethod' => 'GET',
2416+
'uri' => '/v1/disputes/{id}',
2417+
'summary' => 'Get an existing dispute',
24182418
'errorResponses' => $errors,
24192419
'parameters' => [
2420-
'charge' => [
2421-
'description' => 'ID of the charge to close the dispute',
2420+
'id' => [
2421+
'description' => 'Unique identifier of the dispute',
24222422
'location' => 'uri',
24232423
'type' => 'string',
24242424
'required' => true
@@ -2428,33 +2428,78 @@
24282428
'location' => 'query',
24292429
'type' => 'array',
24302430
'required' => false
2431+
]
2432+
]
2433+
],
2434+
2435+
'GetDisputes' => [
2436+
'httpMethod' => 'GET',
2437+
'uri' => '/v1/disputes',
2438+
'summary' => 'Get existing disputes',
2439+
'errorResponses' => $errors,
2440+
'parameters' => [
2441+
'limit' => [
2442+
'description' => 'Limit on how many disputes are retrieved',
2443+
'location' => 'query',
2444+
'type' => 'integer',
2445+
'min' => 1,
2446+
'max' => 100,
2447+
'required' => false
24312448
],
2432-
'idempotency_key' => [
2433-
'description' => 'An indempotency key that prevents accidentally performing the same POST operation twice',
2434-
'location' => 'header',
2435-
'sentAs' => 'Idempotency-Key',
2449+
'starting_after' => [
2450+
'description' => 'A cursor for use in the pagination',
2451+
'location' => 'query',
2452+
'type' => 'string',
2453+
'required' => false
2454+
],
2455+
'ending_before' => [
2456+
'description' => 'A cursor for use in the pagination',
2457+
'location' => 'query',
2458+
'type' => 'string',
2459+
'required' => false
2460+
],
2461+
'created' => [
2462+
'description' => 'A filter based on the "created" field. Can be an exact UTC timestamp, or a hash',
2463+
'location' => 'query',
2464+
'required' => false
2465+
],
2466+
'customer' => [
2467+
'description' => 'Only return invoices for a specific customer',
2468+
'location' => 'query',
24362469
'type' => 'string',
24372470
'required' => false
2471+
],
2472+
'expand' => [
2473+
'description' => 'Allow to expand some properties',
2474+
'location' => 'query',
2475+
'type' => 'array',
2476+
'required' => false
2477+
],
2478+
'include' => [
2479+
'description' => 'Allow to include some additional properties',
2480+
'location' => 'query',
2481+
'type' => 'array',
2482+
'required' => false
24382483
]
24392484
]
24402485
],
24412486

24422487
'UpdateDispute' => [
24432488
'httpMethod' => 'POST',
2444-
'uri' => '/v1/charges/{charge}/dispute',
2489+
'uri' => '/v1/disputes/{id}',
24452490
'summary' => 'Update a dispute',
24462491
'errorResponses' => $errors,
24472492
'parameters' => [
2448-
'charge' => [
2449-
'description' => 'ID of the charge to update the dispute',
2493+
'id' => [
2494+
'description' => 'ID of the dispute to update',
24502495
'location' => 'uri',
24512496
'type' => 'string',
24522497
'required' => true
24532498
],
24542499
'evidence' => [
2455-
'description' => 'Evidence text',
2500+
'description' => 'Evidence hash',
24562501
'location' => 'query',
2457-
'type' => 'string',
2502+
'type' => 'array',
24582503
'required' => false
24592504
],
24602505
'metadata' => [
@@ -2479,6 +2524,34 @@
24792524
]
24802525
],
24812526

2527+
'CloseDispute' => [
2528+
'httpMethod' => 'POST',
2529+
'uri' => '/v1/disputes/{id}/close',
2530+
'summary' => 'Close a dispute',
2531+
'errorResponses' => $errors,
2532+
'parameters' => [
2533+
'charge' => [
2534+
'description' => 'ID of the charge to close the dispute',
2535+
'location' => 'uri',
2536+
'type' => 'string',
2537+
'required' => true
2538+
],
2539+
'expand' => [
2540+
'description' => 'Allow to expand some properties',
2541+
'location' => 'query',
2542+
'type' => 'array',
2543+
'required' => false
2544+
],
2545+
'idempotency_key' => [
2546+
'description' => 'An indempotency key that prevents accidentally performing the same POST operation twice',
2547+
'location' => 'header',
2548+
'sentAs' => 'Idempotency-Key',
2549+
'type' => 'string',
2550+
'required' => false
2551+
]
2552+
]
2553+
],
2554+
24822555
/**
24832556
* --------------------------------------------------------------------------------
24842557
* TRANSFER RELATED METHODS
@@ -2545,7 +2618,7 @@
25452618
'type' => 'string',
25462619
'required' => false
25472620
],
2548-
'statement_description' => [
2621+
'statement_descriptor' => [
25492622
'description' => 'An arbitrary string which will be displayed on the recipient\'s bank statement',
25502623
'location' => 'query',
25512624
'type' => 'string',

0 commit comments

Comments
 (0)