README

由Saloon提供支持的美丽、可扩展的API。

介绍

此API提供了一个功能丰富、优雅的基础，用于与Salesforce API一起工作。开发者可以安装并利用此API来帮助他们轻松且美观地集成Salesforce。这些端点返回salesforce响应，并且大多数端点都包含指向特定文档的链接。

安装

composer require myoutdeskllc/salesforce-php

特性

有许多开箱即用的特性可供您构建。

身份验证
- OAuth
- 用户名 \ 密码流（API用户）
基本操作
- 查询记录
- 插入记录
- 支持流行的常用对象的装饰方法
  - 潜在客户
  - 帐户
  - 机会
  - 联系人
- 搜索助手
SObject元数据API
- 查询基本信息
- 查询完整元数据（字段等）
Bulk API 2.0
- 创建和管理bulk api 2.0作业
- 支持多种上传方法
  - 通过文件名上传CSV
  - 通过文件流上传CSV
  - 将记录作为数组传入
- 包含SalesforceJob类以帮助管理操作
  - 这是可选的，同时也暴露了直接方法
运行SOQL查询
- 访问 SOQL查询构建器
- SOQL日期常量的辅助函数
分析API（报告、仪表板）
- 列出、查询报告、仪表板的基本信息、元数据
- 列出、创建、更新、删除、搜索报告和仪表板文件夹
- 创建、管理、更新、删除、复制报告
- 创建、管理、更新、删除、复制仪表板
- 运行仪表板、报告并同步、异步获取结果
工具API
- 获取apex类、apex页面的信息
- 列出、下载apex日志
- 列出之前的运行，通过REST（同步、异步）运行测试
- 执行匿名apex
- 列出、获取、删除电子邮件模板
  - 创建电子邮件模板是可怕的。你可以，但不要费心。
组织
- 支持的API版本
- 限制

身份验证

支持两种身份验证方法：OAuth和用户名 \ 密码。除非您使用服务器到服务器集成，否则OAuth是首选方法。

OAuth

OAuth是首选的身份验证方法。首先，您需要在您的Salesforce实例中创建一个应用程序，然后复制重定向URI、客户端ID和客户端密钥以开始。

use \myoutdeskllc\SalesforcePhp\SalesforceApi;
use \myoutdeskllc\SalesforcePhp\OAuth\OAuthConfiguration;

$salesforceApi = new SalesforceApi('https://MY_INSTANCE.my.salesforce.com');

$sfOauthConfiguration = OAuthConfiguration::create(
    'client_id' => 'YOUR_CLIENT_ID',
    'secret' => 'YOUR_SECRET',
    'redirect_uri' => 'YOUR_REDIRECT_URI'
);

[$url, $state] = array_values($salesforceApi->startOAuthLogin($oauthConfig));
// store the state yourself in the users session and redirect to $url
// once the user is redirected back to your application, you can get the access token
$authenticator = $salesforceApi->completeOAuthLogin($oauthConfig, $code, $state);
// store this in an encrypted field in your database
$serialized = $authenticator->serialize();

密码身份验证

请访问 YOUR_DOMAIN.com/_ui/system/security/ResetApiTokenEdit 来重置安全令牌。这将通过电子邮件发送给用户。这必须在密码流的身份验证中附加到密码后面，除非您使用的是白名单IP地址范围。

$salesforceApi = new \myoutdeskllc\SalesforcePhp\SalesforceApi('https://MY_INSTANCE.my.salesforce.com');
// this call will return an access_token for you to cache in your own database for a time
$salesforceApi->login('username', 'password', 'consumer_key', 'consumer_secret');
// if you have an access token that is still valid, you can restore it
// I recommend caching this for at least 5 minutes, so you don't bombard salesforce with password requests
// if you new up a new instance of the API, you can restore the access token from previous authentications
$salesforceApi->restoreAccessToken('access_token');

记录级操作

有几种方法可以执行记录的CRUD操作。

创建记录

您可以使用CreateRecord或CreateRecords将记录插入Salesforce。

$salesforceApi->createRecord('My_Custom_Object__c', [
    'Field__c' => 'Value',
    'Other_Field__c' => 'Other Value'
]);
// or
$salesforceApi->createRecords('My_Custom_Object__c', [
    [
        'Field__c' => 'Value',
        'Other_Field__c' => 'Other Value'
    ],
    [
        'Field__c' => 'Value',
        'Other_Field__c' => 'Other Value'
    ]
]);

在创建多个记录时，您可以传递第三个布尔值allOrNone，以确定它们是否都应成功，以便在Salesforce中提交操作。

读取记录

API提供了几种查询记录的不同方法。最常见的方法是使用getRecord方法。

$salesforceApi->getRecord('My_Custom_Object__c', 'ACCOUNT_ID', ['Field__c', 'Other_Field__c']);

您也可以使用queryRecords一次性获取多个记录。

$salesforceApi->getRecords('My_Custom_Object__c', ['id1','id2','id3'], ['Field__c', 'Other_Field__c']);

更新记录

您可以使用updateRecord方法更新记录。

$salesforceApi->updateRecord('My_Custom_Object__c', 'ACCOUNT_ID', [
    'Field__c' => 'Value',
    'Other_Field__c' => 'Other Value'
]);
// or
$salesforceApi->updateRecords('My_Custom_Object__c', [
    [
        'Id' => 'ACCOUNT_ID',
        'Field__c' => 'Value',
        'Other_Field__c' => 'Other Value'
    ],
    [
        'Id' => 'ACCOUNT_ID',
        'Field__c' => 'Value',
        'Other_Field__c' => 'Other Value'
    ]
]);

删除记录

您可以使用deleteRecord方法来删除记录。

$salesforceApi->deleteRecord('My_Custom_Object__c', 'ACCOUNT_ID');
// or using composite api
$salesforceApi->deleteRecords(['id1','id2','id3']);

删除操作支持将allOrNone作为第二个参数。

在更新多个记录时，您可以为allOrNone传递第三个布尔值，以确定它们是否都需要成功才能在Salesforce中提交操作。

搜索记录

API提供了几种不同的方式来搜索记录。

在特定对象内搜索

$salesforceApi->searchIn('Account Name', 'Account');
// iterate over the returned results
foreach($results['searchRecords'] as $record) {
    // do something with the record
}

在特定对象的特定字段内搜索

$salesforceApi->searchIn('Company, LLC', 'Account', ['Name', 'Company']);
// iterate over the returned results
foreach($results['searchRecords'] as $record) {
    // do something with the record
}

跨所有对象搜索

$api->search('Hint inside records somewhere');
foreach($results['searchRecords'] as $record) {
    // do something with the record
}

Salesforce原生对象

API提供了一些辅助方法来获取常见对象。

$standardObjectApi = $salesforceApi->getStandardObjectApi();
$standardObjectApi->createLead($myLeadData);
$standardObjectApi->getLead($leadId, ['Id', 'Name']);
$standardObjectApi->getLeads(['id1','id2','id3'], ['Id', 'Name']);

您可以在StandardObjectApi中查看所有可用的操作列表

批量作业

通过作业包装器提供对记录的批量作业支持，并支持CSV。

// make sure you have a new api first to pass in
$salesforceJob = new SalesforceJob($api->getBulkApi());
$salesforceJob->setObject('My_Object__c');
$salesforceJob->setOperation(BulkApiOptions::INSERT);
$salesforceJob->initJob();
$salesforeJob->getJobId();
// prints a job id
$salesforceJob->setCsvFile('path/to/file.csv');
// this will set a CSV file stream for you, otherwise, set up a file yourself with fopen
$salesforceJob->setFileStream(fopen('path/to/file.csv', 'r'));
// or, just set up records directly as an array
$salesforceJob->setRecords([
    [
        'Field__c' => 'Value',
        'Other_Field__c' => 'Other Value'
    ],
    [
        'Field__c' => 'Value',
        'Other_Field__c' => 'Other Value'
    ]
]);
// don't forget to "close" the job to lock it for salesforce so it begins processing
$salesforceJob->closeJob();
// then later, you can check the status
$salesforceJob = SalesforceJob::getExistingJobById($jobId, $api->getBulkApi());
$salesforceJob->refreshStatus();
// check the state to see if its done
$salesforceJob->getState();
// returns 'JobComplete' if its finished
// then, of course, you need to know what actually was returned
// Row 1 is headers, so you'll want to skip that
$salesforceJob->getSuccessfulResultsAsArray();

SOQL构建器

SOQL构建器可以帮助您更有效地构建应用程序中的查询。您需要确保在构建器中安全性严格，但它提供了一个流畅的API来帮助构建查询。

$builder = SalesforceApi::getQueryBuilder();

$builder
    ->select(['Id', 'Name', 'created_at'])
    ->from('Account')
    ->where('Name', '=', 'Test')
    ->limit(20)
    ->orderBy('created_at', 'DESC')
    ->toSoql();

输出

> SELECT Id, Name, created_at FROM Account WHERE Name = 'Test' ORDER BY created_at DESC LIMIT 20

测试

测试是通过PestPHP完成的。为了确保Salesforce功能的全面覆盖，我们设置了一个沙箱API的scratch org进行测试。这意味着扩展测试将需要更多的工作，但也意味着它已经经过真实数据的实战测试。

获取scratch org的定义副本

将.env.example复制到.env，更新redirect_url为您本地机器的URL。将base_url设置为https://test.salesforce.com。

Scratch Org设置

在此处注册一个开发者版本组织
登录并转到Dev Hub /lightning/setup/DevHub/home 并将滑块切换到启用
安装Salesforce DX CLI
拉取salesforce-php-dx项目
在终端中，输入sfdx force:auth:web:login --setdefaultdevhubusername并登录到开发者中心
创建scratch orgsfdx force:org:create -f config/project-scratch-def.json --setalias salesforcephpdx --durationdays 7 --setdefaultusername --json --loglevel fatal
使用sfdx force:org:open打开您的scratch组织
在开发控制台（或使用VSCODE）中执行scripts/apex/seed.apex中的apex

myoutdeskllc / salesforce-php

维护者

详细信息