cmpas2/ayforrest

Salesforce / Force.com REST API 客户端 for Laravel 5

维护者

详细信息

github.com/cmpas2/ayforrest

源代码

安装: 17

依赖者: 0

建议者: 0

安全: 0

星星: 0

关注者: 2

分支: 117

v2.1.1 2016-02-20 17:38 UTC

Requires

Requires (Dev)

MIT d4e8b6659f382d3c1ce79461a0724bf01c53ed99

restsalesforceforce.comlaravelforce

This package is not auto-updated.

Last update: 2024-09-20 18:54:11 UTC

README

Laravel Latest Stable Version Total Downloads License Build Status

Salesforce/Force.com REST API 客户端 for 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 安装

您应该将 src/config/config.php 中的配置文件复制到应用程序根目录下的配置目录中的 forrest.php 配置文件。

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

$app->register(Omniphx\Forrest\Providers\Lumen\ForrestServiceProvider::class);
$app->configure('forrest');

配置

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

php artisan vendor:publish

您可以在以下位置找到配置文件：config/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('/');
});

自定义登录 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]);

Upsert记录

使用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::describe('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响应和事件监听器的更多信息，请参阅他们的文档。