Sugarcrm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bisonlab/sugarcrm-bundle
   

   Add to AppKernel.php:

   new BisonLab\SugarCrmBundle\BisonLabSugarCrmBundle(),
   

2. Configure Add to config/packages/sugarcrm.yaml (or config.yml):

   parameters:
       sugarcrm_base_url: "http://your-sugar-instance.com"
       sugarcrm_username: "your_username"
       sugarcrm_password: "your_password"
   

   Choose a service config:

   imports:
       - { resource: "@BisonLabSugarCrmBundle/Resources/config/services_wrapper.yml" } # Direct wrapper
       # OR
       - { resource: "@BisonLabSugarCrmBundle/Resources/config/services.yml" } # NoOrmBundle integration
   

3. First Use Case Inject the service and call SugarCRM API:

   use BisonLab\SugarCrmBundle\Service\SugarService;
   
   class MyController extends AbstractController {
       public function __construct(private SugarService $sugarService) {}
   
       public function listContacts() {
           $contacts = $this->sugarService->get('Contacts');
           $results = $contacts->getEntries(['name' => 'John']);
           return $this->json($results);
       }
   }
   

Implementation Patterns

Direct Wrapper Usage (Recommended)

• Service Injection

  public function __construct(private SugarService $sugarService) {}
  

  Access modules directly:

  $accounts = $this->sugarService->get('Accounts');
  $account = $accounts->getEntry(123); // Fetch single record
  

• Common Workflows Create/Update Records:

  $account = $this->sugarService->get('Accounts');
  $account->setEntry([
      'name' => 'Acme Corp',
      'description' => 'New client',
  ]);
  $account->save();
  

  Querying:

  $contacts = $this->sugarService->get('Contacts');
  $results = $contacts->getEntries([
      'filter' => [
          'name' => ['like' => '%Doe%'],
          'status' => 'Active',
      ],
      'select_fields' => ['id', 'name', 'email'],
  ]);
  

  Relationships:

  $account = $this->sugarService->get('Accounts')->getEntry(123);
  $contacts = $account->getRelated('contacts'); // Load linked contacts
  

• Bulk Operations Use setEntries() + save() for batch updates:

  $accounts = $this->sugarService->get('Accounts');
  $accounts->setEntries([
      ['name' => 'Client A', 'id' => 1],
      ['name' => 'Client B', 'id' => 2],
  ]);
  $accounts->save();
  

NoOrmBundle Integration (Advanced)

• Entity Mapping Define a SugarEntity class extending BisonLab\NoOrmBundle\Entity\AbstractEntity:

  namespace App\Entity;
  
  use BisonLab\NoOrmBundle\Entity\AbstractEntity;
  
  class SugarContact extends AbstractEntity {
      protected $module = 'Contacts';
  }
  

  Use in services:

  $contact = new SugarContact();
  $contact->setName('Jane Doe');
  $contact->save();
  

• When to Use Prefer the direct wrapper for simplicity. Use NoOrmBundle only if:

  • You’re already using BisonLabNoOrmBundle for other integrations.
  • You need ORM-like features (e.g., events, repositories).

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Symptom: 401 Unauthorized or empty responses.
   • Fix: Verify sugarcrm_username/sugarcrm_password in parameters.yml. Ensure the user has API access in SugarCRM (Admin > Users > [User] > API Access).

2. Module Not Found

   • Symptom: Module [X] not found errors.
   • Fix: Check SugarCRM’s module name (e.g., Accounts vs. account). Use getModuleList() to debug:

     $modules = $this->sugarService->getModuleList();
     

3. Rate Limiting

   • Symptom: Timeouts or 504 Gateway Timeout.
   • Fix: SugarCRM may throttle requests. Add delays between bulk operations:

     sleep(1); // Pause between batches
     

4. Field Name Mismatches

   • Symptom: Invalid field name errors.
   • Fix: Use SugarCRM’s API to fetch field names:

     $metadata = $this->sugarService->get('Contacts')->getMetadata();
     

Debugging Tips

• Enable API Logging Add to config/packages/sugarcrm.yaml:

  parameters:
      sugarcrm_debug: true
  

  Logs will appear in var/log/sugarcrm.log.

• Raw API Calls Access the underlying client for debugging:

  $client = $this->sugarService->getClient();
  $response = $client->request('GET', '/rest/v10/Contacts');
  

• Common HTTP Errors

  Error	Cause	Solution
  400 Bad Request	Malformed payload	Validate data structure (use getMetadata()).
  403 Forbidden	Insufficient permissions	Check user role in SugarCRM.
  404 Not Found	Invalid endpoint/module	Verify module name and API version (v10).

Extension Points

1. Custom Modules Extend the wrapper for unsupported modules:

   $customModule = $this->sugarService->getClient()->getModule('CustomModule');
   

2. Event Listeners Use Symfony’s event system to intercept SugarCRM responses:

   // config/services.yaml
   BisonLab\SugarCrmBundle\EventListener\SugarResponseListener:
       tags:
           - { name: kernel.event_listener, event: sugarcrm.response, method: onResponse }
   

3. Caching Cache frequent queries (e.g., module metadata):

   $metadata = $this->sugarService->get('Contacts')->getMetadata();
   $this->cache->set('sugar_contacts_metadata', $metadata, 3600);
   

4. Async Operations Offload long-running tasks to a queue (e.g., Symfony Messenger):

   $this->messageBus->dispatch(new SyncSugarDataMessage($data));
   

Configuration Quirks

• API Version The bundle defaults to v10. For newer versions, override the client:

  # config/services.yaml
  BisonLab\SugarCrmBundle\Service\SugarService:
      arguments:
          $apiVersion: 'v11'
  

• SSL/TLS If using HTTPS, ensure sugarcrm_base_url includes https:// and SugarCRM’s SSL certificate is valid. For self-signed certs, configure the client:

  $client = $this->sugarService->getClient();
  $client->setOption('verify', false); // Not recommended for production