From 65e2ee0cca1577bd8438115fe4f8293d6ac95ec8 Mon Sep 17 00:00:00 2001 From: Elmer Thomas Date: Sun, 20 Mar 2016 15:30:00 -0700 Subject: Preparing for public release --- .travis.yml | 34 ++++++++++++ CONTRIBUTING.md | 91 +++++++++---------------------- README.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++- examples/example.php | 12 ++--- 4 files changed, 211 insertions(+), 74 deletions(-) create mode 100644 .travis.yml diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..f0fb99e --- /dev/null +++ b/.travis.yml @@ -0,0 +1,34 @@ +language: php +before_script: +- phpenv local 5.4 +- composer install --dev --no-interaction +- phpenv local --unset +- cd test/unit +script: +- ../../vendor/bin/phpunit . --bootstrap bootstrap.php --filter test* --coverage-clover clover.xml +after_script: +- cd .. +- phpenv local 5.4 +- phpenv local --unset +php: +- 5.2 +- 5.3 +- 5.4 +- 5.5 +- 5.6 +env: + global: + - secure: eUN0huKA436uIkISu6V3yW01/gZHC6slBvlnprMPEhzclU2szH6qhWEXWS5CcOG6EEDBReqLZdNAwu+FC69KGFO9+6oW2GQQLSsfEViqFi/Ig2N0r4EBO4jLRebgq0GOfetPwQvJH27d8BCiloPy8rXBb5pskxSNw4B4bRyXHz4= + - secure: j38xzMNmzYXR/JJdVumPmDoDVxb6FUDF497AuVPHowGh0egFW8XHWCOMeQWqWZI4Gg17pViQNIJ3xC6WBvob70AF8fsNm0+vxF2s7abXDMcbq5flLTS6ydKLgNu+na/RAkOBbTwxJAGIH/fQh8BH8iGKerCwoqf8sDErAge4NMw= + - secure: h3HlxBOsNXBDrIJ0yl467ST6Q8R2TmbL7PltlPcRoHy5gAxn5UiDv5W2+6DSXrwQrTjOUunZ+O9ckcaQGQy1JNhGMwgIkJpyWAHDIHhTYGU289uUIDTHQW/soX0qHJSHSx3iMgDOIc7XnfTz6W7Nv1gYKZFedOMsZ5uBMeGyiXE= + - secure: SKSl/RHFQNhGT7OUj7E0AbrQnuDhhCRI/4jC76mmzvy8EJBDgUNevAKJGtug+LVilHrlbk9fLC8rayPW6SGv0s3PowTGm8NMOc48aRBLOr7QRo/sMikJCmRuU6HWptr0NKuf2fq6lV94WDm/pDdyOSNyLga9/eaIDs/Sacp78sw= +notifications: + hipchat: + rooms: + secure: l4RUOBY44kVhSxx54NU3cmvn598rRMB7Y272Ct/W0fBm1tdGncp42A/rwg7JkiZH9EWXs3tKtoSjqw5xT6QeScUGQDdykS5QVO8lEIkDRGD4WwQ3VDJmRy1+04WtgqFEK8SyYTCcCl4ZJ0rtOcJZgDMvigkOJuLxwGXTDuvfu1k= + template: + - '%{repository} + Build %{build_number} on branch %{branch} by %{author}: %{message} + View on GitHub' + format: html + notify: true \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db93b1c..2db5438 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,12 @@ -Hello! Thank you for choosing to help contribute to the python-http-client. There are many ways you can contribute and help is always welcome. +Hello! Thank you for choosing to help contribute to the php-http-client. There are many ways you can contribute and help is always welcome. -We use [Milestones](https://github.com/sendgrid/python-http-client/milestones) to help define current roadmaps, please feel free to grab an issue from the current milestone. Please indicate that you have begun work on it to avoid collisions. Once a PR is made, community review, comments, suggestions and additional PRs are welcomed and encouraged. +We use [Milestones](https://github.com/sendgrid/php-http-client/milestones) to help define current roadmaps, please feel free to grab an issue from the current milestone. Please indicate that you have begun work on it to avoid collisions. Once a PR is made, community review, comments, suggestions and additional PRs are welcomed and encouraged. * [Feature Request](#feature_request) * [Submit a Bug Report](#submit_a_bug_report) * [Improvements to the Codebase](#improvements_to_the_codebase) * [Understanding the Code Base](#understanding_the_codebase) * [Testing](#testing) -* [Testing Multiple Versions of Python](#testing_multiple_versoins_of_python) * [Style Guidelines & Naming Conventions](#style_guidelines_and_naming_conventions) * [Creating a Pull Request](#creating_a_pull_request) @@ -58,14 +57,14 @@ Any other information you want to share that is relevant to the issue being repo #### Technical details: -* python-http-client Version: master (latest commit: 2cb34372ef0f31352f7c90015a45e1200cb849da) -* Python Version: 2.7 +* php-http-client Version: master (latest commit: 2cb34372ef0f31352f7c90015a45e1200cb849da) +* PHP Version: 5.6 ``` ## Improvements to the Codebase -We welcome direct contributions to the python-http-client code base. Thank you! +We welcome direct contributions to the php-http-client code base. Thank you! ### Development Environment ### @@ -73,14 +72,14 @@ We welcome direct contributions to the python-http-client code base. Thank you! ##### Prerequisites ##### -* Python 2.6 through 3.5 -* There are no external dependencies +* PHP 5.2 through 5.6 +* [Composer](https://getcomposer.org/) ##### Initial setup: ##### ``` -git clone https://github.com/sendgrid/python-http-client.git -cd python-http-client +git clone https://github.com/sendgrid/php-http-client.git +cd php-http-client cp .env_sample .env ``` @@ -88,7 +87,7 @@ Update your settings in `.env` ##### Execute: ##### -See the [examples folder](https://github.com/sendgrid/python-http-client/tree/master/examples) to get started quickly. +See the [examples folder](https://github.com/sendgrid/php-http-client/tree/master/examples) to get started quickly. ## Understanding the Code Base @@ -97,15 +96,15 @@ See the [examples folder](https://github.com/sendgrid/python-http-client/tree/ma Working examples that demonstrate usage. -**client.py** +**client.php** -An HTTP client with a fluent interface using method chaining and reflection. By returning self on [__getattr__](https://github.com/sendgrid/python-http-client/blob/master/client.py#L74) and [_()](https://github.com/sendgrid/python-http-client/blob/master/client.py#L70), we can dynamically build the URL using method chaining and [__getattr__](https://github.com/sendgrid/python-http-client/blob/master/client.py#L74) allows us to dynamically receive the method calls to achieve reflection. +An HTTP client with a fluent interface using method chaining and reflection. By returning self on [__call](https://github.com/sendgrid/php-http-client/blob/master/lib/client.php#L212) and [_()](https://github.com/sendgrid/php-http-client/blob/master/lib/client.pph#L198), we can dynamically build the URL using method chaining and [__call](https://github.com/sendgrid/php-http-client/blob/master/lib/client.php#L212) allows us to dynamically receive the method calls to achieve reflection. This allows for the following mapping from a URL to a method chain: -`/api_client/{api_key_id}/version` maps to `client.api_client._(api_key_id).version.()` where is a [HTTP verb](https://github.com/sendgrid/python-http-client/blob/master/client.py#L24). +`/api_client/{api_key_id}/version` maps to `client->api_client().->_($api_key_id)->version->()` where is a [HTTP verb](https://github.com/sendgrid/php-http-client/blob/master/lib/client.php#L94). -**congfig.py** +**congfig.php** Loads the environment variables. @@ -114,66 +113,26 @@ Loads the environment variables. All PRs require passing tests before the PR will be reviewed. -All test files are in the `[tests](https://github.com/sendgrid/python-http-client/tree/master/tests)` directory. +All test files are in the `[test/unit](https://github.com/sendgrid/php-http-client/tree/master/test/unit)` directory. -For the purposes of contributing to this repo, please update the [`test_unit.py`](https://github.com/sendgrid/python-http-client/blob/master/tests/test_unit.py) file with unit tests as you modify the code. +For the purposes of contributing to this repo, please update the [`ClientTest.php`](https://github.com/sendgrid/php-http-client/blob/master/test/unit/ClientTest.php) file with unit tests as you modify the code. -For Python 2.6.*: - -`unit2 discover -v` - -For Python 2.7.* and up: - -`python -m unittest discover -v` - - -## Testing Multiple Versions of Python - -All PRs require passing tests before the PR will be reviewed. - -### Prequisites: ### - -The above local "Initial setup" is complete - -* [pyenv](https://github.com/yyuu/pyenv) -* [tox](https://pypi.python.org/pypi/tox) - -### Initial setup: ### - -Add ```eval "$(pyenv init -)"``` to your shell environment (.profile, .bashrc, etc) after installing tox, you only need to do this once. - -``` -pyenv install 2.6.9 -pyenv install 2.7.11 -pyenv install 3.2.6 -pyenv install 3.3.6 -pyenv install 3.4.3 -pyenv install 3.5.0 -python setup.py install -pyenv local 3.5.0 3.4.3 3.3.6 3.2.6 2.7.8 2.6.9 -pyenv rehash -```` - -### Execute: ### - -``` -source venv/bin/activate -tox -``` +`phpunit --bootstrap test/unit/bootstrap.php --filter test* test/unit` ## Style Guidelines & Naming Conventions Generally, we follow the style guidelines as suggested by the official language. However, we ask that you conform to the styles that already exist in the library. If you wish to deviate, please explain your reasoning. -* [PEP8](https://www.python.org/dev/peps/pep-0008/) +* [pear coding standards](https://pear.php.net/manual/en/standards.php) -Please run your code through [pyflakes](https://pypi.python.org/pypi/pyflakes), [pylint](https://www.pylint.org/) and [pep8](https://pypi.python.org/pypi/pep8) +Please run your code through [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) ### Directory Structure -* `examples` for example calls -* `tests`, for all tests +* `examples`, for example calls +* `test\unit`, for all tests +* 'lib`, for source code ## Creating a Pull Request @@ -182,11 +141,11 @@ Please run your code through [pyflakes](https://pypi.python.org/pypi/pyflakes), ```bash # Clone your fork of the repo into the current directory - git clone https://github.com/sendgrid/python-http-client + git clone https://github.com/sendgrid/php-http-client # Navigate to the newly cloned directory - cd python-http-client + cd php-http-client # Assign the original repo to a remote called "upstream" - git remote add upstream https://github.com/sendgrid/python-http-client + git remote add upstream https://github.com/sendgrid/php-http-client ``` 2. If you cloned a while ago, get the latest changes from upstream: diff --git a/README.md b/README.md index 57a5223..97787e0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,146 @@ -# php-http-client -HTTP REST client, simplified for PHP +[![Travis Badge](https://travis-ci.org/sendgrid/php-http-client.svg?branch=master)](https://travis-ci.org/sendgrid/php-http-client) + +**Quickly and easily access any REST or REST-like API.** + +Here is a quick example: + +`GET /your/api/{param}/call` + +```php +require 'vendor/autoload.php'; +$global_headers = array(Authorization: Basic XXXXXXX); +$client = SendGrid\Client('base_url', 'global_headers'); +$response = $client->your()->api()->_($param)->call()->get(); +print $response->statusCode(); +print $response->responseHeaders(); +print $response->responseBody(); +``` + +`POST /your/api/{param}/call` with headers, query parameters and a request body with versioning. + +```php +require 'vendor/autoload.php'; +$global_headers = array(Authorization: Basic XXXXXXX); +$client = SendGrid\Client('base_url', 'global_headers'); +$query_params = array('hello' => 0, 'world' => 1); +$request_headers = array('X-Test' => 'test'); +$data = array('some' => 1, 'awesome' => 2, 'data' => 3); +$response = $client->your()->api()->_($param)->call()->post('data', + 'query_params', + 'request_headers'); +print $response->statusCode(); +print $response->responseHeaders(); +print $response->responseBody(); +``` + +# Installation + +Add php-http-client to your `composer.json` file. If you are not using [Composer](http://getcomposer.org), you should be. It's an excellent way to manage dependencies in your PHP application. + +```json +{ + "require": { + "sendgrid/php-http-client": "~1" + } +} +``` + +Then at the top of your PHP script require the autoloader: + +```bash +require 'vendor/autoload.php'; +``` + +or + +`pear install php-http-client` + +## Usage ## + +Following is an example using SendGrid. You can get your free account [here](https://sendgrid.com/free?source=php-http-client). + +First, update your .env with your [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys) and HOST. For this example HOST=https://api.sendgrid.com. + +Following is an abridged example, here is the [full working code](https://github.com/sendgrid/php-http-client/tree/master/examples). + +```php + 100, 'offset' => 0); +$request_headers = array('X-Mock: 200'); +$response = $client->api_keys()->get(null, $query_params, $request_headers); + +// POST +$request_body = array( + 'name' => 'My PHP API Key', + 'scopes' => array( + 'mail.send', + 'alerts.create', + 'alerts.read' + ) +); +$response = $client->api_keys()->post($request_body); +$response_body = json_decode($response->responseBody()); +$api_key_id = $response_body->api_key_id; + +// GET Single +$response = $client->version('/v3')->api_keys()->_($api_key_id)->get(); + +// PATCH +$request_body = array( + 'name' => 'A New Hope' +); +$response = $client->api_keys()->_($api_key_id)->patch($request_body); + +// PUT +$request_body = array( + 'name' => 'A New Hope', + 'scopes' => array( + 'user.profile.read', + 'user.profile.update' + ) +); +$response = $client->api_keys()->_($api_key_id)->put($request_body); + +// DELETE +$response = $client->api_keys()->_($api_key_id)->delete(); +?> +``` + +# Announcements + +[2016.03.28] - We hit version 1! + +# Roadmap + +[Milestones](https://github.com/sendgrid/php-http-client/milestones) + +# How to Contribute + +We encourage contribution to our libraries, please see our [CONTRIBUTING](https://github.com/sendgrid/php-http-client/blob/master/CONTRIBUTING.md) guide for details. + +* [Feature Request](https://github.com/sendgrid/php-http-client/blob/master/CONTRIBUTING.md#feature_request) +* [Bug Reports](https://github.com/sendgrid/php-http-client/blob/master/CONTRIBUTING.md#submit_a_bug_report) +* [Improvements to the Codebase](https://github.com/sendgrid/php-http-client/blob/master/CONTRIBUTING.md#improvements_to_the_codebase) + +# Thanks + +We were inspired by the work done on [birdy](https://github.com/inueni/birdy) and [universalclient](https://github.com/dgreisen/universalclient). + +# About + +![SendGrid Logo] +(https://assets3.sendgrid.com/mkt/assets/logos_brands/small/sglogo_2015_blue-9c87423c2ff2ff393ebce1ab3bd018a4.png) + +php-http-client is guided and supported by the SendGrid [Developer Experience Team](mailto:dx@sendgrid.com). + +php-http-client is maintained and funded by SendGrid, Inc. The names and logos for python-http-client are trademarks of SendGrid, Inc. diff --git a/examples/example.php b/examples/example.php index 590382b..3a90c69 100644 --- a/examples/example.php +++ b/examples/example.php @@ -9,7 +9,7 @@ $headers = array( ); $client = new SendGrid\Client('https://e9sk3d3bfaikbpdq7.stoplight-proxy.io', $headers, '/v3', null); -# GET Collection +// GET Collection $query_params = array('limit' => 100, 'offset' => 0); $request_headers = array('X-Mock: 200'); $response = $client->api_keys()->get(null, $query_params, $request_headers); @@ -17,7 +17,7 @@ echo $response->statusCode(); echo $response->responseBody(); echo $response->responseHeaders(); -# POST +// POST $request_body = array( 'name' => 'My PHP API Key', 'scopes' => array( @@ -33,13 +33,13 @@ echo $response->responseHeaders(); $response_body = json_decode($response->responseBody()); $api_key_id = $response_body->api_key_id; -# GET Single +// GET Single $response = $client->version('/v3')->api_keys()->_($api_key_id)->get(); echo $response->statusCode(); echo $response->responseBody(); echo $response->responseHeaders(); -# PATCH +// PATCH $request_body = array( 'name' => 'A New Hope' ); @@ -48,7 +48,7 @@ echo $response->statusCode(); echo $response->responseBody(); echo $response->responseHeaders(); -# PUT +// PUT $request_body = array( 'name' => 'A New Hope', 'scopes' => array( @@ -61,7 +61,7 @@ echo $response->statusCode(); echo $response->responseBody(); echo $response->responseHeaders(); -# DELETE +// DELETE $response = $client->api_keys()->_($api_key_id)->delete(); echo $response->statusCode(); echo $response->responseBody(); -- cgit v1.1