README

Salesforce PHP库

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

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

##入门

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

composer require darkgoldblade01/salesforce-api:~1.0

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

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

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 \DarkGold\Salesforce\AccessTokenGenerator();
    $accessToken = $tokenGenerator->createFromSalesforceResponse($token);
    
    $_SESSION['accessToken'] = $accessToken->toJson();

}

执行操作：一旦您拥有访问令牌，就可以对API执行请求。

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

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

例如

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

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

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

$sfConfig = new SalesforceConfig();
$sfClient = new \DarkGold\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 \DarkGold\Salesforce\AccessTokenGenerator();
$accessToken = $tokenGenerator->createFromSalesforceResponse($token);

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

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

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

class SFLocalFileStoreConfig implements \DarkGold\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 \DarkGold\Salesforce\TokenStore\LocalFile(new \DarkGold\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 \DarkGold\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']);

###删除记录 可以根据记录的id和类型来删除记录。

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

##错误 如果发生错误，库将抛出异常。

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

所有其他错误将抛出 DarkGold\Salesforce\Exceptions\RequestException，Salesforce错误将包含在消息中。

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

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

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

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

    echo $e->getErrorCode();
    
}