Connect Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require ae/connect-bundle
   

   Enable in config/bundles.php:

   return [
       // ...
       AdvisorsExcel\ConnectBundle\AEConnectBundle::class => ['all' => true],
   ];
   

2. Configure Basic Connection Define credentials in config/packages/ae_connect.yaml:

   ae_connect:
       connections:
           default:
               username: 'your@email.com'
               password: 'your_password'
               security_token: 'your_token'
               client_id: 'your_client_id'  # For OAuth
               client_secret: 'your_client_secret'  # For OAuth
   

3. Map a Doctrine Entity Annotate an entity (e.g., src/Entity/Lead.php):

   use AdvisorsExcel\ConnectBundle\Annotation\SalesforceEntity;
   
   /**
    * @SalesforceEntity("Lead")
    */
   class Lead
   {
       // ...
   }
   

4. First Sync (Outbound) Use the CLI command to push data to Salesforce:

   php bin/console ae:connect:sync:outbound Lead
   

Implementation Patterns

Workflows

1. Entity Mapping

   • Use @SalesforceEntity to link Doctrine entities to Salesforce objects.
   • Customize field mappings via YAML (config/packages/ae_connect/entity_mapping.yaml):

     Lead:
         fields:
             firstName: 'FirstName'
             lastName: 'LastName'
             email: 'Email'
     

2. Inbound/Outbound Sync

   • Outbound (Push to Salesforce):

     $sync = $this->get('ae_connect.sync');
     $sync->outbound('Lead', ['FirstName' => 'John', 'LastName' 'Doe']);
     

   • Inbound (Pull from Salesforce):

     $leads = $this->get('ae_connect.sync')->inbound('Lead', ['Id' => '001xx000003D...']);
     

3. Bulk Operations

   • Use the bulk command for large datasets:

     php bin/console ae:connect:bulk:outbound Lead --file=data.csv
     

   • Configure bulk settings in config/packages/ae_connect.yaml:

     ae_connect:
         bulk:
             batch_size: 200
             chunk_size: 10000
     

4. Transformers

   • Extend AbstractTransformer to customize data before/after sync:

     use AdvisorsExcel\ConnectBundle\Transformer\AbstractTransformer;
     
     class LeadTransformer extends AbstractTransformer
     {
         public function transformOutbound($entity)
         {
             $entity->set('CustomField__c', 'Processed');
             return $entity;
         }
     }
     

   • Register in services.yaml:

     services:
         App\Transformer\LeadTransformer:
             tags: [ae_connect.transformer]
     

5. Validation

   • Use built-in validators or create custom ones:

     # config/packages/ae_connect/validation.yaml
     Lead:
         validators:
             - 'NotBlank: { fields: [Email] }'
             - '@App\Validator\Constraints\CustomLeadValidator'
     

Integration Tips

• Event Listeners Trigger actions post-sync via events:

  use AdvisorsExcel\ConnectBundle\Event\SyncEvent;
  
  $dispatcher->addListener(SyncEvent::OUTBOUND_POST, function (SyncEvent $event) {
      // Log or notify after sync
  });
  

• Queueing (Enqueue) Offload sync jobs to a queue for long-running operations:

  # config/packages/ae_connect.yaml
  ae_connect:
      queue: true
  

  Configure Enqueue in config/packages/enqueue.yaml.

• OAuth Flow For OAuth connections, use the runtime_connections feature:

  ae_connect:
      connections:
          oauth:
              type: oauth
              client_id: 'your_client_id'
              client_secret: 'your_client_secret'
              redirect_uri: 'https://your-app.com/oauth/callback'
  

Gotchas and Tips

Pitfalls

1. PCNTL Dependency

   • The bundle requires pcntl for multi-process bulk operations. Ensure it’s enabled in php.ini:

     extension=pcntl
     

   • Workaround: Use --processes=1 in bulk commands if pcntl is unavailable.

2. Field Mapping Conflicts

   • Salesforce field names are case-insensitive, but Doctrine fields are not. Ensure mappings align exactly:

     # Wrong: "email" vs "Email"
     # Correct: "Email" (matches Salesforce API)
     

3. Bulk API Limits

   • Salesforce imposes Bulk API limits. Monitor job statuses via:

     php bin/console ae:connect:bulk:status
     

4. Caching Issues

   • Clear the cache after changing mappings or configurations:

     php bin/console cache:clear
     

5. OAuth Token Expiry

   • Runtime OAuth connections require manual token refresh. Use the refresh command:

     php bin/console ae:connect:oauth:refresh oauth
     

Debugging

1. Enable Verbose Logging

   php bin/console ae:connect:sync:outbound Lead -vvv
   

   Logs appear in var/log/ae_connect.log.

2. Dry Runs Test mappings without syncing:

   php bin/console ae:connect:validate Lead
   

3. Command Reference

   • List all available commands:

     php bin/console list ae_connect
     

   • Common commands:

     Command	Purpose
     ae:connect:sync:outbound	Push data to Salesforce
     ae:connect:sync:inbound	Pull data from Salesforce
     ae:connect:bulk:outbound	Bulk push with CSV/JSON input
     ae:connect:bulk:status	Check bulk job status
     ae:connect:oauth:authorize	Initiate OAuth flow

Extension Points

1. Custom Connection Strategies Extend AbstractConnection to support non-Salesforce targets (e.g., HubSpot):

   use AdvisorsExcel\ConnectBundle\Connection\AbstractConnection;
   
   class HubSpotConnection extends AbstractConnection
   {
       public function getClient()
       {
           return new HubSpotClient();
       }
   }
   

   Register in services.yaml:

   services:
       App\Connection\HubSpotConnection:
           tags: [ae_connect.connection]
   

2. Custom Validators Create a validator class and tag it:

   use Symfony\Component\Validator\ConstraintValidatorInterface;
   
   class CustomLeadValidator implements ConstraintValidatorInterface
   {
       public function validate($value, Constraint $constraint)
       {
           // Custom logic
       }
   }
   

   # services.yaml
   App\Validator\CustomLeadValidator:
       tags: [validator.constraint_validator]
   

3. Event Subscribers Listen for sync events to trigger side effects (e.g., notifications):

   use AdvisorsExcel\ConnectBundle\Event\SyncEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class SyncSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               SyncEvent::OUTBOUND_PRE => 'onOutboundPre',
               SyncEvent::INBOUND_POST => 'onInboundPost',
           ];
       }
   
       public function onOutboundPre(SyncEvent $event) { /* ... */ }
       public function onInboundPost(SyncEvent $event) { /* ... */ }
   }
   

4. Override Default Services Customize the bundle’s services (e.g., ae_connect.sync) in config/services.yaml:

   services:
       ae_connect.sync:
           class: App\Service\CustomSyncService
           arguments: ['@ae_connect.connection_manager']