README

Salesforce PHP库

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

提供设置连接、请求访问令牌、刷新访问令牌、保存访问令牌以及针对API进行调用的方法。

入门

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

composer require napp/salesforce-api:~1.0

获取OAuth令牌

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

$sfClient = \Napp\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');

}

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

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

执行操作： 获取访问令牌后，您可以针对API执行请求。

$sfClient = \Napp\Salesforce\Client::create('https://test.salesforce.com/', 'clientid', 'clientsecret');
$tokenGenerator = new \Napp\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容器中解析客户端时，这很有用。

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

例如

class SalesforceConfig implements \Napp\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';
    }
}

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

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

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

身份验证

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

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

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

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

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

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

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

存储访问令牌

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

上面的示例使用了php session来实现相同的结果。

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

class SFLocalFileStoreConfig implements \Napp\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 \Napp\Salesforce\TokenStore\LocalFile(new \Napp\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 \Napp\Salesforce\Client($sfConfig, new \GuzzleHttp\Client());

$sfClient->setAccessToken($accessToken);

执行SOQL查询

这是一个针对您的Salesforce数据执行一般查询的强大选项。只需将有效的查询传递给search方法，并将返回结果数据。

$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');

错误

如果出现错误，库将抛出异常。

如果是认证异常，例如过期令牌，这将是Napp\Salesforce\Exceptions\AuthenticationException，您可以使用getMessage和getErrorCode方法获取详细信息。

所有其他错误将是Napp\Salesforce\Exceptions\RequestException，Salesforce错误将包含在消息中。

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

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

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

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

    echo $e->getErrorCode();
    
}

napp / salesforce-api

维护者

详情