README

安装

composer require cnsdose/salesforce-php

注册服务提供者

Laravel

// config/app.php
'providers' => [
    // ...
    \CNSDose\Salesforce\Providers\SalesforceProvider::class
    // ...
]

Lumen

// bootstrap/app.php
$app->register(\CNSDose\Salesforce\Providers\SalesforceProvider::class);

其他

Laravel/Lumen 是可选的，只要你能提供 config($key, $default) 函数即可，例如。

function config(string $key, $default = null)
{
    $configs = [
        'salesforce' => include __DIR__ . '/../config/salesforce.php',
    ];
    return array_get($configs, $key, $default);
}

php artisan vendor:publish --provider='CNSDose\Salesforce\Providers\SalesforceProvider'

配置

见 config/salesforce.php。

记录 API (REST API)

查询记录

当前查询构建器仅支持 SOQL 表达式的子集。

基本用法

注意: salesforce-php 目前不支持自动引号/转义。

$result = Account::build()
    ->where('Type', 'LIKE', "'Customer%'")
    ->where('CurrencyIsoCode', "'USD'")
    ->where('CreatedDate', '>=', '2019-01-23T01:01:01.000Z')
    ->where('Site', '=', null)
    ->query();

解析关系

$result = Account::build()
    ->select('*')
    ->resolve(Contact::class, 'Contacts')
    ->query();

嵌套查询

$contact = Contact::build()
    ->where(
        'AccountId',
        'IN',
        Account::build()
            ->select('Id')
            ->where('Name', "'AccountExample1'")
            ->orWhere('Name', "'AccountExample2'")
    )
    ->query();
$result = BaseRecordModel::build()
    ->select('Id')
    ->select(
        BaseRecordModel::build()
            ->select('Id')
            ->from('Account.Contacts')
    )
    ->from('Account')
    ->query();

原始查询

// $result: original JSON
$result = BaseRecordModel::build()
    ->queryRaw('SELECT Id FROM Account');

// $result: Account[]
$result = Account::build()
    ->queryRaw('SELECT Id FROM Account');

按 ID 查询

此方法检索 Salesforce 中定义的所有字段，即使它们未在相应的类或 config/salesfore.php 中指定。

$result = Account::queryById('0010o00002Cn41XXXX');

创建/更新/删除记录

创建记录

$contact = new Contact();
$contact->FirstName = 'Sheep';
$contact->LastName = 'Shaun';
$contact->Email = 'shaun@example.com';
$contact->create();

Upsert/Delete 记录

/**
 * @var Contact $contact
 */
$contact = Contact::build()
    ->where('LastName', "'Shaun'")
    ->query()[0];
$contact->FirstName = 'Lamb';       // changes after object instantiation are recorded
$contact->upsert();

$contact = new Contact([            // we do not need to query first
    'Id' => $contact->Id,
]);
$contact->FirstName = 'Mince';
$contact->upsert();

$contact->delete();                 // Id is required to delete a record

// Upsert by external ID
$contact = new Contact([
    'Email' => 'bitzer@example.com',
]);
$contact->FirstName = 'Bitzer';
$contact->LastName = 'Woof';
$contact->upsert('Email');

转换规则

转换规则允许自动转换/格式化属性。

内置规则

内置规则已在 \CNSDose\Salesforce\Support\Conversion\BaseConversion::$conversions 中注册。

一些规则允许参数，例如 number:16,2 表示小数点左边16位，右边2位。

自定义规则

创建一个继承自 \CNSDose\Salesforce\Support\Conversion\BaseConversion 的类
实现所需方法
1. doDecode: 在从 API 下载数据后进行后处理
2. doEncode: 在上传到 API 之前进行预处理
通过 \CNSDose\Salesforce\Support\Conversion\BaseConversion::registerRule 注册规则
规则参数：格式 rule_name:arg1,arg2 可以用于传递参数到相应的类构造函数，例如 \CNSDose\Salesforce\Support\Conversion\Number

自定义字段

可以在 config/salesforce.php 中定义自定义字段。在名称冲突的情况下，自定义字段优先于默认字段。

示例

向对象 Custom 添加 3 个自定义字段，并适用转换规则

[
    'custom_fields' => [
        \CNSDose\Salesforce\Models\Sales\Custom::class => [
            'Float__c' => 'number:16,2',
            'Time__c' => 'time',
            'SystemModstamp' => null,
        ],
    ],
]

自定义对象

可以使用 Artisan 命令 salesforce:generate-record-model 自动为在 Salesforce 中定义的自定义对象生成模型。

$ php artisan help salesforce:generate-record-model
Description:
  Generate Salesforce record model dynamically from API

Usage:
  salesforce:generate-record-model [options] [--] <object>

Arguments:
  object

Options:
  -N, --namespace[=NAMESPACE]
      --package[=PACKAGE]
  -C, --class[=CLASS]
  -T, --token[=TOKEN]
  -A, --all-fields

示例

$ php artisan salesforce:generate-record-model -N 'MyProject\Models' -C Custom -A Custom__c
<?php
/**
 * Created automatically by salesforce-sdk.
 */

namespace MyProject\Models;

use CNSDose\Salesforce\Models\BaseRecordModel;

/**
 * Class Custom
 * @package MyProject\Models
 *
 * @method Custom[] query()
 *
 * @property string Id
 * @property string OwnerId
 * @property bool IsDeleted
 * @property string Name
 * @property mixed CurrencyIsoCode
 * @property \Carbon\Carbon CreatedDate
 * @property string CreatedById
 * @property \Carbon\Carbon LastModifiedDate
 * @property string LastModifiedById
 * @property \Carbon\Carbon SystemModstamp
 * @property bool Checkbox__c
 * @property float Currency__c
 * @property \Carbon\Carbon Date__c
 * @property \Carbon\Carbon DateTime__c
 * @property float Integer__c
 * @property float Float__c
 * @property \Carbon\Carbon Time__c
 */
class Custom extends BaseRecordModel
{
    protected static $objectApiName = 'Custom__c';
    protected $defaultFields = [
        'Id' => null,
        'OwnerId' => null,
        'IsDeleted' => 'bool',
        'Name' => null,
        'CurrencyIsoCode' => null,
        'CreatedDate' => 'datetime',
        'CreatedById' => null,
        'LastModifiedDate' => 'datetime',
        'LastModifiedById' => null,
        'SystemModstamp' => 'datetime',
        'Checkbox__c' => 'bool',
        'Currency__c' => 'number:16,2',
        'Date__c' => 'date',
        'DateTime__c' => 'datetime',
        'Integer__c' => 'number:18,0',
        'Float__c' => 'number:16,2',
        'Time__c' => 'time',
    ];
}

自定义类型-规则映射

可以使用 \CNSDose\Salesforce\Console\GenerateRecordModel::addTypeRule 将 Salesforce 类型映射到 PHP 类型/转换规则，以提高方便性。

常见的映射已在 GenerateRecordModel 中定义。

GenerateRecordModel::addTypeRule('type1', 'string', null);
GenerateRecordModel::addTypeRule('type2', '\\Carbon\\Carbon', 'date');
GenerateRecordModel::addTypeRule('type3', 'float', function ($field) {
    return sprintf('number:%s,%s', $field['precision'] - $field['scale'], $field['scale']);
});

元数据 API (SOAP API)

创建/读取/重命名/更新/Upsert/删除

// Create
// Same as Java example in https://developer.salesforce.com/docs/atlas.en-us.216.0.api_meta.meta/api_meta/meta_createMetadata.htm
$customObject = new CustomObject();
$customObject->setFullName('MyCustomObject1__c');
$customObject->setDeploymentStatus(DeploymentStatus::DEPLOYED());
$customObject->setDescription('Created by the Metadata API');
$customObject->setEnableActivities(true);
$customObject->setLabel('MyCustomObject1 Object');
$customObject->setPluralLabel('MyCustomObject1 Objects');
$customObject->setSharingModel(SharingModel::READ_WRITE());

$nameField = new CustomField();
$nameField->setType(FieldType::TEXT());
$nameField->setLabel('MyCustomObject1__c Name');
$nameField->setIsNameField(true);

$customObject->setNameField($nameField);

$customObject->create();

// Read & Update
$customObject = CustomObject::read('MyCustomObject1__c');
$customObject->setDescription('Updated description!');
$customObject->update();

// Rename
$customObject->rename('MyCustomObject2__c');

// Upsert
$customObject->setLabel('MyCustomObject1 Object');
$customObject->setPluralLabel('MyCustomObject1 Objects');
$customObject->upsert();

// Delete
$customObject->delete();

如何使用 Salesforce API 的不同版本

在 Salesforce Lightning Experience 中，从设置 | 集成 | API 下载元数据 WSDL 并将其保存在您的项目中
在配置文件中更新 api_version 和 metadata_wsdl
使用命令 salesforce:generate-metadata-model 和 salesforce:generate-record-model 生成模型（此库中的 update_models.sh 可以作为良好的起点）

cnsdose / salesforce-php

维护者

详细信息