README

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

目前只支持Laravel和Lumen。

对Eloquent Salesforce模型感兴趣？请查看@roblesterjr04的EloquentSalesForce项目，该项目利用Forrest作为其API层。

安装

如果您正在升级到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();

然后您可以通过在bootstrap/app.php文件中注册Lumen服务提供者来使用它。

配置

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

php artisan vendor:publish

这将发布一个config/forrest.php文件，该文件可以在不同的身份验证类型和其他设置之间切换。

添加配置文件后，更新您的.env文件以包含以下值（获取消费者密钥和密钥的详细说明如下）

CONSUMER_KEY=123455
CONSUMER_SECRET=ABCDEF
CALLBACK_URI=https://test.app/callback
LOGIN_URL=https://login.salesforce.com
USERNAME=mattjmitchener@gmail.com
PASSWORD=password123

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

Laravel 4中，运行php artisan config:publish omniphx/forrest，这将创建app/config/omniphx/forrest/config.php

入门

设置连接应用

1. 登录Salesforce组织
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('/');
});

SOAP身份验证流程

（当您无法在Salesforce中创建连接应用时）

1. Salesforce允许通过SOAP登录进行个人登录
2. SOAP登录返回的Bearer访问令牌可以像Oauth密钥一样使用
3. 更新您的配置文件，并将authentication值设置为UserPasswordSoap
4. 更新您的配置文件，添加 loginURL、username 和 password 的值。使用用户名密码 SOAP 流，您可以直接通过 Forrest::authenticate() 方法进行身份验证。

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

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

如果您的应用程序需要以不同的用户登录 Salesforce，您还可以将登录 URL、用户名和密码传递给 Forrest::authenticateUser() 方法。

除非您的 IP 地址已列入白名单，否则可能需要修改安全令牌。

Route::Post('/authenticate', function(Request $request)
{
    Forrest::authenticateUser('https://login.salesforce.com',$request->username, $request->password);
    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 条记录。

创建新记录

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

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

更新记录

使用 PUT 方法更新记录。

Forrest::sobjects('Account/001i000000xxx',[
    'method' => 'put',
    'body'   => [
        'Name'  => 'Dunder Mifflin',
        'Phone' => '555-555-5555'
    ]
]);

Upsert 记录

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

$externalId = 'XYZ1234';

Forrest::sobjects('Account/External_Id__c/' + $externalId, [
    'method' => 'patch',
    'body'   => [
        'Name'  => 'Dunder Mifflin',
        'Phone' => '555-555-5555'
    ]
]);

删除记录

使用 DELETE 方法删除记录。

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

设置头信息

有时您需要设置自定义头信息（例如，创建具有分配规则的潜在客户）

Forrest::sobjects('Lead',[
    'method' => 'post',
    'body' => [
        'Company' => 'Dunder Mifflin',
        'LastName' => 'Scott'
    ],
    'headers' => [
        'Sforce-Auto-Assign' => '01Q1N000000yMQZUA2'
    ]
]);

要禁用分配规则，请使用 'Sforce-Auto-Assign' => 'false'

XML 格式

使用 format 键将请求/响应格式更改为 XML 或在配置文件中将它设置为默认格式。

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

API 请求

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

您可以通过调用资源方法来确定您有权访问哪些资源。

Forrest::resources();

此示例输出显示了可通过 API 调用的资源

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']);

批量 Upsert 多条记录（Bulk API 2.0）

当您需要快速将大量数据加载到 Salesforce 组织时，批量 API 请求特别有用。主要区别在于它至少需要三个单独的请求（创建、添加、关闭），并且要加载的数据以 CSV 格式发送。

以下是对 Contacts 记录的 CSV 批量 Upsert 的三个请求示例。

创建

使用 POST 方法创建批量上传作业，请求体包含以下作业属性

• object 是您要加载的对象类型（每个作业中必须都是同一类型）
• externalIdFieldName 是外部 ID，如果存在，则会更新；如果不存在，则会插入新记录。仅适用于 Upsert 操作。
• contentType 是 CSV，这是当前唯一有效的值。
• operation 设置为 upsert 以添加和更新记录。

我们将响应存储在 $bulkJob 中，以便在下面的添加和关闭请求中引用唯一的作业 ID。

有关此处所有可用选项的完整列表，请参阅创建作业。

$bulkJob = Forrest::jobs('ingest', [
    'method' => 'post',
    'body' => [
        "object" => "Contact",
        "externalIdFieldName" => "externalId",
        "contentType" => "CSV",
        "operation" => "upsert"
    ]
]);

添加数据

使用创建 POST 请求中的作业 ID，然后发送 CSV 数据以使用 PUT 请求进行处理。这假设您已经将 CSV 内容加载到 $csv

有关格式细节，请参阅 准备 CSV 文件。

Forrest::jobs('ingest/' . $bulkJob['id'] . '/batches', [
    'method' => 'put',
    'headers' => [
        'Content-Type' => 'text/csv'
    ],
    'body' => $csv
]);

关闭

在记录可以处理之前，您必须关闭作业，为此，您需要向作业 ID 发送一个使用 PATCH 请求的 UploadComplete 状态。

有关更多选项和如何取消作业的详细信息，请参阅 关闭或取消作业。

$response = Forrest::jobs('ingest/' . $bulkJob['id'] . '/', [
    'method' => 'patch',
    'body' => [
        "state" => "UploadComplete"
    ]
]);

批量 API 2.0 可在 API 版本 41.0 及更高版本中使用。有关 Salesforce 批量 API 的更多信息，请参阅 官方文档 和有关如何进行成功的批量上传的 本教程。

其他 API 请求

刷新

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

Forrest::refresh();

如果您需要刷新令牌，请确保在您的 连接应用程序 中指定 access scope。您也可以通过添加 '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 响应和事件监听器的更多信息，请参阅他们的 文档。