<commit_before># Omniphx/Forrest, Force.com REST API Client for Laravel 5
[![Laravel](https://img.shields.io/badge/Laravel-5.0-orange.svg?style=flat-square)](http://laravel.com)
[![Latest Stable Version](https://img.shields.io/packagist/v/omniphx/forrest.svg?style=flat-square)](https://packagist.org/packages/omniphx/forrest)
[![Total Downloads](https://img.shields.io/packagist/dt/omniphx/forrest.svg?style=flat-square)](https://packagist.org/packages/omniphx/forrest)
[![License](https://img.shields.io/packagist/l/omniphx/forrest.svg?style=flat-square)](https://packagist.org/packages/omniphx/forrest)
[![Build Status](https://img.shields.io/travis/omniphx/forrest.svg?style=flat-square)](https://travis-ci.org/omniphx/forrest)

Salesforce/Force.com REST API client for Laravel. It provides access to restricted Salesforce information via Oauth 2.0. REST is a lightweight alternative to the SOAP API and is useful for mobile users.

While this package is built for Laravel, it has been decoupled so that it can be extended into any framework or vanilla PHP application.

## Installation
>If you are upgrading to Version 2.0, be sure to re-publish your config file.

Forrest can be installed through composer. Open your `composer.json` file and add the following to the `require` key:

    "omniphx/forrest": "2.*"

Next run `composer update` from the command line to install the package.

If you are using Laravel, add the service provider and alias to your `bootstrap/app.php` file:

    'Omniphx\Forrest\Providers\Laravel\ForrestServiceProvider'

    'Forrest' => 'Omniphx\Forrest\Providers\Laravel\Facades\Forrest'

>For Laravel 4, add `Omniphx\Forrest\Providers\Laravel4\ForrestServiceProvider` in `app/config/app.php`. Alias will remain the same.

### Configuration
You will need a configuration file to add your credentials. Publish a config file using the `artisan` command:
```bash
php artisan vendor:publish
```
You can find the config file in: `config/forrest.php`

>For Laravel 4, run `php artisan config:publish omniphx/forrest`. It will be found in `app/config/omniphx/forrest/config.php`

## Getting Started
### Setting up a Connected App
1. Log into to your Salesforce org
2. Click on Setup in the upper right-hand menu
3. Under Build click `Create > Apps`
4. Scroll to the bottom and click `New` under Connected Apps.
5. Enter the following details for the remote application:
    * Connected App Name
    * API Name
    * Contact Email
    * Enable OAuth Settings under the API dropdown
    * Callback URL
    * Select access scope (If you need a refresh token, specify it here)
6. Click `Save`

After saving, you will now be given a Consumer Key and Consumer Secret. Update your config file with values for `consumerKey`, `consumerSecret`, `loginURL` and `callbackURI`.

### Setup
Forrest will come with the following routes included in it's package.

>Feel free to overwrite these in your `routes.php` file. Your routes can be called anything you like, but the callback must what you used in your Connected App settings.

##### Web Server authentication flow
```php
Route::get('/authenticate', function()
{
    return Forrest::authenticate();
});

Route::get('/callback', function()
{
    Forrest::callback();

    $url = Config::get('forrest::authRedirect');

    return Redirect::to($url);
});
```
##### Username-Password authentication flow
With the Username Password flow, you can directly authenticate with the `Forrest::authenticate()` method.

>To use this authentication you must add your username, and password to the confirg file. Security token might need to be ammended to your password unless your IP address is whitelisted.

```php
Route::get('/authenticate', function()
{
    Forrest::authenticate();

    $url = Config::get('forrest::authRedirect');

    return Redirect::to($url);
});
```

#### Custom login urls
Sometimes users will need to connect to a sandbox or custom url. To do this, simply pass the url as an argument for the authenticatation method:
```php
Route::get('/authenticate', function()
{
    $loginURL = 'https://test.salesforce.com';

    return Forrest::authenticate($loginURL);
});
```
>Note: You can specify a default login URL in your config file.

## Basic usage
After authentication, your app will store an encrypted authentication token which can be used to make API requests.
### Query a record
```php
Forrest::query('SELECT Id FROM Account');
```
Result:
```JavaScript
{
    "totalSize": 2,
    "done": true,
    "records": [
        {
            "attributes": {
                "type": "Account",
                "url": "\/services\/data\/v30.0\/sobjects\/Account\/001i000000xxx"
            },
            "Id": "001i000000xxx"
        },
        {
            "attributes": {
                "type": "Account",
                "url": "\/services\/data\/v30.0\/sobjects\/Account\/001i000000xxx"
            },
            "Id": "001i000000xxx"
        }
    ]
}
```
If you are querying more than 2000 records, you response will include:
```
"nextRecordsUrl" : "/services/data/v20.0/query/01gD0000002HU6KIAW-2000"
```

Simply, call `Forrest::next($nextRecordsUrl)` to return the next 2000 records.

### Create a new record
Records can be created using the following format.
```php
$body = ['Name' => 'New Account'];
Forrest::sobjects('Account',[
    'method' => 'post',
    'body'   => $body]);
```

### Update a record
Update a record with the PUT method.

```php
$body = [
    'Name'  => 'Acme'
    'Phone' => '555-555-5555'];

Forrest::sobjects('Account/001i000000xxx',[
    'method' => 'put',
    'body'   => $body]);
```

### Upsert a record
Update a record with the PATCH method and if the external Id doesn't exist, it will insert a new record.

```php
$body = [
    'Phone' => '555-555-5555',
    'External_Id__c' => 'XYZ1234'];

Forrest::sobjects('Account',[
    'method' => 'patch',
    'body'   => $body]);
```

### Delete a record
Delete a record with the DELETE method.

```php
Forrest::sobjects('Account/001i000000xxx', ['method' => 'delete']);
```

### XML format
Change the request/response format to XML with the `format` key or make it default in your config file.

```php
Forrest::describe('Account',['format'=>'xml']);
```

## API Requests

With the exception of the `search` and `query` resources, all resources are requested dynamically using method overloading.

First, determine which resources you have access to by calling:
```php
Forrest::resources();
```
Same result:<commit_msg>Documentation updates for 2.0<commit_after># Omniphx/Forrest, Force.com REST API Client for Laravel 5
[![Laravel](https://img.shields.io/badge/Laravel-5.0-orange.svg?style=flat-square)](http://laravel.com)
[![Latest Stable Version](https://img.shields.io/packagist/v/omniphx/forrest.svg?style=flat-square)](https://packagist.org/packages/omniphx/forrest)
[![Total Downloads](https://img.shields.io/packagist/dt/omniphx/forrest.svg?style=flat-square)](https://packagist.org/packages/omniphx/forrest)
[![License](https://img.shields.io/packagist/l/omniphx/forrest.svg?style=flat-square)](https://packagist.org/packages/omniphx/forrest)
[![Build Status](https://img.shields.io/travis/omniphx/forrest.svg?style=flat-square)](https://travis-ci.org/omniphx/forrest)

Salesforce/Force.com REST API client for Laravel. It provides access to restricted Salesforce information via Oauth 2.0. REST is a lightweight alternative to the SOAP API and is useful for mobile users.

While this package is built for Laravel, it has been decoupled so that it can be extended into any framework or vanilla PHP application.

## Installation
>If you are upgrading to Version 2.0, be sure to re-publish your config file.

Forrest can be installed through composer. Open your `composer.json` file and add the following to the `require` key:

    "omniphx/forrest": "2.*"

Next run `composer update` from the command line to install the package.

If you are using Laravel, add the service provider and alias to your `bootstrap/app.php` file:

    'Omniphx\Forrest\Providers\Laravel\ForrestServiceProvider'

    'Forrest' => 'Omniphx\Forrest\Providers\Laravel\Facades\Forrest'

>For Laravel 4, add `Omniphx\Forrest\Providers\Laravel4\ForrestServiceProvider` in `app/config/app.php`. Alias will remain the same.

### Configuration
You will need a configuration file to add your credentials. Publish a config file using the `artisan` command:
```bash
php artisan vendor:publish
```
You can find the config file in: `config/forrest.php`

>For Laravel 4, run `php artisan config:publish omniphx/forrest`. It will be found in `app/config/omniphx/forrest/config.php`

## Getting Started
### Setting up a Connected App
1. Log into to your Salesforce org
2. Click on Setup in the upper right-hand menu
3. Under Build click `Create > Apps`
4. Scroll to the bottom and click `New` under Connected Apps.
5. Enter the following details for the remote application:
    * Connected App Name
    * API Name
    * Contact Email
    * Enable OAuth Settings under the API dropdown
    * Callback URL
    * Select access scope (If you need a refresh token, specify it here)
6. Click `Save`

After saving, you will now be given a Consumer Key and Consumer Secret. Update your config file with values for `consumerKey`, `consumerSecret`, `loginURL` and `callbackURI`.

### Setup
Forrest will come with the following routes included in it's package.

>Feel free to overwrite these in your `routes.php` file. Your routes can be called anything you like, but the callback must what you used in your Connected App settings.

##### Web Server authentication flow
```php
Route::get('/authenticate', function()
{
    return Forrest::authenticate();
});

Route::get('/callback', function()
{
    Forrest::callback();

    $url = Config::get('forrest::authRedirect');

    return Redirect::to($url);
});
```
##### Username-Password authentication flow
With the Username Password flow, you can directly authenticate with the `Forrest::authenticate()` method.

>To use this authentication you must add your username, and password to the config file. Security token might need to be ammended to your password unless your IP address is whitelisted.

```php
Route::get('/authenticate', function()
{
    Forrest::authenticate();

    $url = Config::get('forrest::authRedirect');

    return Redirect::to($url);
});
```

#### Custom login urls
Sometimes users will need to connect to a sandbox or custom url. To do this, simply pass the url as an argument for the authenticatation method:
```php
Route::get('/authenticate', function()
{
    $loginURL = 'https://test.salesforce.com';

    return Forrest::authenticate($loginURL);
});
```
>Note: You can specify a default login URL in your config file.

## Basic usage
After authentication, your app will store an encrypted authentication token which can be used to make API requests.
### Query a record
```php
Forrest::query('SELECT Id FROM Account');
```
Result:
```JavaScript
{
    "totalSize": 2,
    "done": true,
    "records": [
        {
            "attributes": {
                "type": "Account",
                "url": "\/services\/data\/v30.0\/sobjects\/Account\/001i000000xxx"
            },
            "Id": "001i000000xxx"
        },
        {
            "attributes": {
                "type": "Account",
                "url": "\/services\/data\/v30.0\/sobjects\/Account\/001i000000xxx"
            },
            "Id": "001i000000xxx"
        }
    ]
}
```
If you are querying more than 2000 records, you response will include:
```
"nextRecordsUrl" : "/services/data/v20.0/query/01gD0000002HU6KIAW-2000"
```

Simply, call `Forrest::next($nextRecordsUrl)` to return the next 2000 records.

### Create a new record
Records can be created using the following format.
```php
$body = ['Name' => 'New Account'];
Forrest::sobjects('Account',[
    'method' => 'post',
    'body'   => $body]);
```

### Update a record
Update a record with the PUT method.

```php
$body = [
    'Name'  => 'Acme'
    'Phone' => '555-555-5555'];

Forrest::sobjects('Account/001i000000xxx',[
    'method' => 'put',
    'body'   => $body]);
```

### Upsert a record
Update a record with the PATCH method and if the external Id doesn't exist, it will insert a new record.

```php
$body = [
    'Phone' => '555-555-5555',
    'External_Id__c' => 'XYZ1234'];

Forrest::sobjects('Account',[
    'method' => 'patch',
    'body'   => $body]);
```

### Delete a record
Delete a record with the DELETE method.

```php
Forrest::sobjects('Account/001i000000xxx', ['method' => 'delete']);
```

### XML format
Change the request/response format to XML with the `format` key or make it default in your config file.

```php
Forrest::describe('Account',['format'=>'xml']);
```

## API Requests

With the exception of the `search` and `query` resources, all resources are requested dynamically using method overloading.

First, determine which resources you have access to by calling:
```php
Forrest::resources();
```
Result:
{'fraction_non_alphanumeric': 0.1310552298673249, 'fraction_numerical': 0.01974699166923789, 'mean_word_length': 3.9750575594781274, 'pattern_counts': {'":': 24, '<': 3, '<?xml version=': 0, '>': 45, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '847929', 'n_tokens_mistral': 4185, 'n_tokens_neox': 3841, 'n_words': 1357}