README

A lightweight integration for interacting with Salesforce from PHP. The package supplies a stand‑alone client and query builder while also providing adapters for the garethhudson07/api framework.

Features

• Salesforce HTTP client built on Guzzle with convenience helpers for common endpoints.
• Fluent SOQL query builder supporting nested conditions, IN clauses, ordering, limits and relationship includes.
• Repository layer exposing find, first, get, create, update, upsert, upsertRecord and delete methods for Salesforce objects.
• Integration with garethhudson07/api through repository and query bridge classes and a data transformer so that resources defined in that package can query Salesforce seamlessly.
• Laravel support including a service provider for obtaining and caching OAuth tokens and optional request logging.
• Lookup utilities for retrieving and caching pick list values.
• Adapters for api-resource-loader allowing resources to be loaded from configuration files.

Although the package was designed to act as a bridge for garethhudson07/api, the client, query builder and repository classes can be used independently in any PHP project.

Installation

composer require oilstone/api-salesforce-integration

Optional Laravel setup

If your project uses Laravel you can register the service provider and publish the configuration file:

// config/app.php
'providers' => [
    \Oilstone\ApiSalesforceIntegration\Integrations\Laravel\ServiceProvider::class,
],

php artisan vendor:publish --tag=config --provider="Oilstone\\ApiSalesforceIntegration\\Integrations\\Laravel\\ServiceProvider"

Configure your Salesforce instance in config/salesforce.php and the provider will handle authentication and caching of access tokens. When the debug option is enabled each request and response is logged via Laravel's logger. Queries served from the cache are also logged with a cache flag so they can be distinguished from live requests.

OAuth access tokens are managed by SalesforceTokenManager, which caches the token under the key salesforce.access_token, derives its TTL from the expires_in field returned by Salesforce (with a 60 second safety margin), serialises concurrent token fetches with a cache lock to avoid thundering-herd requests, and transparently refreshes the token if any Salesforce call returns HTTP 401. This works out of the box with the Redis cache store.

When authenticating with the client credentials grant you must supply at least one OAuth scope. Set the SALESFORCE_SCOPES environment variable to a comma separated list (or define the scopes array in the published configuration) and the service provider will include them in the token request.

The package divides caching into three independent layers via QueryCacheHandler:

• Query cache entries persist the results of SOQL queries for a short TTL. The SOQL string itself is hashed to generate the cache key and a single flushQueryCache method invalidates every cached query in one call by rotating an internal namespace token. The query cache is also flushed automatically by any repository mutation (create, update, upsert, upsertRecord, delete).
• Entry cache entries store individual records returned from find / first lookups for a longer TTL. Each cached entry is indexed under every configured "indexable field" (the record's Id by default, plus any extra unique columns you register via setIndexableFields). Mutations invalidate the entry under each known indexable field so a record cached by Email remains in sync after an update keyed by Id. Negative results (null for "not found") are deliberately not cached, so a subsequent create is never fooled by a stale miss.
• Schema cache entries store object describe payloads and picklist value responses, which rarely change. Schema entries live in their own namespace and are not affected by flushQueryCache, so the (expensive) describe call is preserved across data mutations. Use flushSchemaCache or the --schema flag on the Artisan command to invalidate them after a Salesforce metadata change.

Configuring entry cache invalidation

By default the entry cache is keyed by the repository's identifier (Id, or whatever you set with setIdentifier). If you also look records up by other unique fields (an external ID, an email column, etc.), register them so mutations can invalidate every cached copy:

$repository = (new Repository('Contact'))
    ->setIdentifier('Id')
    ->setIndexableFields(['Id', 'Email', 'External_Id__c']);

Only register fields that uniquely identify a record. Non-unique fields (e.g. Status) are not appropriate as indexable fields. Note that if the value of an indexable field changes during an update, the cache entry keyed under the old value is left to expire via TTL — this is rarely a problem when indexable fields are immutable identifiers.

Clearing caches manually

php artisan salesforce:cache:clear                                          # Flushes all query cache entries
php artisan salesforce:cache:clear Account 001XXXXXXXXXXXXXXX               # Also forgets the entry cache for that Id
php artisan salesforce:cache:clear Account 001XXXXXXXXXXXXXXX --field=External_Id__c
php artisan salesforce:cache:clear --schema                                 # Flushes only the schema cache

Configuration

Default TTLs and behaviour can be configured via environment variables (or the corresponding keys in the published salesforce.php configuration file):

Variable	Default	Purpose
SALESFORCE_QUERY_CACHE_DEFAULT_TTL	3600	TTL (seconds) for cached SOQL query results.
SALESFORCE_ENTRY_CACHE_DEFAULT_TTL	86400	TTL (seconds) for cached individual records.
SALESFORCE_SCHEMA_CACHE_DEFAULT_TTL	86400	TTL (seconds) for cached describe / picklist payloads.
SALESFORCE_SKIP_RETRIEVAL_DEFAULT	false	When true, every cached lookup bypasses the cache on the way in (cache is still populated). Useful for long-running queue workers that need fresh reads.

You can also opt out of the cache on a single call by passing 'skip_retrieval' => true in the repository options array.

Basic usage

Stand‑alone

use GuzzleHttp\Client;
use Oilstone\ApiSalesforceIntegration\Clients\Salesforce;
use Oilstone\ApiSalesforceIntegration\Repository;

$http = new Client();
$salesforce = new Salesforce($http, $instanceUrl, $accessToken);
$accounts = (new Repository('Account'))
    ->setClient($salesforce)
    ->setDefaultConstraints([['Type', 'Customer']])
    ->newQuery()
    ->where('Name', 'like', 'Acme%')
    ->get();

With garethhudson07/api

Create a resource repository that extends the provided API adapter and let the framework resolve queries against Salesforce:

use Oilstone\ApiSalesforceIntegration\Integrations\Api\Repository as ApiRepository;

class AccountRepository extends ApiRepository
{
    protected string $object = 'Account';
    // Optionally customise the identifier column
    protected string $identifier = 'External_Id__c';
}

The package's query resolver and transformer bridge the API pipeline to Salesforce so existing endpoints defined in garethhudson07/api continue to work with Salesforce data.

Including related records

Use the with method when building a query to fetch related records. Pass the child object name (or relationship name) to include the Id and Name fields for that relationship by default:

$account = (new Repository('Account'))
    ->setClient($salesforce)
    ->newQuery()
    ->with('Museum_Facility__c')
    ->first();

You can target specific fields on the related object using a colon syntax:

$account = (new Repository('Account'))
    ->setClient($salesforce)
    ->newQuery()
    ->with('Contacts:FirstName,LastName')
    ->first();

Related data is returned as a simple array of child records without the Salesforce metadata wrappers.

Creating a fresh repository

When you need a repository for a different object without inheriting the current repository's default constraints, includes or schema defaults, use freshRepository:

$accountRepo = (new AccountRepository())->setClient($salesforce);
$facilityRepo = $accountRepo->freshRepository('Museum_Facility__c');

The returned repository is clean and can be configured independently.

Apex REST requests

Some Salesforce integrations expose Apex REST endpoints under /services/apexrest. Use the apexRest helper on the client to call these resources directly:

use GuzzleHttp\Client;
use Oilstone\ApiSalesforceIntegration\Clients\Salesforce;

$http = new Client();
$salesforce = new Salesforce($http, $instanceUrl, $accessToken);

$paymentMethods = $salesforce->apexRest('GET', 'cpm/v2/PaymentMethods');

Schema meta properties

When a resource is backed by an Api\Schema\Schema, meta properties on the schema fields control how values are fetched from Salesforce, transformed for API consumers and written back. The integration recognises the following meta keys:

Meta key	Behaviour
validationOnly	Excludes the field from every read/write operation so it can still be validated by the API schema without hitting Salesforce.
needs	Ensures additional Salesforce fields are always selected with the property (accepts a string or array of field names).
calculated	Marks the property as derived so it is never selected, has no defaults extracted and is ignored when writing back.
isRelation	Skips the property when building field lists and payloads because the value comes from relationship includes.
readonly	Omits the property from create/update payloads unless forceReverse is used on the transformer.
fixed	Forces the property to a constant value for reads and writes, and seeds that value when building defaults.
default	Provides a fallback when no explicit value is supplied and is also surfaced by Repository::getDefaultValues().
beforeTransform / afterTransform	Callables that run before/after a record is transformed for API output, letting you massage inbound values.
beforeReverse / afterReverse	Callables that run before/after values are prepared for Salesforce, giving hooks for last-mile tweaks.
delimited	Treats the field as a delimited list. Responses are exploded into arrays and outbound arrays are imploded using the delimiter string stored on the property.
isYesNo	Converts 'Yes'/'No' Salesforce strings to booleans when reading, back to Salesforce-friendly strings when writing, and applies the same mapping to query constraints.
isAddressLine	Maps a specific numbered line of a multi-line address field when transforming in either direction, rebuilding the combined field on writes.

These meta keys can be combined to tailor how each schema property interacts with Salesforce while keeping the resource definition declarative.

Resource-level transform callbacks

For cross-field shaping that should happen once around the whole schema transformation, register callbacks on the resource itself:

class AccountResource extends \Oilstone\ApiSalesforceIntegration\Integrations\ApiResourceLoader\Resource
{
    public function __construct()
    {
        parent::__construct();

        $this->beforeTransform(function (array $attributes) {
            $attributes['FullName'] = trim(($attributes['FirstName'] ?? '') . ' ' . ($attributes['LastName'] ?? ''));

            return $attributes;
        });

        $this->afterTransform(function (array $attributes) {
            $attributes['display_name'] = strtoupper($attributes['full_name'] ?? '');

            return $attributes;
        });
    }
}

beforeTransform() runs before schema mapping and receives the raw Salesforce attributes. afterTransform() runs after schema mapping and receives the transformed attributes. Both callbacks may also accept the current record and schema as later arguments when needed.

Lookups

Extend Lookup or CachedLookup to pull picklist values from Salesforce:

class IndustryLookup extends CachedLookup
{
    public static function object(): string { return 'Account'; }
    public static function field(): string { return 'Industry'; }
    public static function recordTypeId(): string { return '0123...'; }
}

$industries = IndustryLookup::all();

Exceptions

SalesforceException is thrown for non‑successful responses and provides access to the underlying error details via getErrors().

License

This package is released under the MIT license.