README

安装

确保已安装 composer，然后运行以下命令

composer require seanbarton/salesforce

这将获取库及其依赖项，并将其放入您的 vendor 目录中。

要求

功能

密码授权类型的 OAuth
创建、更新、删除、更新和查询记录
使用 seanbarton\Salesforce\Record 表示 Salesforce 记录的对象
字段验证和对象映射
可扩展代码：添加自定义对象或验证规则

设置连接应用

在开始之前，您需要在 Salesforce 中设置“连接应用”并获取 consumerKey、consumerSecret、username 和 password 以允许 API 访问。

注意，此过程可能因 Salesforce 网站更改或您的 Salesforce 账户和设置而有所不同。

请参阅 Salesforce 帮助文档以验证。

登录您的 Salesforce 组织
点击右上角的“设置”
在“构建”下点击创建→应用
滚动到页面底部，然后在“连接应用”下点击“新建”。
为远程应用输入以下详细信息
- 连接应用名称
- API 名称
- 联系邮箱
- 在 API 下拉菜单中启用 OAuth 设置
- 回调 URL
- 选择访问范围（如果您需要刷新令牌，请在此处指定）
点击保存，并将访问凭证保存在安全的地方。

用法

创建新的 API 客户端并连接

use seanbarton\Salesforce\Authenticator\Password;
use seanbarton\Salesforce\Client;

// Provide endpoint and any Guzzle options in Password::create(), endoint defaults to login.salesforce.com
$auth = Password::create(['endpoint' => 'https://test.salesforce.com/'])->authenticate([
    "client_id" => $YOUR_CONSUMER_KEY,
    "client_secret" => $YOUR_CONSUMER_SECRET,
    "username" => $YOUR_SALESFORCE_USERNAME,
    "password" => $YOUR_SALESFORCE_PASSWORD_AND_SECURITY_TOKEN
]);

// Here you may also provide object mappings and desired Salesforce API version
$salesforce = new Client($auth, [], 59);

以下示例使用名为 Example 的 Salesforce 对象，它有一个 Name 字段。

执行基本的 SOQL 查询

$select = "SELECT Id, Name FROM Example LIMIT 100";
foreach ($salesforce->query($select) as $object) {
    echo "Example {$object->Id} ({$object->Name})\n";
    // outputs something like "Example 5003000000D8cuIQAA (Bob)"
}

如果您需要在查询中使用 php 值，请在 SOQL 中放置 {tokens} 并通过 query() 的第二个参数单独传递值。值将根据其类型进行适当的引号和转义，并插入到查询中

$select = "SELECT Id, Name FROM Example WHERE Name={name} LIMIT 100";
$name = 'Bob';
foreach ($salesforce->query($select, ['name' => $name]) as $object) {
    echo "Example {$object->Id} ({$object->Name})\n";
    // outputs something like "Example 5003000000D8cuIQAA (Bob)"
}

通过 ID 获取记录

$id = "5003000000D8cuIQAA";
$bob = $salesforce->get("Example", $id);
echo "Hello, {$bob->Name}\n";
// outputs something like "Hello, Bob"

创建新的记录

use seanbarton\Salesforce\Record;

$linda = $salesforce->create(new Record("Example", ["Name" => "Linda"]));
echo "Example {$linda->Id} ({$linda->Name})";
// outputs something like "Example 5003000000D8cuIQAA (Linda)"

更新现有记录

$bob->Name = "Roberto";
$roberto = $salesforce->update($bob);
echo "Hello, {$roberto->Name}\n";
// outputs "Hello, Roberto"

删除记录

$ded = $salesforce->delete($bob);
var_dump($ded->Id);
// outputs "NULL"

高级用法

扩展 Record 类

包含的 seanbarton\Salesforce\Record 类可以不进行修改作为通用的“salesforce record”实现 - 它将根据从 API 获取的内容自动设置属性。然而，目的是应用程序将从它扩展并定义每个 Salesforce 对象所需的属性。这允许您有一个一致的架构，您的代码可以依赖于它，甚至可以在您的应用程序中直接实现一定程度的验证。

要构建自己的 Salesforce 对象，您必须

从 seanbarton\Salesforce\Record 扩展
定义对象字段为公共属性
在 UNEDITABLE_FIELDS 中列出任何必须在 update() 调用中不包括的属性（例如，重命名的字段、嵌套对象或对象列表）
在 setField() 中添加任何必要的逻辑（例如，如果您的记录具有关系，则构建一个新的对象）
在 validateField() 中添加任何所需的逻辑

使用上面提到的“Example”对象

use seanbarton\Salesforce\Record;

class Example extends Record
{
    public const TYPE = "Example";

    public ?string $Name = null;
}

内联记录和记录列表

SOQL 允许查询嵌套对象和查询，分别以内联记录和查询结果的形式出现在结果中。这个库确实理解此类查询的结果，但你的 Record 子类必须以特定方式定义属性以支持它们。

例如，一个类似于 SELECT Manager.Id, Manager.Name, (SELECT Id, Name FROM Members) FROM Teams 的查询将需要一个类似下面的 Record 类

use seanbarton\Salesforce\Record;
use seanbarton\Salesforce\Result;
use Example;

class Team extends Record
{
    public const TYPE = "Team";

    protected const UNEDITABLE_FIELDS = [
        "Manager",
        "Members",
        ...parent::UNEDITABLE_FIELDS
    ];

    public ?Example $Manager = null;
    public ?Result $Members = null;
}

如果有内联对象，属性应该被类型化为相应的 Record 子类。对于任何不创建 Record 子类的记录类型，属性的类型应该是 Record —— 虽然这显然不太有用。

如果有子查询，属性应该被类型化为一个 Result 实例。除此之外，这还允许 Result 支持分页子查询。

对象映射

最后，为了让 Api 客户端利用你的子类，你必须提供一个 $objectMap，这样它就知道哪些 PHP 类对应于哪些 Salesforce 记录类型。如果没有这个，你最终会得到所有东西的通用 Record 实例。嵌套结果将使用与它们的父 Result 实例相同的 $objectMap。

$salesforce = new Client(
    $password->authenticate([...$credentials]),
    [Example::TYPE => Example::class, Team::TYPE => Team::class]
);

字段验证

seanbarton\Salesforce\Validator 包含了一些基本的验证函数。这些方法都接受要验证的值作为第一个参数，并且可以根据需要接受其他参数。按照相同的模式实现你自己的对象的额外验证函数。

use seanbarton\Salesforce\Record;
use seanbarton\Salesforce\Validator;

class Example extends Record
{
    public ?string $Name = null;

    protected function validateField(string $field) : void {
        switch ($field) {
            case "Name":
                Validator::characterLength($this->Name, 2, 100);
                return;
            default:
                parent::validateField($field);
                return;
        }
    }
}

错误处理

从这个库中抛出的所有运行时异常都将是一个 seanbarton\Salesforce\Error 实例。

异常分为以下几种类型

seanbarton\Salesforce\Exceptions\SalesforceException:

来自 Salesforce API 的错误，包括 HTTP 错误（例如，连接超时）
seanbarton\Salesforce\Exceptions\AuthException:

认证失败或尝试在认证成功之前使用 HttpClient
seanbarton\Salesforce\Exceptions\ResultException:

解析或处理 Salesforce API 结果或记录时的错误；这通常表明你的自定义 Record 类中存在问题
seanbarton\Salesforce\Exceptions\UsageException:

由于库使用不当而产生的错误；这通常表明你的应用程序代码中存在运行时问题
seanbarton\Salesforce\Exceptions\ValidationException:

验证错误。

使用 Docker 进行开发

我们包含了一个 Dockerfile，以便轻松运行测试和调试代码。你必须安装 Docker。以下命令将构建镜像并运行容器

docker build -t seanbarton/salesforce --build-arg PHP_VERSION=8 .
docker run -it --rm -v ${PWD}:/var/www/sapi seanbarton/salesforce sh

在 VSCode 中使用 XDebug 进行调试

Docker 镜像已配置 XDebug。要使用 VSCode 调试代码，请按照以下步骤操作

在 VSCode 中安装 PHP Debug 扩展

在 VSCode 中添加一个新的 PHP Debug 配置

{
    "name": "XDebug Docker",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
        "/var/www/sapi/": "${workspaceRoot}/"
    }
}

docker run -it --rm -v ${PWD}:/var/www/sapi --add-host host.docker.internal:host-gateway seanbarton/salesforce sh
使用“XDebug Docker”配置在 VSCode 中开始调试。

测试

这个库包含 PHPUnit 用于开发。Composer 文件已配置了一些脚本，运行以下命令以运行测试

composer test

seanbarton / salesforce

维护者

详细信息