Connect Bundle Laravel Package

Getting Started

Minimal Setup for Laravel

1. Install via Composer (adjust for Laravel’s Symfony compatibility):

   composer require ae/connect-bundle
   

   Note: Laravel lacks native Symfony bundle support. Use a Service Provider wrapper or manually register services.

2. Configure Connections (config/ae_connect.php):

   return [
       'connections' => [
           'default' => [
               'username' => env('SF_USERNAME'),
               'password' => env('SF_PASSWORD'),
               'token'    => env('SF_TOKEN'),
               'client_id' => env('SF_CLIENT_ID'),
               'client_secret' => env('SF_CLIENT_SECRET'),
               'domain' => env('SF_DOMAIN', 'login.salesforce.com'),
           ],
       ],
   ];
   

3. Map a Doctrine Entity (e.g., Lead):

   use AE\ConnectBundle\Annotation\Connection;
   use Doctrine\ORM\Mapping as ORM;
   
   /**
    * @ORM\Entity
    * @Connection("default")
    */
   class Lead {
       // ...
   }
   

4. Run a One-Time Sync (via Artisan):

   php artisan ae_connect:bulk:sync Lead --insert-new
   

   Note: Use php artisan make:command to wrap commands in Laravel’s CLI.

First Use Case: Syncing Leads

1. Define a Transformer (for custom field mapping):

   use AE\ConnectBundle\Transformer\TransformerInterface;
   
   class LeadTransformer implements TransformerInterface {
       public function transform($entity, $direction) {
           if ($direction === 'outbound') {
               $entity->setSalesforceId($entity->sf_id); // Custom logic
           }
           return $entity;
       }
   }
   

   Annotate the entity:

   /**
    * @Transformer("lead_transformer")
    */
   class Lead { ... }
   

2. Trigger a Sync (via Event Listener or Cron):

   use AE\ConnectBundle\Event\SyncEvent;
   
   public function onSync(SyncEvent $event) {
       if ($event->getEntityName() === 'Lead') {
           $this->log->info('Syncing Leads...');
       }
   }
   

Key Starting Points

• Entity Mapping Docs: Define @Connection and @Transformer annotations.
• Bulk Sync Guide: Optimize large datasets with LIMIT/OFFSET.
• Commands Reference: List available Artisan commands (e.g., ae_connect:listen for real-time CDC).

Implementation Patterns

Workflow: Bidirectional Sync

1. Outbound (Laravel → Salesforce):

   • Use SalesforceConnector to push entities:

     $connector = $this->container->get('ae_connect.connector');
     $connector->save($leadEntity);
     

   • Bulk Outbound: Queue via ae_connect:bulk:outbound with --insert-new flag.

2. Inbound (Salesforce → Laravel):

   • Subscribe to Change Data Capture (CDC) via:

     php artisan ae_connect:listen Lead --connection=default
     

   • Handle events in a subscriber:

     use AE\ConnectBundle\Event\ChangeEvent;
     
     public function onChange(ChangeEvent $event) {
         $lead = $event->getEntity();
         // Process or reject changes
     }
     

3. Validation:

   • Use custom validation groups (ae_connect.inbound/ae_connect.outbound):

     use Symfony\Component\Validator\Constraints as Assert;
     
     /**
      * @Assert\NotBlank(groups={"ae_connect.inbound"})
      */
     private $salesforce_id;
     

Integration Tips

1. Laravel-Specific Adaptations:

   • Service Provider: Register AEConnect services in AppServiceProvider:

     public function register() {
         $this->app->register(\AE\ConnectBundle\AEConnectBundle::class);
     }
     

   • Queue Workers: Use Laravel’s queue system to process bulk ops:

     $this->app->make('ae_connect.queue_worker')->process();
     

2. Doctrine in Laravel:

   • Install doctrine/orm and doctrine/dbal:

     composer require doctrine/orm doctrine/dbal
     

   • Configure config/doctrine.php to point to your Laravel database.

3. Logging:

   • Override Monolog channels (as per v1.6.4):

     # config/services.php
     'Psr\Log\InboundLogger' => \Monolog\Logger::class . '@salesforce_inbound',
     

4. Error Handling:

   • Catch AE\ConnectBundle\Exception\SyncException and log via Laravel’s Log facade:

     try {
         $connector->save($entity);
     } catch (SyncException $e) {
         \Log::error($e->getMessage(), ['entity' => get_class($entity)]);
     }
     

Advanced Patterns

1. Multi-Org Sync:

   • Define connections in config and route entities dynamically:

     /**
      * @Connection({"default", "sandbox"})
      */
     class Account { ... }
     

2. Bulk Query Optimization:

   • Use SOQL LIMIT/OFFSET in bulk commands:

     php artisan ae_connect:bulk:query:import Lead --limit=1000 --offset=0
     

3. Real-Time CDC:

   • Combine ae_connect:listen with Laravel Echo/Pusher for live updates:

     // Broadcast changes via Laravel Events
     event(new LeadSynced($lead));
     

4. Custom Transformers:

   • Extend AbstractTransformer for complex logic:

     class CustomTransformer extends AbstractTransformer {
         public function transform($entity, $direction) {
             if ($direction === 'inbound') {
                 $entity->setFormattedPhone($this->formatPhone($entity->phone));
             }
             return parent::transform($entity, $direction);
         }
     }
     

Gotchas and Tips

Pitfalls

1. PCNTL Dependency:

   • Issue: PCNTL is disabled in many shared hosting/Laravel Forge environments.
   • Fix: Use parallel:workers config to limit processes or switch to sequential processing.

2. Doctrine vs. Eloquent:

   • Issue: AEConnect expects Doctrine entities. Eloquent models require manual mapping or a bridge like eloquent-doctrine.
   • Tip: Use doctrine/orm with Eloquent via illuminate/database's Doctrine integration.

3. Salesforce API Changes:

   • Issue: The package uses an older Salesforce REST SDK (v1.4.1). Newer APIs (e.g., Composite API) may break compatibility.
   • Fix: Fork and update the SDK or use a wrapper like salesforce/php-sdk.

4. Entity Manager Leaks:

   • Issue: v2.0.2 notes unclosed EntityManagers.
   • Fix: Manually close managers after bulk ops:

     $em->flush();
     $em->close();
     

5. Bulk Sync Gaps:

   • Issue: v1.4.3 mentions unprocessed batches.
   • Fix: Use --batch-size=1000 and verify progress logs.

6. UUID Handling:

   • Issue: v1.3.18 notes UUID serialization errors.
   • Fix: Ensure your sf_id field uses string type in Doctrine:

     /**
      * @ORM\Column(type="string", length=36)
      */
     private $sf_id;
     

Debugging Tips

1. Enable Debug Logs:

   • Set debug: true in config/ae_connect.php and check storage/logs/ae_connect.log.

2. SOQL Errors:

   • Validate queries with the Salesforce SOQL Explorer.
   • Use --dry-run in bulk commands to test queries.

3. Transformer Debugging:

   • Add var_dump($entity) in transformers to inspect data flow.

4. Connection Issues: