README

Salesforce/Force.com REST API 客户端用于Laravel。虽然它更像是一个API方法的包装器，但它应该为你提供与REST服务交互所需的所有灵活性。

虽然此包是为Laravel构建的，但它已被解耦，以便它可以扩展到任何框架或纯PHP应用程序。目前只支持Laravel 4、5和Lumen。

安装

如果您正在升级到2.0版本，请确保重新发布您的配置文件。

可以通过composer安装Forrest。打开您的composer.json文件，并将以下内容添加到require键中

"omniphx/forrest": "2.*"

接下来，从命令行运行composer update以安装包。

Laravel安装

将服务提供者和别名添加到您的config/app.php文件中

Omniphx\Forrest\Providers\Laravel\ForrestServiceProvider::class
'Forrest' => Omniphx\Forrest\Providers\Laravel\Facades\Forrest::class

Laravel 4中，在app/config/app.php中添加Omniphx\Forrest\Providers\Laravel4\ForrestServiceProvider。别名保持不变。

Lumen安装

class_alias('Omniphx\Forrest\Providers\Laravel\Facades\Forrest', 'Forrest');
$app->register(Omniphx\Forrest\Providers\Lumen\ForrestServiceProvider::class);
$app->configure('forrest');
$app->withFacades();

然后您将使用Lumen服务提供程序，通过在bootstrap/app.php文件中注册它来利用它。

配置

您需要一个配置文件来添加您的凭证。使用artisan命令发布配置文件

php artisan vendor:publish

您可以在以下位置找到配置文件：config/forrest.php

对于Lumen，您应从src/config/config.php复制配置文件，并将其添加到应用程序根目录下的配置目录中的forrest.php配置文件中。

对于Laravel 4，运行php artisan config:publish omniphx/forrest。它将在app/config/omniphx/forrest/config.php中找到。

入门

设置连接的应用程序

1. 登录到您的Salesforce org
2. 在右上角菜单中点击“设置”
3. 在“构建”下点击“创建 > 应用程序”
4. 滚动到页面底部，在“连接应用程序”下点击“新建”
5. 为远程应用程序输入以下详细信息
   • 连接应用程序名称
   • API名称
   • 联系邮箱
   • 在API下拉菜单下启用OAuth设置
   • 回调URL
   • 选择访问范围（如果您需要刷新令牌，请在此处指定）
6. 点击“保存”

保存后，您将获得消费者密钥和消费者密钥。使用consumerKey、consumerSecret、loginURL和callbackURI的值更新您的配置文件。

设置

创建认证路由

Web服务器认证流程

Route::get('/authenticate', function()
{
    return Forrest::authenticate();
});

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

    return Redirect::to('/');
});

用户名-密码认证流程

使用用户名-密码流程，您可以直接使用Forrest::authenticate()方法进行认证。

要使用此认证，您必须将用户名和密码添加到配置文件中。除非您的IP地址已在白名单中，否则可能需要修改安全令牌。

Route::get('/authenticate', function()
{
    Forrest::authenticate();
    return Redirect::to('/');
});

自定义登录URL

有时用户需要连接到沙盒或自定义URL。为此，只需将URL作为认证方法的参数传递即可。

Route::get('/authenticate', function()
{
    $loginURL = 'https://test.salesforce.com';

    return Forrest::authenticate($loginURL);
});

注意：您可以在配置文件中指定默认登录URL。

基本用法

认证后，您的应用程序将存储一个加密的认证令牌，该令牌可用于发送API请求。

查询记录

Forrest::query('SELECT Id FROM Account');

结果

{
    "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"
        }
    ]
}

如果您要查询超过2000条记录，您的响应将包含

"nextRecordsUrl" : "/services/data/v20.0/query/01gD0000002HU6KIAW-2000"

简单来说，通过调用Forrest::next($nextRecordsUrl)来返回下2000条记录。

创建新记录

可以使用以下格式创建记录。

$body = ['Name' => 'New Account'];
Forrest::sobjects('Account',[
    'method' => 'post',
    'body'   => $body]);

更新记录

使用PUT方法更新记录。

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

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

合并更新记录

使用PATCH方法更新记录，如果外部ID不存在，则会插入一条新记录。

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

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

删除记录

使用DELETE方法删除记录。

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

XML格式

通过format键更改请求/响应格式为XML，或在您的配置文件中将其设置为默认值。

Forrest::sobjects('Account',['format'=>'xml']);

API请求

除了search和query资源外，所有资源都通过方法重载动态请求。

首先，通过调用

Forrest::resources();

结果

Array
(
    [sobjects] => /services/data/v30.0/sobjects
    [connect] => /services/data/v30.0/connect
    [query] => /services/data/v30.0/query
    [theme] => /services/data/v30.0/theme
    [queryAll] => /services/data/v30.0/queryAll
    [tooling] => /services/data/v30.0/tooling
    [chatter] => /services/data/v30.0/chatter
    [analytics] => /services/data/v30.0/analytics
    [recent] => /services/data/v30.0/recent
    [process] => /services/data/v30.0/process
    [identity] => https://login.salesforce.com/id/00Di0000000XXXXXX/005i0000000aaaaAAA
    [flexiPage] => /services/data/v30.0/flexiPage
    [search] => /services/data/v30.0/search
    [quickActions] => /services/data/v30.0/quickActions
    [appMenu] => /services/data/v30.0/appMenu
)

然后，通过引用指定的键调用资源。例如

Forrest::theme();

或

Forrest::appMenu();

可以通过将额外参数传递给第一个参数来扩展资源URL

Forrest::sobjects('Account/describe/approvalLayouts/');

您还可以向请求添加可选参数

Forrest::theme(['format'=>'xml']);

其他API请求

刷新

如果设置了刷新令牌，则服务器可以在用户的代表下刷新访问令牌。刷新令牌仅适用于Web服务器流程。

Forrest::refresh();

如果您需要刷新令牌，请确保在已连接的应用的访问范围下指定此内容。您还可以通过添加'scope' => 'full refresh_token'在配置文件中指定此内容。在配置文件中设置范围访问是可选的，默认范围访问由您的Salesforce组织确定。

撤销

这将撤销授权令牌。会话将继续存储令牌，但它们将变得无效。

Forrest::revoke();

版本

返回所有当前支持的版本。包括版本、标签和每个版本的根链接

Forrest::versions();

资源

根据登录用户的权限和API版本返回可用资源的列表。

Forrest::resources();

身份

返回有关登录用户的信息。

Forrest::identity();

有关API资源的完整列表，请参阅Force.com REST API开发者指南

自定义Apex端点

如果您使用Apex创建了自定义API，您可以使用custom()方法来消费它们。

Forrest::custom('/myEndpoint');

可以像这样传递额外的选项和参数

Forrest::custom('/myEndpoint', [
    'method' => 'post',
    'body' => ['foo' => 'bar'],
    'parameters' => ['flim' => 'flam']]);

有关更多信息，请参阅使用Apex REST创建REST API

原始请求

如果需要，您可以对您选择的端点进行原始请求。

Forrest::get('/services/data/v20.0/endpoint');
Forrest::head('/services/data/v20.0/endpoint');
Forrest::post('/services/data/v20.0/endpoint', ['my'=>'param']);
Forrest::put('/services/data/v20.0/endpoint', ['my'=>'param']);
Forrest::patch('/services/data/v20.0/endpoint', ['my'=>'param']);
Forrest::delete('/services/data/v20.0/endpoint');

原始响应输出

默认情况下，此包将响应体作为反序列化的JSON对象或SimpleXMLElement对象返回。

有时，您可能希望以不同的方式处理。为此，只需使用除'json'或'xml'之外的其他格式，代码将返回Guzzle响应对象。

$response = Forrest::sobjects($resource, ['format'=> 'none']);
$content = (string) $response->getBody(); // Guzzle response

事件监听器

此包使用Guzzle的事件监听器

Event::listen('forrest.response', function($request, $response) {
    dd((string) $response);
});

有关Guzzle响应和事件监听器的更多信息，请参阅他们的文档。