Download the PHP package wazza/sync-model-to-crm without Composer

Synchronize a Model to a Remote CRM Object

A library that will syncronise any defined database table properties/associations (inside the Model) to an external CRM provider, like HubSpot, Pipedrive and more.

Steps: Add a few property configurations to your Laravel Models, configure sync trigger via Observers or Model Mutators and monitor the logs to see how your data is automatically syncronised with a HubSpot object (like customer). You can also trigger the sync process via an event job.

Current Support:

• HubSpot:
  • Local User syncronization with the Contact object.
  • Local Entity syncronization with the Company object.
  • Associations between Contact and Company records.
  • Coming soon... Deal & Ticket objects.
• Future Support:
  • Pipedrive
  • Salesforce
  • ZohoCrm
  • etc.

Overview

The idea around this library is to make it very easy for a developer to define inside each applicable Model (like User, Entity, Order, etc.) which properties should syncronize to which CRM Provider and Environment.

After each first time successful sync, the CRM Object primary key will be stored in a mapping table against the local table primary key. This allows for quicker loading times for future changes.

Update your Model with 7 properties that define the rules for 3rd-party CRM synchronization:

• @var string|array|null $syncModelCrmEnvironment;

  config('sync_modeltocrm.api.environment') will be used if not provided.

• @var array $syncModelCrmPropertyMapping; *Required
• @var array $syncModelCrmUniqueSearch; *Required
• @var string $syncModelCrmRelatedObject;

  config('sync_modeltocrm.api.providers.{provider}.object_table_mapping') will be used if this is not provided.

• @var array $syncModelCrmDeleteRules; *Required for delete actions
• @var array $syncModelCrmActiveRules; *Required for restore actions
• @var array $syncModelCrmAssociateRules; *Required when associations are true

Looking at the below example:

1. The User Model will syncronize to both the Sandbox and Production HubSpot environments ($syncModelCrmEnvironment).
2. It will only syncronize the name and email properties to the HubSpot corresponding firstname and email fields ($syncModelCrmPropertyMapping).
3. When there are no internal mapping yet stored, the CRM record will be uniquely loaded using the email property ($syncModelCrmUniqueSearch).
4. In order for the script to know which remote CRM object relates to the User model, contact ($syncModelCrmRelatedObject) have to be defined as the remote item.
5. The ($syncModelCrmDeleteRules) property is used to instruct the CRM what action to take when a local record is deleted/removed. For example, when SoftDeletes are enabled locally, the crm will use the soft_delete rules to update the crm records or alternatively Archive the record in the crm.
6. The reverse to the above, ($syncModelCrmActiveRules) will be used to define the action that will be taken when deleted records are activated again.
7. Finally, the non-required ($syncModelCrmAssociateRules) property is used to define the relationship (associations) between objects. e.g. user to entity.

Usage

The are a few methods that you can use to initiate a Model sync.

Executing (new CrmController())->setModel($user)->execute();:

1. Directly in a controller action.
2. Using the trait inside the model as a type of Mutators function.

3. Via a Observer. e.g. inside a UserObserver to trigger after a save() event. (see below)

4. Inside an event job. This is a good method to separate the logic from the save event and put the sync in a job queue to be processed shortly after the record has been saved.

Installation

PHP 8.1 is a minimum requirement for this project.

1. Open terminal and require the package:

2. Navigate to the config directory within your Laravel project and open the app.php file.

   • Look for the providers array within the app.php file.
   • Inside the providers array, add the following line and save: Wazza\SyncModelToCrm\Providers\SyncModelToCrmServiceProvider::class, see example below:

3. In your terminal again, complete the setup by running the below commands:

4. Below are some of the environment keys that can be added to your .env configuration. If you need more information what each item does, refer to the config/sync_modeltocrm.php config file.

5. Run config:cache after you have made your env changes.

6. Done. Review any configuration file changes that you might want to change. The config file was published to the main config folder.

Looking at the logs

Depending on your log level (refer to your config file settings: 1:high to 3:low) less or more information will be written to your Laravel log file.

You can track the transactions by running tail -f {log path} or even including grep with the unique transaction 8 digit code.

Testing

Run the following command to execute tests:

Output Example:

Note: More test to follow in the next release.