Merge pull request #43 from delatbabel/update-create-documentation

Clarify docblocks

.gitignore

@@ -5,3 +5,4 @@ phpunit.xml
 .directory
 /dirlist.*
 /documents/
+/.idea/

src/Message/CreateCardRequest.php

@@ -20,7 +20,9 @@
  * response in that case will then contain both a customer token
  * and a card token, and is essentially the same as CreateCustomerRequest
  *
- * Example.  This example assumes that you have already created a
+ * ### Example
+ *
+ * This example assumes that you have already created a
  * customer, and that the customer reference is stored in $customer_id.
  * See CreateCustomerRequest for the first part of this transaction.
  *

src/Message/CreateCustomerRequest.php

@@ -14,49 +14,69 @@
  * You can retrieve individual customers as well as a list of all of
  * your customers.
  *
- * Example:
+ * ### Examples
+ *
+ * #### Create Customer from Email Address
+ *
+ * This is the recommended way to create a customer object.
  *
  * <code>
- *   // Create a gateway for the Stripe Gateway
- *   // (routes to GatewayFactory::create)
- *   $gateway = Omnipay::create('Stripe');
+ * $response = $gateway->createCustomer(array(
+ *     'description'       => 'Test Customer',
+ *     'email'             => '[email protected]',
+ * ))->send();
+ * if ($response->isSuccessful()) {
+ *     echo "Gateway createCustomer was successful.\n";
+ *     // Find the card ID
+ *     $customer_id = $response->getCustomerReference();
+ *     echo "Customer ID = " . $customer_id . "\n";
+ * } else {
+ *     echo "Gateway createCustomer failed.\n";
+ *     echo "Error message == " . $response->getMessage() . "\n";
+ * }
+ * </code>
  *
- *   // Initialise the gateway
- *   $gateway->initialize(array(
- *       'apiKey' => 'MyApiKey',
- *   ));
+ * The $customer_id can now be used in a createCard() call.
  *
- *   // Create a credit card object
- *   // This card can be used for testing.
- *   // The CreditCard object is also used for creating customers.
- *   $card = new CreditCard(array(
- *               'firstName'    => 'Example',
- *               'lastName'     => 'Customer',
- *               'number'       => '4242424242424242',
- *               'expiryMonth'  => '01',
- *               'expiryYear'   => '2020',
- *               'cvv'          => '123',
- *               'email'                 => '[email protected]',
- *               'billingAddress1'       => '1 Scrubby Creek Road',
- *               'billingCountry'        => 'AU',
- *               'billingCity'           => 'Scrubby Creek',
- *               'billingPostcode'       => '4999',
- *               'billingState'          => 'QLD',
- *   ));
+ * #### Create Customer using Card Object
+ *
+ * Historically, this library used a card object to create customers.
+ * Although this is no longer the recommended path, it is still supported.
+ * Using this approach, a customer object and a card object can be created
+ * at the same time.
+ *
+ * <code>
+ * // Create a credit card object
+ * // This card can be used for testing.
+ * // The CreditCard object is also used for creating customers.
+ * $card = new CreditCard(array(
+ *             'firstName'    => 'Example',
+ *             'lastName'     => 'Customer',
+ *             'number'       => '4242424242424242',
+ *             'expiryMonth'  => '01',
+ *             'expiryYear'   => '2020',
+ *             'cvv'          => '123',
+ *             'email'                 => '[email protected]',
+ *             'billingAddress1'       => '1 Scrubby Creek Road',
+ *             'billingCountry'        => 'AU',
+ *             'billingCity'           => 'Scrubby Creek',
+ *             'billingPostcode'       => '4999',
+ *             'billingState'          => 'QLD',
+ * ));
  *
- *   // Do a create customer transaction on the gateway
- *   $response = $gateway->createCustomer(array(
- *       'card'                     => $card,
- *   ))->send();
- *   if ($response->isSuccessful()) {
- *       echo "Gateway createCustomer was successful.\n";
- *       // Find the customer ID
- *       $customer_id = $response->getCustomerReference();
- *       echo "Customer ID = " . $customer_id . "\n";
- *       // Find the card ID
- *       $card_id = $response->getCardReference();
- *       echo "Card ID = " . $card_id . "\n";
- *   }
+ * // Do a create customer transaction on the gateway
+ * $response = $gateway->createCustomer(array(
+ *     'card'                     => $card,
+ * ))->send();
+ * if ($response->isSuccessful()) {
+ *     echo "Gateway createCustomer was successful.\n";
+ *     // Find the customer ID
+ *     $customer_id = $response->getCustomerReference();
+ *     echo "Customer ID = " . $customer_id . "\n";
+ *     // Find the card ID
+ *     $card_id = $response->getCardReference();
+ *     echo "Card ID = " . $card_id . "\n";
+ * }
  * </code>
  *
  * @link https://stripe.com/docs/api#customers