README

Salesforce PHP库

一个用于与Salesforce REST API交互的简单库。

提供设置连接、请求访问令牌、刷新访问令牌、保存访问令牌以及向API发起调用等方法。

入门

安装： 应通过Composer安装此包并将其锁定到主版本

composer require crunch-accounting/salesforce-api:~1.0

获取OAuth令牌

用户交互方式： 您需要为用户获取一个访问令牌，所有后续请求都将针对此用户执行。

$sfClient = \Crunch\Salesforce\Client::create('https://test.salesforce.com/', 'clientid', 'clientsecret', 'v37.0');

if ( ! isset($_GET['code'])) {

    $url = $sfClient->getLoginUrl('http://example.com/sf-login');
    header('Location: '.$url);
    exit();

} else {

    $token = $sfClient->authorizeConfirm($_GET['code'], 'http://example.com/sf-login');
    $tokenGenerator = new \Crunch\Salesforce\AccessTokenGenerator();
    $accessToken = $tokenGenerator->createFromSalesforceResponse($token);
    
    $_SESSION['accessToken'] = $accessToken->toJson();

}

拥有用户名和密码时： 使用此方法时，您还需要将安全令牌附加到密码上。请注意，此方法应作为旧API密钥工作流程的替代方案。

$sfClient = \Crunch\Salesforce\Client::create('https://test.salesforce.com/', 'clientid', 'clientsecret');
$sfClient->login('username', 'passwordAndSecurityTokenAppended');

执行操作： 一旦您有了访问令牌，您就可以向API发起请求。

$sfClient = \Crunch\Salesforce\Client::create('https://test.salesforce.com/', 'clientid', 'clientsecret');
$tokenGenerator = new \Crunch\Salesforce\AccessTokenGenerator();
$accessToken = $tokenGenerator->createFromJson($_SESSION['accessToken']);
$sfClient->setAccessToken($accessToken);

$results = $sfClient->search('SELECT Name, Email FROM Lead Limit 10');
print_r($results);

令牌将在一小时后过期，因此您应确保检查过期时间并相应地刷新。

设置Salesforce客户端

客户端可以通过两种方式配置，您可以通过调用上面的静态create方法并传入登录URL和OAuth详细信息来配置客户端，或者您可以使用下面的示例中的配置对象。当您需要从IoC容器中解析客户端时，这很有用。

客户端的配置数据通过一个配置文件传入，该文件必须实现 \Crunch\Salesforce\ClientConfigInterface

例如

class SalesforceConfig implements \Crunch\Salesforce\ClientConfigInterface {

    /**
     * @return string
     */
    public function getLoginUrl()
    {
        return 'https://test.salesforce.com/';
    }

    /**
     * @return string
     */
    public function getClientId()
    {
        return 'clientid';
    }

    /**
     * @return string
     */
    public function getClientSecret()
    {
        return 'clientsecret';
    }
    
    /**
     * Version of the API you wish to use
     * @return string
     */
    public function getVersion()
    {
        return 'v37.0';
    }
}

提供了一个配置类，如果需要可以使用。 \Crunch\Salesforce\ClientConfig

然后可以使用配置对象和Guzzle v4客户端实例化Salesforce客户端。

$sfConfig = new SalesforceConfig();
$sfClient = new \Crunch\Salesforce\Client($sfConfig, new GuzzleHttp\Client());

身份验证

身份验证通过oauth2进行，可以使用 getLoginUrl 方法生成登录URL，您应将此返回URL传递给OAuth过程的发送阶段。

$url = $sfClient->getLoginUrl('http://exmaple.com/sf-login');

您应将用户重定向到此返回的URL，完成操作后，他们将带着查询字符串中的代码被重定向回。

然后可以完成身份验证的第二阶段。

$token = $sfClient->authorizeConfirm($_GET['code'], 'http://exmaple.com/sf-login');

从这里返回的令牌是原始数据，可以传递给访问令牌生成器以创建 AccessToken。

$tokenGenerator = new \Crunch\Salesforce\AccessTokenGenerator();
$accessToken = $tokenGenerator->createFromSalesforceResponse($token);

存储访问令牌

此访问令牌应被存储。提供了一个将此存储在文件系统上的方法，但这不是必需的。

上面的示例使用了PHP会话来实现相同的结果。

需要使用访问令牌生成器和实现 \Crunch\Salesforce\TokenStore\LocalFileConfigInterface 的配置类来实例化 LocalFileStore 对象。

class SFLocalFileStoreConfig implements \Crunch\Salesforce\TokenStore\LocalFileConfigInterface {

    /**
     * The path where the file will be stored, no trailing slash, must be writable
     *
     * @return string
     */
    public function getFilePath()
    {
        return __DIR__;
    }
}

然后可以创建并使用令牌存储来将访问令牌保存到本地文件系统以及检索以前保存的令牌。

$tokenStore = new \Crunch\Salesforce\TokenStore\LocalFile(new \Crunch\Salesforce\AccessTokenGenerator, new SFLocalFileStoreConfig);

//Save a token
$tokenStore->saveAccessToken($accessToken);

//Fetch a token
$accessToken = $tokenStore->fetchAccessToken();

刷新令牌

访问令牌在过期前仅有效1小时，因此您应定期检查其状态并相应地刷新。

$accessToken = $tokenStore->fetchAccessToken();

if ($accessToken->needsRefresh()) {

	$accessToken = $sfClient->refreshToken();

    $tokenStore->saveAccessToken($accessToken);
}

发起请求

在发起请求之前，您应按照上面的示例实例化客户端，然后将访问令牌分配给它。

$sfConfig = new SalesforceConfig();
$sfClient = new \Crunch\Salesforce\Client($sfConfig, new \GuzzleHttp\Client());

$sfClient->setAccessToken($accessToken);

执行SOQL查询

这是一个强大的选项，用于对您的Salesforce数据进行一般查询。只需将有效的查询传递给搜索方法，即可返回结果数据。

$data = $sfClient->search('SELECT Email, Name FROM Lead LIMIT 10');

检索单个记录

如果您知道记录的ID和类型，您可以从中检索一组字段。

$data = $sfClient->getRecord('Lead', '00WL0000008wVl1MDE', ['name', 'email', 'phone']);

创建和更新记录

创建和更新记录的过程非常相似，可以按照以下步骤执行。createRecord方法将返回新创建记录的id。

$data = $sfClient->createRecord('Lead', ['email' => 'foo@example.com', 'Company' => 'New test', 'lastName' => 'John Doe']);

$sfClient->updateRecord('Lead', '00WL0000008wVl1MDE', ['lastName' => 'Steve Jobs']);
// or with the above freshly created client
$sfClient->updateRecord('Lead', $data, ['lastName' => 'Steve Jobs']);

删除记录

可以根据记录的id和类型进行删除。

$sfClient->deleteRecord('Lead', '00WL0000008wVl1MDE');

错误

如果出现问题，库将抛出异常。

如果是一个认证异常，例如令牌过期，这将作为Crunch\Salesforce\Exceptions\AuthenticationException，您可以使用getMessage和getErrorCode方法获取详细情况。

所有其他错误都将作为Crunch\Salesforce\Exceptions\RequestException，salesforce错误将在消息中显示。

try {
    
    $results = $sfClient->search('SELECT Name, Email FROM Lead Limit 10');
    print_r($results);

} catch (\Crunch\Salesforce\Exceptions\RequestException $e) {

    echo $e->getMessage();
    echo $e->getErrorCode();

} catch (\Crunch\Salesforce\Exceptions\AuthenticationException $e) {

    echo $e->getErrorCode();
    
}

morloderex / salesforce-api

维护者

详细信息