Merge branch 'master' into refactor-make-request-method

Author: thinkingserious

.codeclimate.yml

@@ -0,0 +1,18 @@
+engines:
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - "php"
+  phpcodesniffer:
+    enabled: true
+    config:
+      file_extensions: "php"
+      standard: "PSR1,PSR2"
+ratings:
+  paths:
+  - "**.php"
+exclude_paths:
+  - "examples/**/*"
+  - "test/**/*"
+  - "vendor/**/*"

.travis.yml

@@ -3,7 +3,9 @@ before_script:
 - composer install --dev --no-interaction
 - cd test/unit
 script:
-- ../../vendor/bin/phpunit . --bootstrap bootstrap.php --filter test* --coverage-clover clover.xml
+- ../../vendor/bin/phpunit . --bootstrap bootstrap.php --filter test* --coverage-clover=coverage.xml
+after_success:
+- bash <(curl -s https://codecov.io/bash)
 php:
 - 5.6
 - 7.0
@@ -22,4 +24,4 @@ notifications:
             Build %{build_number}</a> on branch <i>%{branch}</i> by %{author}: <strong>%{message}</strong>
             <a href="https://github.com/%{repository}/commits/%{commit}">View on GitHub</a>'
     format: html
-    notify: true
+    notify: true

CONTRIBUTING.md

@@ -9,6 +9,7 @@ Hello! Thank you for choosing to help contribute to one of the SendGrid open sou
 - [Testing](#testing)
 - [Style Guidelines & Naming Conventions](#style-guidelines-and-naming-conventions)
 - [Creating a Pull Request](#creating-a-pull-request)
+- [Code Reviews](#code-reviews)
 
 <a name="roadmap"></a>
 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.
@@ -74,7 +75,7 @@ git clone https://github.com/sendgrid/php-http-client.git
 cd php-http-client
 ```
 
-## Environment Variables
+### Environment Variables
 
 First, get your free SendGrid account [here](https://sendgrid.com/free?source=php-http-client).
 
@@ -88,7 +89,8 @@ source ./sendgrid.env
 
 ##### Execute: #####
 
-See the [examples folder](https://github.com/sendgrid/php-http-client/tree/master/examples
+See the [examples folder](https://github.com/sendgrid/php-http-client/tree/master/examples).
+
 <a name="understanding-the-codebase"></a>
 ## Understanding the Code Base
 
@@ -138,7 +140,8 @@ Please run your code through:
 
 - [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer)
 
-## Creating a Pull Request<a name="creating-a-pull-request"></a>
+<a name="creating-a-pull-request"></a>
+## Creating a Pull Request
 
 1. [Fork](https://help.github.com/fork-a-repo/) the project, clone your fork,
    and configure the remotes:
@@ -191,4 +194,8 @@ Please run your code through:
 7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
     with a clear title and description against the `master` branch. All tests must be passing before we will review the PR.
 
+<a name="code-reviews"></a>
+## Code Reviews
+If you can, please look at open PRs and review them. Give feedback and help us merge these PRs much faster! If you don't know how, Github has some great [information on how to review a Pull Request](https://help.github.com/articles/about-pull-request-reviews/).
+
 If you have any additional questions, please feel free to [email](mailto:dx@sendgrid.com) us or create an issue in this repo.

Dockerfile

@@ -0,0 +1,13 @@
+FROM php:7.1-apache
+
+ARG sendgrid_apikey
+ENV SENDGRID_API_KEY=$sendgrid_apikey
+
+COPY . /var/www/client
+WORKDIR /var/www/client
+
+RUN apt-get update && \
+    apt-get install -y git zip zlib1g-dev && docker-php-ext-install zip
+RUN curl --silent --show-error https://getcomposer.org/installer | php
+
+RUN php composer.phar install

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 SendGrid, Inc.
+Copyright (c) 2012-2018 SendGrid, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,7 +2,6 @@
 
 [![Travis Badge](https://travis-ci.org/sendgrid/php-http-client.svg?branch=master)](https://travis-ci.org/sendgrid/php-http-client)
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/sendgrid/php-http-client.svg?style=flat-square)](https://packagist.org/packages/sendgrid/php-http-client)
-[![BuildStatus](https://travis-ci.org/sendgrid/php-http-client.svg?branch=master)](https://travis-ci.org/sendgrid/php-http-client)
 [![Email Notifications Badge](https://dx.sendgrid.com/badge/php)](https://dx.sendgrid.com/newsletter/php)
 [![Twitter Follow](https://img.shields.io/twitter/follow/sendgrid.svg?style=social&label=Follow)](https://twitter.com/sendgrid)
 [![GitHub contributors](https://img.shields.io/github/contributors/sendgrid/php-http-client.svg)](https://github.com/sendgrid/php-http-client/graphs/contributors)
@@ -66,7 +65,6 @@ $ cd /path/to/your/app
 $ mkdir lib
 $ cd lib
 $ git clone https://github.com/sendgrid/php-http-client.git
-$ git clone https://github.com/sendgrid/sendgrid-php.git
 ```
 
 In the next step you should create `loader.php`:
@@ -83,8 +81,6 @@ And add to `loader.php` code below:
 
 require_once __DIR__ . '/lib/php-http-client/lib/Client.php';
 require_once __DIR__ . '/lib/php-http-client/lib/Response.php';
-require_once __DIR__ . '/lib/sendgrid-php/lib/SendGrid.php';
-
 ```
 
 After it you can use `php-http-client` library in your project:
@@ -107,36 +103,54 @@ Here is a quick example:
 ```php
 // include __DIR__ . '/loader.php';
 require 'vendor/autoload.php';
-$global_headers = array('Authorization: Basic XXXXXXX');
-$client = new SendGrid\Client('base_url', $global_headers);
+$apiKey = YOUR_SENDGRID_API_KEY;
+$authHeaders = [
+    'Authorization: Bearer ' . $apiKey
+];
+$client = new SendGrid\Client('https://api.sendgrid.com', $authHeaders);
+$param = 'foo';
 $response = $client->your()->api()->_($param)->call()->get();
-print $response->statusCode();
-print $response->headers();
-print $response->body();
+
+var_dump(
+    $response->statusCode(),
+    $response->headers(),
+    $response->body()
+);
 ```
 
 `POST /your/api/{param}/call` with headers, query parameters and a request body with versioning.
 
 ```php
 // include __DIR__ . '/loader.php';
 require 'vendor/autoload.php';
-$global_headers = array('Authorization: Basic XXXXXXX');
-$client = new 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->headers();
-print $response->body();
+$apiKey = YOUR_SENDGRID_API_KEY;
+$authHeaders = [
+    'Authorization: Bearer ' . $apiKey
+];
+$client = new SendGrid\Client('https://api.sendgrid.com', $authHeaders);
+$queryParams = [
+    'hello' => 0, 'world' => 1
+];
+$requestHeaders = [
+    'X-Test' => 'test'
+];
+$data = [
+    'some' => 1, 'awesome' => 2, 'data' => 3
+];
+$param = 'bar';
+$response = $client->your()->api()->_($param)->call()->post($data, $queryParams, $requestHeaders);
+
+var_dump(
+    $response->statusCode(),
+    $response->headers(),
+    $response->body()
+);
 ```
 
 <a name="usage"></a>
 # Usage
 
-- [Example Code](https://github.com/sendgrid/php-http-client/tree/master/examples)
+- [Usage Examples](USAGE.md)
 
 ## Environment Variables 
 
@@ -154,14 +168,15 @@ If you are interested in the future direction of this project, please take a loo
 <a name="contribute"></a>
 # 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.
+We encourage contribution to our libraries, please see our [CONTRIBUTING](https://github.com/sendgrid/php-http-client/blob/master/CONTRIBUTING.md) guide for details.
 
 Quick links:
 
 - [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)
 - [Sign the CLA to Create a Pull Request](https://github.com/sendgrid/php-http-client/blob/master/CONTRIBUTING.md#cla)
 - [Improvements to the Codebase](https://github.com/sendgrid/php-http-client/blob/master/CONTRIBUTING.md#improvements-to-the-codebase)
+- [Review Pull Requests](https://github.com/sendgrid/php-http-client/blob/master/CONTRIBUTING.md#code-reviews)
 
 <a name="thanks"></a>
 # Thanks

USAGE.md

@@ -0,0 +1,109 @@
+# Usage
+
+Usage examples for SendGrid php-http-client
+
+## Initialization
+
+```
+// If running this outside of this context, use the following include and
+// comment out the two includes below
+// require __DIR__ . '/vendor/autoload.php';
+include(dirname(__DIR__) . '/lib/Client.php');
+// This gets the parent directory, for your current directory use getcwd()
+$path_to_config = dirname(__DIR__);
+$apiKey = getenv('SENDGRID_API_KEY');
+$headers = ['Authorization: Bearer ' . $apiKey];
+$client = new SendGrid\Client('https://api.sendgrid.com', $headers, '/v3');
+```
+
+## Table of Contents
+
+- [GET](#get)
+- [DELETE](#delete)
+- [POST](#post)
+- [PUT](#put)
+- [PATCH](#patch)
+
+<a name="get"></a>
+## GET
+
+#### GET Collection
+
+```
+$query_params = ['limit' => 100, 'offset' => 0];
+$request_headers = ['X-Mock: 200'];
+$response = $client->api_keys()->get(null, $query_params, $request_headers);
+echo $response->statusCode();
+echo $response->body();
+echo $response->headers();
+```
+
+#### GET with auto retry on rate limit
+
+```
+$query_params = ['limit' => 100, 'offset' => 0];
+$request_headers = ['X-Mock: 200'];
+$retryOnLimit = true;
+$response = $client->api_keys()->get(null, $query_params, $request_headers, $retryOnLimit);
+echo $response->statusCode();
+echo $response->body();
+echo $response->headers();
+```
+
+<a name="delete"></a>
+## DELETE
+
+```
+$response = $client->api_keys()->_($api_key_id)->delete();
+echo $response->statusCode();
+echo $response->body();
+echo $response->headers();
+```
+
+<a name="post"></a>
+## POST
+
+```
+$request_body = [
+    'name' => 'My PHP API Key',
+    'scopes' => [
+        'mail.send',
+        'alerts.create',
+        'alerts.read'
+    ]
+];
+$response = $client->api_keys()->post($request_body);
+echo $response->statusCode();
+echo $response->body();
+echo $response->headers();
+$response_body = json_decode($response->body());
+$api_key_id = $response_body->api_key_id;
+```
+<a name="put"></a>
+## PUT
+
+```
+$request_body = [
+    'name' => 'A New Hope',
+    'scopes' => [
+        'user.profile.read',
+        'user.profile.update'
+    ]
+];
+$response = $client->api_keys()->_($api_key_id)->put($request_body);
+echo $response->statusCode();
+echo $response->body();
+echo $response->headers();
+```
+<a name="patch"></a>
+## PATCH
+
+```
+$request_body = [
+    'name' => 'A New Hope'
+];
+$response = $client->api_keys()->_($api_key_id)->patch($request_body);
+echo $response->statusCode();
+echo $response->body();
+echo $response->headers();
+```

USE_CASES.md

@@ -0,0 +1,27 @@
+This documentation provides examples for specific use cases. Please [open an issue](https://github.com/sendgrid/php-http-client/issues) or make a pull request for any use cases you would like us to document here. Thank you!
+
+# Table of Contents
+* [Docker](#docker)
+
+<a name="docker"></a>
+# Docker
+
+You can run the example code at `examples/example.php` in a Docker container.
+
+From the root directory:
+
+```bash
+cp examples/.env_sample .env
+```
+
+Update the `.env` file with your SendGrid API Key. If you don't have one, you can get one [here](https://sendgrid.com/free?source=php-http-client).
+
+Add the `.env` file to your `.gitignore` file if you are publishing your code publically.
+
+```
+source .env
+docker build --build-arg sendgrid_apikey=$SENDGRID_API_KEY -t client .
+docker run client php examples/example.php
+```
+
+You should see a list of your SendGrid API Keys.

composer.json

@@ -3,10 +3,6 @@
     "description": "HTTP REST client, simplified for PHP",
     "type": "library",
     "version": "3.8.0",
-    "require-dev": {
-        "phpunit/phpunit": "~4.4",
-        "squizlabs/php_codesniffer": "~2.0"
-    },
     "homepage": "http://github.com/sendgrid/php-http-client",
     "keywords": ["SendGrid", "HTTP", "REST", "API", "Fluent"],
     "license": "MIT",
@@ -23,6 +19,10 @@
     "require": {
         "php": ">=5.6"
     },
+    "require-dev": {
+        "phpunit/phpunit": "~4.4",
+        "squizlabs/php_codesniffer": "~2.0"
+    },
     "autoload": {
         "psr-4": {
             "SendGrid\\": "lib/"