Eloquent Sales Force

Work with SalesForce APIs via the Eloquent Model.

Installation

Install via composer

composer require rob-lester-jr04/eloquent-sales-force

Register Service Provider

Note! This and next step are optional if you use laravel>=5.5 with package auto discovery feature.

Add service provider to config/app.php in providers section

Lester\EloquentSalesForce\ServiceProvider::class,

Publish Configuration File

**Note that this is optional and in most cases, the configuration here is not needed.

php artisan vendor:publish --provider="Lester\EloquentSalesForce\ServiceProvider" --tag="config"

Usage

Setting up your connected app

Log into to your Salesforce org
Click on Setup in the upper right-hand menu
Under Build click Create > Apps
Scroll to the bottom and click New under Connected Apps.
Enter the following details for the remote application:
- Connected App Name
- API Name
- Contact Email
- Enable OAuth Settings under the API dropdown
- Callback URL
- Select access scope (If you need a refresh token, specify it here)
Click Save

After saving, you will now be given a Consumer Key and Consumer Secret. Update your config file with values for consumerKey, consumerSecret, and loginURL.

Configuration

In your config/database.php file, add the following driver to the connections array

'soql' => [
    'driver' => 'soql',
    'database' => null,
    'consumerKey'    => env('CONSUMER_KEY'),
    'consumerSecret' => env('CONSUMER_SECRET'),
    'loginURL'       => env('LOGIN_URL'),
    // Only required for UserPassword authentication:
    'username'       => env('USERNAME'),
    // Security token might need to be ammended to password unless IP Address is whitelisted
    'password'       => env('PASSWORD')
],

If you need to modify any more settings for Forrest, publish the config file using the artisan command:

php artisan vendor:publish

You can find the config file in: config/eloquent_sf.php. Any of the same settings that Forrest recognizes will be available to set here.

Using Models

Create a model for the object you want to use, example: artisan make:model Lead

Open the model file, it will look like this:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Lead extends Model
{
    //
}

Replace the use statement so your model looks like:

<?php

namespace App;

use Lester\EloquentSalesForce\Model;

class Lead extends Model
{
    //
}

Now use it like you normally would!

$leads = Lead::where('email', 'user@test.com')->get();

$lead = Lead::find('00Q1J00000cQ08eUAC');

Update properties like you normally would...

$lead->FirstName = 'Robert';
$lead->save();

Columns

By default, the selected columns for the record will be the compact layout defined in the SalesForce instance. This is usually enough. If you need to pull specific columns, you have some options.

// Per select
$object = Contact::select('Id', 'Name')->get();

You can also define on the model what columns you want to bring back with each record. Add public $columns to the top of the model.

...

    public $columns = [
        'Name',
        'Id',
        'Email',
    ];

To return the columns currently available on a model, use the describe method on the object.

$fields = Lead::describe();

Inserting and Updating

Insert

$lead = new Lead();
$lead->FirstName = 'Foo';
$lead->LastName = 'Bar';
$lead->Company = 'Test';
$lead->save();

OR:

$lead = Lead::create(['FirstName' => 'Foo', 'LastName' => 'Bar', 'Company' => 'Test Company']);

Bulk Insert

$leads = collect([
	new Lead(['Email' => 'email1@test.com']),
	new Lead(['Email' => 'email2@test.com'])
]);

Lead::insert($leads);

Update

$lead = Lead::first();
$lead->LastName = 'Lester';
$lead->save();

OR:

$lead->update(['LastName' => 'Lester']);

Bulk Update

The bulk update method is model agnostic - meaning that this capability, within salesforce, accepts a mix of object types in the collection that gets sent. So this method therefore exists in the new SObjects facade.

$accounts = Account::where('Company', 'Test Company')->get(); // collection of accounts.

$accounts = $accounts->map(function($account) {
	$account->Company = 'New Company Name';
	return $account;
});

SObjects::update($accounts); // Sends all these objects to SF with updates.

SalesForce will execute each update individually and will not fail the batch if any individual update fails. If you want success to be dependent on all updates succeeding (all or nothing), then you can pass true as the second parameter. If this is set, the batch of updates must all succeed, or none will.

SObjects::update($accounts, true); // All or none.

Columns, Where, Ordering

Columns/Properties

By default, the object is loaded with the columns found in the primary compactLayout. If you'd like additional columns, you would use the select method on the model. For example:

$leads = Lead::select('Id', 'Name', 'Email', 'Custom_Field__c')->limit(10)->get();

Where / Order By

The where and orderBy methods work as usual as well.

$contacts = Contact::where('Email', 'test@test.com')->first();

$contacts = Contact::where('Name', 'like', 'Donuts%')->get();

$contacts = Contact::limit(20)->orderBy('Name')->get();

Delete

Exactly as you'd expect.

$lead = Lead::first();

$lead->delete();

Relationships

Relationships work the same way.

Create a model like above for Account and Contact

In the Contact model, add a method for a relationship like you normally would

## Contact.php
public function account()
{
	return $this->belongsTo(Account::class);
}

So you can call now:

$contact = Contact::where('email', 'some@email.com')->first();
$account = $contact->account;

And the reverse is true

## Account.php
public function contacts()
{
	return $this->hasMany(Contact::class);
}

$contacts = $account->contacts;

Joins

You are also able to use manual joins

$account = Account::join('Contact', 'AccountId')->first();

These aren't as easy to work with as Relationships because the SalesForce API still returns the array nested in the records property.

Custom Objects

To use custom objects (or an object with a special object name, different from the model), set the protected $table property in the model.

<?php

namespace App;

use Lester\EloquentSalesForce\Model;

class TouchPoint extends Model
{
    protected $table = 'TouchPoint__c';

    /** Any other overrides **/
}

The SObjects Facade

This is a new feature to the package. The SObjects facade serves the purpose of exposing any global features not model specific, such as authentication and mass updates, but also it is a pass-thru mechanism for the Forrest facade.

Any methods such as get, post, patch, resources, etc will pass through to the Forrest facade and accept parameters respectively.

Authentication

The authenticate() method in the facade will return the token information that has been stored in cache/session.

Anonymous Objects

Sometimes you want to grab a record from SalesForce casually without having to pre-generate a model for it. Now you can do that easily with the object method on the facade. Example:

$lead = SObjects::object('Lead')->find('01t1J00000BVyNBQA1'); // Get a single record by ID

$accounts = SObjects::object('Account')->get(); // Returns all of the specified object. `all` won't work here.

$contact = SObjects::object('Contact')->where('Name', 'like', 'Barns %')->get(); // Get all contacts where name starts with Barns.

$newLead = SObjects::object('Lead', ['Email'=>'test@test.com', 'FirstName' => 'Test', 'LastName' => 'Name', 'Company' => 'Test Company'])->save(); // Save a new lead;

The class used for each object returned will be Lester\EloquentSalesForce\SalesForceObject.

Security

If you discover any security related issues, please email instead of using the issue tracker.

Credits

This package is bootstrapped with the help of melihovv/laravel-package-generator.

stzahi / EloquentSalesForce