Download the PHP package lyonstahl/salesforce without Composer

Salesforce REST API Client

Installation

Ensure you have composer installed, then run the following command:

composer require lyonstahl/salesforce

That will fetch the library and its dependencies inside your vendor folder.

If you want a simple API for bulding SOQL queries, we suggest lyonstahl/soql-builder

Requirements

• PHP 7.3+
• Composer 2.0+

Features

• OAuth with password grant type
• Create, update, delete, upsert, and query records
• Object representation of Salesforce records with LyonStahl\Salesforce\Record
• Field validation and object mapping
• Extendable code: add custom objects or validation rules

Setting up a Connected App

Before you begin, you need to have set up a "Connected App" in Salesforce and get a consumerKey, consumerSecret, username, and password to allow Api access.

Note, this process may vary depending on changes to the Salesforce website, or on your Salesforce account and settings.

_Check Salesforce's Help Docs to verify._

1. Log into to your Salesforce org
2. Click on Setup in the upper right-hand menu
3. Under Build click Create → Apps
4. Scroll to the bottom and click "New" under Connected Apps.
5. Enter the following details for the remote application:
   • Connected App Name
   • API Name
   • Contact Email
   • Under the API dropdown, enable OAuth Settings
   • Callback URL
   • Select Access Scope (If you need a refresh token, specify it here)
6. Click Save, and store your access credentials in a safe place.

Usage

Creating a new Api client and connecting:

The following examples use a Salesforce object named Example that has a field Name.

Executing Basic SOQL Queries:

If you need to use php values in your query, put {tokens} in your SOQL and pass the values separately via query()'s second argument. The values will be properly quoted and escaped based on their type, and interpolated into the query:

Fetching a Record by Id:

Creating a new Record:

Updating an existing Record:

Deleting a Record:

Advanced Usage

Extending the Record class

The included LyonStahl\Salesforce\Record class can be used without modification as a generic "salesforce record" implementation - it will automatically set properties based on what's fetched from the Api. However, the intent is that applications will extend from it and define the properties needed for each of their Salesforce objects. This allows for a consistent schema that your code can rely on, and even lets you implement some level of validation directly in your application.

To build your own Salesforce Object, you must:

• extend from LyonStahl\Salesforce\Record
• define the object fields as public properties
• list any properties that must not be included in update() calls (e.g., renamed fields, nested objects or object lists) in UNEDITABLE_FIELDS.
• add any necessary logic in setField() (e.g., building a new object if your record has a relation)
• add any desired logic in validateField()

Using our "Example" object from above,

Inline Records and Record Lists

SOQL allows queries for nested objects and queries, which appear in results as inline records and query results respectively. This library does understand results from such queries, but your Record subclasses must define properties in a particular way to support them.

For example, a query similar to SELECT Manager.Id, Manager.Name, (SELECT Id, Name FROM Members) FROM Teams would require a Record class like so:

Where there is an inline object, the property should be typed as the corresponding Record subclass. For any record type where you're not making a Record subclass, type the property as Record — though this is obviously less useful.

Where there is a subquery, the property should be typed as a Result instance. Among other things, this allows the Result to support paginated subqueries.

Object Mapping

Finally, to allow the Api Client take advantage of your subclasses, you must provide an $objectMap so it knows which PHP classes correspond to which Salesforce record types. Without this, you'll end up with generic Record instances for everything. Nested Results will be provided the same $objectMap as their parent Result instance.

Field Validation

Some basic validation functions are included in LyonStahl\Salesforce\Validator. These methods all take the value to validate as the first argument, and can have other arguments depending on needs. Follow this same pattern to implement additional validation functions for your own objects as needed.

Handling Errors

All Runtime Exceptions thrown from this library will be an instance of LyonStahl\Salesforce\Error.

Exceptions are grouped into the following types:

• LyonStahl\Salesforce\Exceptions\SalesforceException:

  Errors originating from the Salesforce API, including HTTP errors (e.g., connection timeouts)

• LyonStahl\Salesforce\Exceptions\AuthException:

  Authentication failures or attempts to use the HttpClient before authentication has succeeded

• LyonStahl\Salesforce\Exceptions\ResultException:

  Errors parsing or handling Salesforce Api results or records; these will usually indicate a problem in your custom Record classes

• LyonStahl\Salesforce\Exceptions\UsageException:

  Errors arising from incorrect library usage; these will usually indicate a runtime problem in your application code

• LyonStahl\Salesforce\Exceptions\ValidationException:

  Validation errors.

Running for development with Docker

We have included a Dockerfile to make it easy to run the tests and debug the code. You must have Docker installed. The following commands will build the image and run the container:

1. docker build -t lyonstahl/salesforce --build-arg PHP_VERSION=8 .
2. docker run -it --rm -v ${PWD}:/var/www/sapi lyonstahl/salesforce sh

Debugging with XDebug in VSCode

Docker image is configured with XDebug. To debug the code with VSCode, follow these steps:

1. Install the PHP Debug extension in VSCode

2. Add a new PHP Debug configuration in VSCode:

   {
       "name": "XDebug Docker",
       "type": "php",
       "request": "launch",
       "port": 9003,
       "pathMappings": {
           "/var/www/sapi/": "${workspaceRoot}/"
       }
   }

3. docker run -it --rm -v ${PWD}:/var/www/sapi --add-host host.docker.internal:host-gateway lyonstahl/salesforce sh
4. Start debugging in VSCode with the 'XDebug Docker' configuration.

Testing

This library ships with PHPUnit for development. Composer file has been configured with some scripts, run the following command to run the tests:

composer test