README

安装

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

composer require lyonstahl/salesforce

这将获取库及其依赖项，并将其放置在您的vendor文件夹中。

如果您需要一个用于构建SOQL查询的简单API，我们建议lyonstahl/soql-builder

要求

功能

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

设置连接应用

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

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

请查阅Salesforce的帮助文档以验证。

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

用法

创建新的API客户端并连接

use LyonStahl\Salesforce\Authenticator\Password;
use LyonStahl\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 LyonStahl\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类

包含的LyonStahl\Salesforce\Record类可以未经修改地作为通用的“salesforce记录”实现使用 - 它将自动根据从API获取的内容设置属性。然而，意图是应用程序将从此类扩展，并定义它们每个Salesforce对象所需的属性。这允许您拥有一致的架构，您的代码可以依赖于此，甚至可以在您的应用程序中直接实现一些级别的验证。

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

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

使用上述“Example”对象

use LyonStahl\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 LyonStahl\Salesforce\Record;
use LyonStahl\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]
);

字段验证

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

use LyonStahl\Salesforce\Record;
use LyonStahl\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;
        }
    }
}

处理错误

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

异常分为以下类型

LyonStahl\Salesforce\Exceptions\SalesforceException:

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

身份验证失败或尝试在身份验证成功之前使用 HttpClient
LyonStahl\Salesforce\Exceptions\ResultException:

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

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

验证错误。

使用 Docker 进行开发

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

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

使用 VSCode 中的 XDebug 进行调试

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

在 VSCode 中安装 PHP 调试扩展

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

{
    "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 lyonstahl/salesforce sh
使用 'XDebug Docker' 配置在 VSCode 中开始调试。

测试

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

composer test

lyonstahl / salesforce

维护者

详细信息