Permalink
Browse files

Merge pull request #56 from kevinburke/catch-missing-require

Add additional documentation for common error cases
  • Loading branch information...
2 parents e458183 + de19c88 commit 7e043e5f16178e93cc15db524e5251f0189b034f @kyleconroy kyleconroy committed Apr 21, 2012
Showing with 153 additions and 94 deletions.
  1. +152 −0 docs/faq.rst
  2. +1 −0 docs/index.rst
  3. +0 −94 docs/usage/rest.rst
View
@@ -0,0 +1,152 @@
+==========================
+Frequently Asked Questions
+==========================
+
+Hopefully you can find an answer here to one of your questions. If not, please
+contact `help@twilio.com <mailto:help@twilio.com>`_.
+
+require: Failed to open stream messages
+-----------------------------------------
+
+If you are trying to use the helper library and you get an error message that
+looks like this:
+
+.. code-block:: php
+
+ PHP Warning: require(Services/Twilio.php): failed to open stream: No such
+ file or directory in /path/to/file
+
+ Fatal error: require(): Failed opening required 'Services/Twilio.php'
+ (include_path='.:/usr/lib/php:/usr/local/php-5.3.8/lib/php') in
+ /Library/Python/2.6/site-packages/phpsh/phpsh.php(578): on line 1
+
+Your PHP file can't find the Twilio library. The easiest way to do this is to
+move the Services folder from the twilio-php library into the folder containing
+your file. So if you have a file called ``send-sms.php``, your folder structure
+should look like this:
+
+.. code-block:: bash
+
+ .
+ ├── send-sms.php
+ ├── Services
+ │   ├── Twilio.php
+ │   ├── Twilio
+ │   │   ├── ArrayDataProxy.php
+ │   │   ├── (..about 50 other files...)
+
+If you need to copy all of these files to your web hosting server, the easiest
+way is to compress them into a ZIP file, copy that to your server with FTP, and
+then unzip it back into a folder in your CPanel or similar.
+
+You could also try downloading the library via PEAR, a package manager for PHP,
+which will add the library to your PHP path, so you can load the Twilio library
+from anywhere. Run this at the command line:
+
+.. code-block:: bash
+
+ $ pear channel-discover twilio.github.com/pear
+ $ pear install twilio/Services_Twilio
+
+If you get the following message:
+
+.. code-block:: bash
+
+ $ -bash: pear: command not found
+
+you can install PEAR from their website.
+
+SSL Validation Exceptions
+-------------------------
+
+If you are using an outdated version of `libcurl`, you may encounter
+SSL validation exceptions. If you see the following error message, you have
+a SSL validation exception: ::
+
+ Fatal error: Uncaught exception 'Services_Twilio_TinyHttpException'
+ with message 'SSL certificate problem, verify that the CA cert is OK.
+
+ Details: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate
+ verify failed' in [MY PATH]\Services\Twilio\TinyHttp.php:89
+
+This means that Twilio is trying to offer a certificate to verify that you are
+actually connecting to `https://api.twilio.com <https://api.twilio.com>`_, but
+your curl client cannot verify our certificate.
+
+There are four solutions to this problem:
+
+Upgrade your version of the twilio-php library
+==============================================
+
+Since November 2011, the SSL certificate has been built in to the helper
+library, and it is used to sign requests made to our API. If you are still
+encountering this problem, you can upgrade your helper library to the latest
+version, and you should not encounter this error anymore.
+
+If you are using an older version of the helper library, you can try one of the
+following three methods:
+
+Upgrade your version of libcurl
+===============================
+
+The Twilio certificate is included in the latest version of the
+``libcurl`` library. Upgrading your system version of ``libcurl`` will
+resolve the SSL error. `Click here to download the latest version of
+libcurl <http://curl.haxx.se/download.html>`_.
+
+Manually add Twilio's SSL certificate
+=====================================
+
+The PHP curl library can also manually verify an SSL certificate. In your
+browser, navigate to
+`https://github.com/twilio/twilio-php/blob/master/Services/twilio_ssl_certificate.crt
+<https://github.com/twilio/twilio-php/blob/master/Services/twilio_ssl_certificate.crt>`_
+and download the file. (**Note**: If your browser presents ANY warnings
+at this time, your Internet connection may be compromised. Do not download the
+file, and do not proceed with this step). Place this file in the same folder as
+your PHP script. Then, replace this line in your script:
+
+.. code-block:: php
+
+ $client = new Services_Twilio($sid, $token);
+
+with this one:
+
+.. code-block:: php
+
+ $http = new Services_Twilio_TinyHttp(
+ 'https://api.twilio.com',
+ array('curlopts' => array(
+ CURLOPT_SSL_VERIFYPEER => true,
+ CURLOPT_SSL_VERIFYHOST => 2,
+ CURLOPT_CAINFO => getcwd() . "/twilio_ssl_certificate.crt")));
+
+ $client = new Services_Twilio($sid, $token, "2010-04-01", $http);
+
+Disable certificate checking
+============================
+
+A final option is to disable checking the certificate. Disabling the
+certificate check means that a malicious third party can pretend to be
+Twilio, intercept your data, and gain access to your Account SID and
+Auth Token in the process. Because this is a security vulnerability,
+we **strongly discourage** you from disabling certificate checking in
+a production environment. This is known as a `man-in-the-middle attack
+<http://en.wikipedia.org/wiki/Man-in-the-middle_attack>`_.
+
+If you still want to proceed, here is code that will disable certificate
+checking:
+
+.. code-block:: php
+
+ $http = new Services_Twilio_TinyHttp(
+ 'https://api.twilio.com',
+ array('curlopts' => array(CURLOPT_SSL_VERIFYPEER => false))
+ );
+
+ $client = new Services_Twilio('AC123', 'token', '2010-04-01', $http);
+
+If this does not work, double check your Account SID, token, and that you do
+not have errors anywhere else in your code. If you need further assistance,
+please email our customer support at `help@twilio.com`_.
+
View
@@ -122,6 +122,7 @@ TwiML and other utilities
usage/twiml
usage/validation
usage/token-generation
+ faq/
API Documentation
==================
View
@@ -86,97 +86,3 @@ requests.
$participant = $client->account->conferences
->get("CO123")->participants->get("PF123");
-SSL Validation Exceptions
-=========================
-
-If you are using an outdated version of `libcurl`, you may encounter
-SSL validation exceptions. If you see the following error message, you have
-a SSL validation exception: ::
-
- Fatal error: Uncaught exception 'Services_Twilio_TinyHttpException'
- with message 'SSL certificate problem, verify that the CA cert is OK.
-
- Details: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate
- verify failed' in [MY PATH]\Services\Twilio\TinyHttp.php:89
-
-This means that Twilio is trying to offer a certificate to verify that you are
-actually connecting to `https://api.twilio.com <https://api.twilio.com>`_, but
-your curl client cannot verify our certificate.
-
-There are four solutions to this problem.
-
-Upgrade your version of the twilio-php library
-----------------------------------------------
-
-Since November 2011, the SSL certificate has been built in to the helper
-library, and it is used to sign requests made to our API. If you are still
-encountering this problem, you can upgrade your helper library to the latest
-version, and you should not encounter this error anymore.
-
-If you are using an older version of the helper library, you can try one of the
-following three methods:
-
-Upgrade your version of libcurl
--------------------------------
-
-The Twilio certificate is included in the latest version of the
-``libcurl`` library. Upgrading your system version of ``libcurl`` will
-resolve the SSL error. `Click here to download the latest version of
-libcurl <http://curl.haxx.se/download.html>`_.
-
-Manually add Twilio's SSL certificate
--------------------------------------
-
-The PHP curl library can also manually verify an SSL certificate. In your
-browser, navigate to
-`https://github.com/twilio/twilio-php/blob/master/Services/twilio_ssl_certificate.crt
-<https://github.com/twilio/twilio-php/blob/master/Services/twilio_ssl_certificate.crt>`_
-and download the file. (**Note**: If your browser presents ANY warnings
-at this time, your Internet connection may be compromised. Do not download the
-file, and do not proceed with this step). Place this file in the same folder as
-your PHP script. Then, replace this line in your script:
-
-.. code-block:: php
-
- $client = new Services_Twilio($sid, $token);
-
-with this one:
-
-.. code-block:: php
-
- $http = new Services_Twilio_TinyHttp(
- 'https://api.twilio.com',
- array('curlopts' => array(
- CURLOPT_SSL_VERIFYPEER => true,
- CURLOPT_SSL_VERIFYHOST => 2,
- CURLOPT_CAINFO => getcwd() . "/twilio_ssl_certificate.crt")));
-
- $client = new Services_Twilio($sid, $token, "2010-04-01", $http);
-
-Disable certificate checking
-----------------------------
-
-A final option is to disable checking the certificate. Disabling the
-certificate check means that a malicious third party can pretend to be
-Twilio, intercept your data, and gain access to your Account SID and
-Auth Token in the process. Because this is a security vulnerability,
-we **strongly discourage** you from disabling certificate checking in
-a production environment. This is known as a `man-in-the-middle attack
-<http://en.wikipedia.org/wiki/Man-in-the-middle_attack>`_.
-
-If you still want to proceed, here is code that will disable certificate
-checking:
-
-.. code-block:: php
-
- $http = new Services_Twilio_TinyHttp(
- 'https://api.twilio.com',
- array('curlopts' => array(CURLOPT_SSL_VERIFYPEER => false))
- );
-
- $client = new Services_Twilio('AC123', 'token', '2010-04-01', $http);
-
-If this does not work, double check your Account SID, token, and that you do
-not have errors anywhere else in your code. If you need further assistance,
-please email our customer support at `help@twilio.com`_.
-

0 comments on commit 7e043e5

Please sign in to comment.