docs: consolidate (#775)

* docs: migrate custom http client example from docs

* docs: consolidate docs information with README.md

* docs: add hardcoded credentials warning

* chore: remove old docs reference

CONTRIBUTING.md

@@ -22,7 +22,7 @@ it can be.
 ## <a name="question"></a> Got an API/Product Question or Problem?
 
 If you have questions about how to use `twilio-php`, please see our
-[docs][docs-link], and if you don't find the answer there, please contact
+[docs](./README.md), and if you don't find the answer there, please contact
 [help@twilio.com](mailto:help@twilio.com) with any issues you have.
 
 ## <a name="issue"></a> Found an Issue?
@@ -81,10 +81,6 @@ you're working on.
 For large fixes, please build and test the documentation before submitting the
 PR to be sure you haven't accidentally introduced layout or formatting issues.
 
-If you want to help improve the docs at
-[https://www.twilio.com/docs/libraries/php][docs-link], please contact
-[help@twilio.com](mailto:help@twilio.com).
-
 ## <a name="submit"></a> Submission Guidelines
 
 ### Submitting an Issue
@@ -182,6 +178,5 @@ Sample simple workflow:
 
 Tested versions: 7.1.32, 7.2.22, 7.3.9 and 7.4-rc. A complete list of supported PHP versions can be found at the [Docker docs page](https://docs.docker.com/samples/library/php).
 
-[docs-link]: https://www.twilio.com/docs/libraries/php
 [issue-link]: https://github.com/twilio/twilio-php/issues/new
 [github]: https://github.com/twilio/twilio-php

README.md

@@ -20,93 +20,176 @@ The PHP library documentation can be found [here][libdocs].
 
 This library supports the following PHP implementations:
 
-* PHP 7.2
-* PHP 7.3
-* PHP 7.4
-* PHP 8.0
-* PHP 8.1
+- PHP 7.2
+- PHP 7.3
+- PHP 7.4
+- PHP 8.0
+- PHP 8.1
 
 ## Installation
 
-You can install **twilio-php** via composer or by downloading the source.
+You can install `twilio-php` via [composer](https://getcomposer.org/) or by downloading the source.
 
-### Via Composer:
+### Via Composer
 
-**twilio-php** is available on Packagist as the
-[`twilio/sdk`](https://packagist.org/packages/twilio/sdk) package:
+`twilio-php` is available on Packagist as the [`twilio/sdk`](https://packagist.org/packages/twilio/sdk) package:
 
-```
+```shell
 composer require twilio/sdk
 ```
 
-## Quickstart
+### Test your installation
 
-### Send an SMS
+Here is an example of using the SDK to send a text message:
 
 ```php
 // Send an SMS using Twilio's REST API and PHP
 <?php
-$sid = "ACXXXXXX"; // Your Account SID from www.twilio.com/console
-$token = "YYYYYY"; // Your Auth Token from www.twilio.com/console
+// Required if your environment does not handle autoloading
+require __DIR__ . '/vendor/autoload.php';
 
+// Your Account SID and Auth Token from console.twilio.com
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
 $client = new Twilio\Rest\Client($sid, $token);
-$message = $client->messages->create(
-  '8881231234', // Text this number
-  [
-    'from' => '9991231234', // From a valid Twilio number
-    'body' => 'Hello from Twilio!'
-  ]
+
+// Use the Client to make requests to the Twilio REST API
+$client->messages->create(
+    // The number you'd like to send the message to
+    '+15558675309',
+    [
+        // A Twilio phone number you purchased at https://console.twilio.com
+        'from' => '+15017250604',
+        // The body of the text message you'd like to send
+        'body' => "Hey Jenny! Good luck on the bar exam!"
+    ]
 );
+```
 
-print $message->sid;
+### Without Composer
+
+While we recommend using a package manager to track the dependencies in your application, it is possible to download and use the PHP SDK manually. You can download the full source of the PHP SDK from GitHub, and browse the repo if you would like. To use the SDK in your application, unzip the SDK download file in the same directory as your PHP code. In your code, you can then require the autoload file bundled with the SDK.
+
+```php
+<?php
+// Require the bundled autoload file - the path may need to change
+// based on where you downloaded and unzipped the SDK
+require __DIR__ . '/twilio-php-main/src/Twilio/autoload.php';
+
+// Your Account SID and Auth Token from console.twilio.com
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
+$client = new Twilio\Rest\Client($sid, $token);
+
+// Use the Client to make requests to the Twilio REST API
+$client->messages->create(
+    // The number you'd like to send the message to
+    '+15558675309',
+    [
+        // A Twilio phone number you purchased at https://console.twilio.com
+        'from' => '+15017250604',
+        // The body of the text message you'd like to send
+        'body' => "Hey Jenny! Good luck on the bar exam!"
+    ]
+);
 ```
 
+## Usage
+
 ### Make a Call
 
 ```php
 <?php
-$sid = "ACXXXXXX"; // Your Account SID from www.twilio.com/console
-$token = "YYYYYY"; // Your Auth Token from www.twilio.com/console
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
 
 $client = new Twilio\Rest\Client($sid, $token);
 
 // Read TwiML at this URL when a call connects (hold music)
 $call = $client->calls->create(
-  '8881231234', // Call this number
-  '9991231234', // From a valid Twilio number
-  [
-      'url' => 'https://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient'
-  ]
+    '8881231234',
+    // Call this number
+    '9991231234',
+    // From a valid Twilio number
+    [
+        'url' => 'https://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient'
+    ]
 );
 ```
 
+> **Warning**
+> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.
+
+### Get an existing Call
+
+```php
+<?php
+require_once '/path/to/vendor/autoload.php';
+
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
+$client = new Twilio\Rest\Client($sid, $token);
+
+// Get an object using its SID. If you do not have a SID,
+// check out the list resource examples on this page
+$call = $client->calls("CA42ed11f93dc08b952027ffbc406d0868")->fetch();
+print $call->to;
+```
+
+### Iterate through records
+
+The library automatically handles paging for you. Collections, such as `calls` and `messages`, have `read` and `stream` methods that page under the hood. With both `read` and `stream`, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`pageSize`). The library will then handle the task for you.
+
+`read` eagerly fetches all records and returns them as a list, whereas `stream` returns an iterator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the `page` method.
+
+For more information about these methods, view the [auto-generated library docs](https://www.twilio.com/docs/libraries/reference/twilio-php/).
+
+### Use the `read` method
+
+```php
+<?php
+require_once '/path/to/vendor/autoload.php';
+
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
+$client = new Twilio\Rest\Client($sid, $token);
+
+// Loop over the list of calls and print a property from each one
+foreach ($client->calls->read() as $call) {
+    print $call->direction;
+}
+```
+
 ### Specify Region and/or Edge
 
 To take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client:
 
 ```php
 <?php
-$sid = "ACXXXXXX"; // Your Account SID from www.twilio.com/console
-$token = "YYYYYY"; // Your Auth Token from www.twilio.com/console
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
 
 $client = new Twilio\Rest\Client($sid, $token, null, 'au1');
 $client->setEdge('sydney');
 ```
+
 A `Client` constructor without these parameters will also look for `TWILIO_REGION` and `TWILIO_EDGE` variables inside the current environment.
 
 This will result in the `hostname` transforming from `api.twilio.com` to `api.sydney.au1.twilio.com`.
 
 ### Enable Debug Logging
+
 There are two ways to enable debug logging in the default HTTP client. You can create an environment variable called `TWILIO_LOG_LEVEL` and set it to `debug` or you can set the log level to debug:
+
 ```php
-$sid = "ACXXXXXX"; // Your Account SID from www.twilio.com/console
-$token = "YYYYYY"; // Your Auth Token from www.twilio.com/console
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
 
 $client = new Twilio\Rest\Client($sid, $token);
 $client->setLogLevel('debug');
 ```
 
-### Generating TwiML
+### Generate TwiML
 
 To control phone calls, your application needs to output [TwiML][twiml].
 
@@ -130,15 +213,156 @@ That will output XML that looks like this:
 </Response>
 ```
 
-### Handling Exceptions
+### Handle exceptions
+
+When something goes wrong during client initialization, in an API request, or when creating TwiML, twilio-php will throw an appropriate exception. You should handle these exceptions to keep your application running and avoid unnecessary crashes.
+
+#### The Twilio client
+
+For example, it is possible to get an authentication exception when initiating your client, perhaps with the wrong credentials. This can be handled like so:
+
+```php
+<?php
+require_once('/path/to/twilio-php/Services/Twilio.php');
+
+use Twilio\Exceptions\ConfigurationException;
+use Twilio\Rest\Client;
+
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
+
+// Attempt to create a new Client, but your credentials may contain a typo
+try {
+    $client = new Twilio\Rest\Client($sid, $token);
+} catch (ConfigurationException $e) {
+    // You can `catch` the exception, and perform any recovery method of your choice
+    print $e . getCode();
+}
+
+$call = $client->account->calls
+    ->get("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
+
+print $call->to;
+```
+
+#### CurlClient
+
+When initializing the curl client, you will see an EnvironmentException if curl is not installed on your system.
+
+```php
+<?php
+require_once('/path/to/twilio-php/Services/Twilio.php');
+
+use Twilio\Exceptions\TwilioException;
+use Twilio\Http\CurlClient;
+
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
+$client = new Twilio\Rest\Client($sid, $token);
+
+try {
+    $client = new CurlClient();
+
+    $client->options(
+        'GET',
+        'http://api.twilio.com',
+        array(),
+        array(),
+        array(),
+        $sid,
+        $token
+    );
+} catch (EnvironmentException $e) {
+    print $e . getCode();
+}
+
+print $call->to;
+```
+
+#### TwilioException
+
+`TwilioException` can be used to handle API errors, as shown below. This is the most common exception type that you will most likely use.
+
+```php
+<?php
+require_once('/path/to/twilio-php/Services/Twilio.php');
+
+use Twilio\Exceptions\TwilioException;
+
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
+$client = new Twilio\Rest\Client($sid, $token);
 
-For an example on how to handle exceptions in this helper library, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/php/usage-guide#exceptions).
+try {
+    $call = $client->account->calls
+        ->get("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
+} catch (TwilioException $e) {
+    print $e->getCode();
+}
+
+print $call->to;
+```
+
+### TwimlException
+
+When building [TwiML](https://www.twilio.com/docs/api/twiml) with `twilio-php`, if the result does not conform to what the API expects, you will see a `TwimlException` which you then need to handle like so:
+
+```php
+<?php
+require_once './vendor/autoload.php';
+use Twilio\Twiml;
+
+try {
+    $response = new Twiml();
+    $dial = $response->dial();
+    $dial->conference('Room 1234');
+    print $response;
+} catch (TwimlException $e) {
+    print $e->getCode();
+}
+```
+
+### Debug API requests
+
+To assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default Curl client that ships with the library.
+
+For example, you can retrieve the status code of the last response like so:
+
+```php
+<?php
+$sid = "ACXXXXXX";
+$token = "YYYYYY";
+
+$client = new Twilio\Rest\Client($sid, $token);
+$message = $client->messages->create(
+    '+15558675309',
+    [
+        'from' => '+15017250604',
+        'body' => "Hey Jenny! Good luck on the bar exam!"
+    ]
+);
+
+// Print the message's SID
+print $message->sid;
+
+// Print details about the last request
+print $client->lastRequest->method;
+print $client->lastRequest->url;
+print $client->lastRequest->auth;
+print $client->lastRequest->params;
+print $client->lastRequest->headers;
+print $client->lastRequest->data;
+
+// Print details about the last response
+print $client->lastResponse->statusCode;
+print $client->lastResponse->body;
+```
 
-## Using a Custom HTTP Client
+## Use a custom HTTP Client
 
-To use a custom HTTP client with this helper library, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/php/custom-http-clients-php).
+To use a custom HTTP client with this helper library, please see the [advanced example of how to do so](./advanced-examples/custom-http-client.md).
 
-## Docker Image
+## Docker image
 
 The `Dockerfile` present in this repository and its respective `twilio/twilio-php` Docker image are currently used by Twilio for testing purposes only.