Skip to content

Commit ec01803

Browse files
greydnlsgreydnls
committed
Merge pull request #12 from delatbabel/master
Update docblocks for API documentation
2 parents 23a5f77 + 72dd50f commit ec01803

15 files changed

+529
-1
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,6 @@
22
composer.lock
33
composer.phar
44
phpunit.xml
5+
.directory
6+
/dirlist.*
7+
/documents/

‎README.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ And run composer to update your dependencies:
3131

3232
The following gateways are provided by this package:
3333

34-
* Stripe
34+
* [Stripe](https://stripe.com/)
3535

3636
For general usage instructions, please see the main [Omnipay](https://github.com/thephpleague/omnipay)
3737
repository.
@@ -50,6 +50,15 @@ $token = $_POST['stripeToken'];
5050
$response = $gateway->purchase(['amount' => '10.00', 'currency' => 'USD', 'token' => $token])->send();
5151
```
5252

53+
## Test Mode
54+
55+
Stripe accounts have test-mode API keys as well as live-mode API keys. These keys can be active
56+
at the same time. Data created with test-mode credentials will never hit the credit card networks
57+
and will never cost anyone money.
58+
59+
Unlike some gateways, there is no test mode endpoint separate to the live mode endpoint, the
60+
Stripe API endpoint is the same for test and for live.
61+
5362
## Support
5463

5564
If you are having general issues with Omnipay, we suggest posting on

‎makedoc.sh

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
#!/bin/sh
2+
3+
#
4+
# Smart little documentation generator.
5+
# GPL/LGPL
6+
# (c) Del 2015 http://www.babel.com.au/
7+
#
8+
9+
APPNAME='Omnipay Stripe Gateway Module'
10+
CMDFILE=apigen.cmd.$$
11+
DESTDIR=./documents
12+
13+
#
14+
# Find apigen, either in the path or as a local phar file
15+
#
16+
if [ -f apigen.phar ]; then
17+
APIGEN="php apigen.phar"
18+
19+
else
20+
APIGEN=`which apigen`
21+
if [ ! -f "$APIGEN" ]; then
22+
23+
# Search for phpdoc if apigen is not found.
24+
if [ -f phpDocumentor.phar ]; then
25+
PHPDOC="php phpDocumentor.phar"
26+
27+
else
28+
PHPDOC=`which phpdoc`
29+
if [ ! -f "$PHPDOC" ]; then
30+
echo "Neither apigen nor phpdoc is installed in the path or locally, please install one of them"
31+
echo "see http://www.apigen.org/ or http://www.phpdoc.org/"
32+
exit 1
33+
fi
34+
fi
35+
fi
36+
fi
37+
38+
#
39+
# As of version 4 of apigen need to use the generate subcommand
40+
#
41+
if [ ! -z "$APIGEN" ]; then
42+
APIGEN="$APIGEN generate"
43+
fi
44+
45+
#
46+
# Without any arguments this builds the entire system documentation,
47+
# making the cache file first if required.
48+
#
49+
if [ -z "$1" ]; then
50+
#
51+
# Check to see that the cache has been made.
52+
#
53+
if [ ! -f dirlist.cache ]; then
54+
echo "Making dirlist.cache file"
55+
$0 makecache
56+
fi
57+
58+
#
59+
# Build the apigen/phpdoc command in a file.
60+
#
61+
if [ ! -z "$APIGEN" ]; then
62+
echo "$APIGEN --php --tree --title '$APPNAME API Documentation' --destination $DESTDIR/main \\" > $CMDFILE
63+
cat dirlist.cache | while read dir; do
64+
echo "--source $dir \\" >> $CMDFILE
65+
done
66+
echo "" >> $CMDFILE
67+
68+
elif [ ! -z "$PHPDOC" ]; then
69+
echo "$PHPDOC --sourcecode --title '$APPNAME API Documentation' --target $DESTDIR/main --directory \\" > $CMDFILE
70+
cat dirlist.cache | while read dir; do
71+
echo "${dir},\\" >> $CMDFILE
72+
done
73+
echo "" >> $CMDFILE
74+
75+
else
76+
"Neither apigen nor phpdoc are found, how did I get here?"
77+
exit 1
78+
fi
79+
80+
#
81+
# Run the apigen command
82+
#
83+
rm -rf $DESTDIR/main
84+
mkdir -p $DESTDIR/main
85+
. ./$CMDFILE
86+
87+
/bin/rm -f ./$CMDFILE
88+
89+
#
90+
# The "makecache" argument causes the script to just make the cache file
91+
#
92+
elif [ "$1" = "makecache" ]; then
93+
echo "Find application source directories"
94+
find src -name \*.php -print | \
95+
(
96+
while read file; do
97+
grep -q 'class' $file && dirname $file
98+
done
99+
) | sort -u | \
100+
grep -v -E 'config|docs|migrations|phpunit|test|Test|views|web' > dirlist.app
101+
102+
echo "Find vendor source directories"
103+
find vendor -name \*.php -print | \
104+
(
105+
while read file; do
106+
grep -q 'class' $file && dirname $file
107+
done
108+
) | sort -u | \
109+
grep -v -E 'config|docs|migrations|phpunit|codesniffer|test|Test|views' > dirlist.vendor
110+
111+
#
112+
# Filter out any vendor directories for which apigen fails
113+
#
114+
echo "Filter source directories"
115+
mkdir -p $DESTDIR/tmp
116+
cat dirlist.app dirlist.vendor | while read dir; do
117+
if [ ! -z "$APIGEN" ]; then
118+
$APIGEN --quiet --title "Test please ignore" \
119+
--source $dir \
120+
--destination $DESTDIR/tmp && (
121+
echo "Including $dir"
122+
echo $dir >> dirlist.cache
123+
) || (
124+
echo "Excluding $dir"
125+
)
126+
127+
elif [ ! -z "$PHPDOC" ]; then
128+
$PHPDOC --quiet --title "Test please ignore" \
129+
--directory $dir \
130+
--target $DESTDIR/tmp && (
131+
echo "Including $dir"
132+
echo $dir >> dirlist.cache
133+
) || (
134+
echo "Excluding $dir"
135+
)
136+
137+
fi
138+
done
139+
echo "Documentation cache dirlist.cache built OK"
140+
141+
#
142+
# Clean up
143+
#
144+
/bin/rm -rf $DESTDIR/tmp
145+
146+
fi

‎src/Gateway.php

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
11
<?php
2+
/**
3+
* Stripe Gateway
4+
*/
25

36
namespace Omnipay\Stripe;
47

@@ -9,6 +12,73 @@
912
/**
1013
* Stripe Gateway
1114
*
15+
* Example:
16+
*
17+
* <code>
18+
* // Create a gateway for the Stripe Gateway
19+
* // (routes to GatewayFactory::create)
20+
* $gateway = Omnipay::create('Stripe');
21+
*
22+
* // Initialise the gateway
23+
* $gateway->initialize(array(
24+
* 'apiKey' => 'MyApiKey',
25+
* ));
26+
*
27+
* // Create a credit card object
28+
* // This card can be used for testing.
29+
* $card = new CreditCard(array(
30+
* 'firstName' => 'Example',
31+
* 'lastName' => 'Customer',
32+
* 'number' => '4242424242424242',
33+
* 'expiryMonth' => '01',
34+
* 'expiryYear' => '2020',
35+
* 'cvv' => '123',
36+
* 'email' => '[email protected]',
37+
* 'billingAddress1' => '1 Scrubby Creek Road',
38+
* 'billingCountry' => 'AU',
39+
* 'billingCity' => 'Scrubby Creek',
40+
* 'billingPostcode' => '4999',
41+
* 'billingState' => 'QLD',
42+
* ));
43+
*
44+
* // Do a purchase transaction on the gateway
45+
* $transaction = $gateway->purchase(array(
46+
* 'amount' => '10.00',
47+
* 'currency' => 'USD',
48+
* 'card' => $card,
49+
* ));
50+
* $response = $transaction->send();
51+
* if ($response->isSuccessful()) {
52+
* echo "Purchase transaction was successful!\n";
53+
* $sale_id = $response->getTransactionReference();
54+
* echo "Transaction reference = " . $sale_id . "\n";
55+
* }
56+
* </code>
57+
*
58+
* Test modes:
59+
*
60+
* Stripe accounts have test-mode API keys as well as live-mode
61+
* API keys. These keys can be active at the same time. Data
62+
* created with test-mode credentials will never hit the credit
63+
* card networks and will never cost anyone money.
64+
*
65+
* Unlike some gateways, there is no test mode endpoint separate
66+
* to the live mode endpoint, the Stripe API endpoint is the same
67+
* for test and for live.
68+
*
69+
* Setting the testMode flag on this gateway has no effect. To
70+
* use test mode just use your test mode API key.
71+
*
72+
* You can use any of the cards listed at https://stripe.com/docs/testing
73+
* for testing.
74+
*
75+
* Authentication:
76+
*
77+
* Authentication is by means of a single secret API key set as
78+
* the apiKey parameter when creating the gateway object.
79+
*
80+
* @see \Omnipay\Common\AbstractGateway
81+
* @see \Omnipay\Stripe\Message\AbstractRequest
1282
* @link https://stripe.com/docs/api
1383
*/
1484
class Gateway extends AbstractGateway

‎src/Message/AbstractRequest.php

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,60 @@
11
<?php
2+
/**
3+
* Stripe Abstract Request
4+
*/
25

36
namespace Omnipay\Stripe\Message;
47

58
/**
69
* Stripe Abstract Request
710
*
11+
* This is the parent class for all Stripe requests.
12+
*
13+
* Test modes:
14+
*
15+
* Stripe accounts have test-mode API keys as well as live-mode
16+
* API keys. These keys can be active at the same time. Data
17+
* created with test-mode credentials will never hit the credit
18+
* card networks and will never cost anyone money.
19+
*
20+
* Unlike some gateways, there is no test mode endpoint separate
21+
* to the live mode endpoint, the Stripe API endpoint is the same
22+
* for test and for live.
23+
*
24+
* Setting the testMode flag on this gateway has no effect. To
25+
* use test mode just use your test mode API key.
26+
*
27+
* You can use any of the cards listed at https://stripe.com/docs/testing
28+
* for testing.
29+
*
30+
* @see \Omnipay\Stripe\Gateway
31+
* @link https://stripe.com/docs/api
832
* @method \Omnipay\Stripe\Message\Response send()
933
*/
1034
abstract class AbstractRequest extends \Omnipay\Common\Message\AbstractRequest
1135
{
36+
/**
37+
* Live or Test Endpoint URL
38+
*
39+
* @var string URL
40+
*/
1241
protected $endpoint = 'https://api.stripe.com/v1';
1342

43+
/**
44+
* Get the gateway API Key
45+
*
46+
* @return string
47+
*/
1448
public function getApiKey()
1549
{
1650
return $this->getParameter('apiKey');
1751
}
1852

53+
/**
54+
* Set the gateway API Key
55+
*
56+
* @return AbstractRequest provides a fluent interface.
57+
*/
1958
public function setApiKey($value)
2059
{
2160
return $this->setParameter('apiKey', $value);
@@ -49,6 +88,13 @@ public function setMetadata($value)
4988

5089
abstract public function getEndpoint();
5190

91+
/**
92+
* Get HTTP Method.
93+
*
94+
* This is nearly always POST but can be over-ridden in sub classes.
95+
*
96+
* @return string
97+
*/
5298
public function getHttpMethod()
5399
{
54100
return 'POST';
@@ -79,6 +125,16 @@ function ($event) {
79125
return $this->response = new Response($this, $httpResponse->json());
80126
}
81127

128+
/**
129+
* Get the card data.
130+
*
131+
* Because the stripe gateway uses a common format for passing
132+
* card data to the API, this function can be called to get the
133+
* data from the associated card object in the format that the
134+
* API requires.
135+
*
136+
* @return array
137+
*/
82138
protected function getCardData()
83139
{
84140
$this->getCard()->validate();

0 commit comments

Comments
 (0)