Skip to content

Commit

Permalink
Prepare v3
Browse files Browse the repository at this point in the history
  • Loading branch information
@bakura10
bakura10 committed Aug 4, 2015
1 parent 778b1c8 commit 8004b1f
Show file tree
Hide file tree
Showing 7 changed files with 146 additions and 10,841 deletions.
20 changes: 20 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,23 @@
# 3.0.0

* [BC] For all descriptors, `closeDispute` and `updateDispute` now uses the new endpoints that do not require a charge ID but instead a dispute
ID. In previous versions:

```php
$stripeClient->closeDispute(['charge' => 'ch_abc']);
```

In new version:

```php
$stripeClient->closeDispute(['id' => 'dp_abc']);
```

Also, new endpoints have been added that allow to retrieve a specific dispute by its id, as well as retrieving all disputes.

* [BC] Descriptor cleanup: older descriptors have been removed. ZfrStripe now supports Stripe API version from 2015-02-18. If you are using an older
version of the API, you should stay on 2.x branch.

# 2.20.0

* [BC] Set default Stripe API to "2015-07-28"
Expand Down
29 changes: 17 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ ZfrStripe is a modern PHP library based on Guzzle for [Stripe payment system](ht
Installation of ZfrStripe is only officially supported using Composer:

```sh
php composer.phar require 'zfr/zfr-stripe:2.*'
php composer.phar require 'zfr/zfr-stripe:3.*'
```

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

### Versioning

Stripe versions its API using a dated version ("2013-12-03", "2014-01-31"...). Their [versioning policy](https://stripe.com/docs/upgrades)
is to release a new dated version each time something changes in their API (for instance, if a response returns
new attributes, if new endpoint is added)...
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
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
that will be available to older versions too.

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.
Therefore, each time a new dated version of Stripe API is released, ZfrStripe will adopt this policy:

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.
* 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
the default Stripe version as the latest one.
* If no new endpoints are introduced, but some parameter change, a new descriptor is created, hence supporting multiple versions. A minor version is tagged,
and set the default Stripe version as the latest one.
* 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.
* If existing endpoints are updating by changing their URL, a major release of ZfrStripe is released as compatibility cannot be assured.

Currently, the following Stripe API versions are accepted by ZfrStripe: `2014-03-28`, `2014-05-19`, `2014-06-13`,
`2014-06-17`, `2014-07-22`, `2014-07-26`, `2014-08-04`, `2014-08-20`, `2014-09-08`, `2014-10-07`, `2014-11-05`,
`2014-11-20`, `2014-12-08`, `2014-12-17`, `2014-12-22`, `2015-01-11`, `2015-01-26`, `2015-02-10`, `2015-02-16`,
`2015-02-18`, `2015-03-24`, `2015-04-07`, `2015-06-15`, `2015-07-07`, `2015-07-13`, `2015-07-28`. I will try
to update the library as soon as new version are released.
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`,
`2015-07-13`, `2015-07-28`. I will try to update the library as soon as new version are released.

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

Expand Down Expand Up @@ -359,6 +362,8 @@ INVOICE ITEM RELATED METHODS:

DISPUTE RELATED METHODS:

* array getDispute(array $args = array()
* array getDisputes(array $args = array())
* array closeDispute(array $args = array())
* array updateDispute(array $args = array())

Expand Down
135 changes: 104 additions & 31 deletions src/Client/ServiceDescription/Stripe-v1.0.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@
'CreateCharge' => [
'httpMethod' => 'POST',
'uri' => '/v1/charges',
'summary' => 'Create a new charge (either card or customer is needed)',
'summary' => 'Create a new charge (either source or customer is needed)',
'errorResponses' => $errors,
'parameters' => [
'amount' => [
Expand All @@ -134,8 +134,8 @@
'type' => 'string',
'required' => false
],
'card' => [
'description' => 'Unique card identifier (can either be an ID or a hash)',
'source' => [
'description' => 'Unique source (can either be an ID or a hash)',
'location' => 'query',
'type' => ['string', 'array'],
'required' => false
Expand All @@ -159,8 +159,8 @@
'type' => 'array',
'required' => false
],
'statement_description' => [
'description' => 'An arbitrary string to be displayed alongside your company name on your customer\'s credit card statement',
'statement_descriptor' => [
'description' => 'An arbitrary string to be displayed alongside your customer\'s credit card statement',
'location' => 'query',
'type' => 'string',
'required' => false
Expand Down Expand Up @@ -400,8 +400,8 @@
'type' => 'integer',
'required' => false
],
'card' => [
'description' => 'Unique card identifier (can either be an ID or a hash)',
'source' => [
'description' => 'Unique source identifier (can either be an ID or a hash)',
'location' => 'query',
'type' => ['string', 'array'],
'required' => false
Expand Down Expand Up @@ -578,8 +578,8 @@
'type' => 'integer',
'required' => false
],
'card' => [
'description' => 'Unique card identifier (can either be an ID or a hash)',
'source' => [
'description' => 'Unique source identifier (can either be an ID or a hash)',
'location' => 'query',
'type' => ['string', 'array'],
'required' => false
Expand Down Expand Up @@ -1424,8 +1424,8 @@
'type' => 'array',
'required' => false
],
'statement_description' => [
'description' => 'An arbitrary string to be displayed alongside your company name on your customer\'s credit card statement',
'statement_descriptor' => [
'description' => 'An arbitrary string to be displayed alongside your customer\'s credit card statement',
'location' => 'query',
'type' => 'string',
'required' => false
Expand Down Expand Up @@ -1553,8 +1553,8 @@
'type' => 'array',
'required' => false
],
'statement_description' => [
'description' => 'An arbitrary string to be displayed alongside your company name on your customer\'s credit card statement',
'statement_descriptor' => [
'description' => 'An arbitrary string to be displayed alongside your customer\'s credit card statement',
'location' => 'query',
'type' => 'string',
'required' => false
Expand Down Expand Up @@ -1859,7 +1859,7 @@
'type' => 'string',
'required' => false
],
'statement_description' => [
'statement_descriptor' => [
'description' => 'Extra information about a charge for the customer\'s credit card statement',
'location' => 'query',
'type' => 'string',
Expand Down Expand Up @@ -2134,7 +2134,7 @@
'type' => 'string',
'required' => false
],
'statement_description' => [
'statement_descriptor' => [
'description' => 'Extra information about a charge for the customer\'s credit card statement',
'location' => 'query',
'type' => 'string',
Expand Down Expand Up @@ -2411,14 +2411,14 @@
* --------------------------------------------------------------------------------
*/

'CloseDispute' => [
'httpMethod' => 'POST',
'uri' => '/v1/charges/{charge}/dispute/close',
'summary' => 'Close a dispute',
'GetDispute' => [
'httpMethod' => 'GET',
'uri' => '/v1/disputes/{id}',
'summary' => 'Get an existing dispute',
'errorResponses' => $errors,
'parameters' => [
'charge' => [
'description' => 'ID of the charge to close the dispute',
'id' => [
'description' => 'Unique identifier of the dispute',
'location' => 'uri',
'type' => 'string',
'required' => true
Expand All @@ -2428,33 +2428,78 @@
'location' => 'query',
'type' => 'array',
'required' => false
]
]
],

'GetDisputes' => [
'httpMethod' => 'GET',
'uri' => '/v1/disputes',
'summary' => 'Get existing disputes',
'errorResponses' => $errors,
'parameters' => [
'limit' => [
'description' => 'Limit on how many disputes are retrieved',
'location' => 'query',
'type' => 'integer',
'min' => 1,
'max' => 100,
'required' => false
],
'idempotency_key' => [
'description' => 'An indempotency key that prevents accidentally performing the same POST operation twice',
'location' => 'header',
'sentAs' => 'Idempotency-Key',
'starting_after' => [
'description' => 'A cursor for use in the pagination',
'location' => 'query',
'type' => 'string',
'required' => false
],
'ending_before' => [
'description' => 'A cursor for use in the pagination',
'location' => 'query',
'type' => 'string',
'required' => false
],
'created' => [
'description' => 'A filter based on the "created" field. Can be an exact UTC timestamp, or a hash',
'location' => 'query',
'required' => false
],
'customer' => [
'description' => 'Only return invoices for a specific customer',
'location' => 'query',
'type' => 'string',
'required' => false
],
'expand' => [
'description' => 'Allow to expand some properties',
'location' => 'query',
'type' => 'array',
'required' => false
],
'include' => [
'description' => 'Allow to include some additional properties',
'location' => 'query',
'type' => 'array',
'required' => false
]
]
],

'UpdateDispute' => [
'httpMethod' => 'POST',
'uri' => '/v1/charges/{charge}/dispute',
'uri' => '/v1/disputes/{id}',
'summary' => 'Update a dispute',
'errorResponses' => $errors,
'parameters' => [
'charge' => [
'description' => 'ID of the charge to update the dispute',
'id' => [
'description' => 'ID of the dispute to update',
'location' => 'uri',
'type' => 'string',
'required' => true
],
'evidence' => [
'description' => 'Evidence text',
'description' => 'Evidence hash',
'location' => 'query',
'type' => 'string',
'type' => 'array',
'required' => false
],
'metadata' => [
Expand All @@ -2479,6 +2524,34 @@
]
],

'CloseDispute' => [
'httpMethod' => 'POST',
'uri' => '/v1/disputes/{id}/close',
'summary' => 'Close a dispute',
'errorResponses' => $errors,
'parameters' => [
'charge' => [
'description' => 'ID of the charge to close the dispute',
'location' => 'uri',
'type' => 'string',
'required' => true
],
'expand' => [
'description' => 'Allow to expand some properties',
'location' => 'query',
'type' => 'array',
'required' => false
],
'idempotency_key' => [
'description' => 'An indempotency key that prevents accidentally performing the same POST operation twice',
'location' => 'header',
'sentAs' => 'Idempotency-Key',
'type' => 'string',
'required' => false
]
]
],

/**
* --------------------------------------------------------------------------------
* TRANSFER RELATED METHODS
Expand Down Expand Up @@ -2545,7 +2618,7 @@
'type' => 'string',
'required' => false
],
'statement_description' => [
'statement_descriptor' => [
'description' => 'An arbitrary string which will be displayed on the recipient\'s bank statement',
'location' => 'query',
'type' => 'string',
Expand Down
Loading

0 comments on commit 8004b1f

Please sign in to comment.