README

salesforce-api-php-wrapper

一个用于与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 Key工作流程的替代方案。

$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传入。

$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数据进行一般查询。只需将有效的查询传递给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']);

### 删除记录可以根据记录的 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();
    
}

chorton / salesforce-api-php-wrapper

维护者

详细信息

README

salesforce-api-php-wrapper