Sonata Admin Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require splash/sonata-admin
   

   Enable the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Splash\SonataAdminBundle\SplashSonataAdminBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Configure the bundle in config/packages/splash_sonata_admin.yaml:

   splash_sonata_admin:
       connectors: ['connector1', 'connector2']  # Define your Splash Connectors
       sonata_admin:
           dashboard_groups: ['Group1', 'Group2']  # Group your admin panels
   

3. First Use Case: CRUD Integration Extend a Sonata Admin class to integrate with Splash:

   use Splash\SonataAdminBundle\Admin\SplashAdmin;
   use Splash\SonataAdminBundle\Admin\SplashAdminInterface;
   
   class PostAdmin extends SplashAdmin implements SplashAdminInterface
   {
       protected function configureSplash()
       {
           $this->setSplashConnector('connector1');
           $this->setSplashModel('post');
       }
   }
   

4. Register the Admin Add the admin to your services.yaml:

   services:
       App\Admin\PostAdmin:
           tags: [sonata.admin]
   

Implementation Patterns

Workflow: Syncing Data Between Sonata and Splash

1. Model Mapping Define how Sonata entities map to Splash models in your configureSplash() method:

   protected function configureSplash()
   {
       $this->setSplashModel('post')
             ->setSplashFields([
                 'title' => 'title',
                 'content' => 'body',
                 'published_at' => 'date_published',
             ]);
   }
   

2. Automatic Sync on Save Override prePersist() and preUpdate() to sync data to Splash:

   public function prePersist($post)
   {
       $this->syncToSplash($post);
   }
   
   public function preUpdate($post)
   {
       $this->syncToSplash($post);
   }
   

3. Bulk Operations Use the syncCollectionToSplash() method for bulk updates:

   public function syncCollectionToSplash($posts)
   {
       $this->getSplashService()->syncCollection($posts, $this->getSplashModel());
   }
   

4. Event-Driven Sync Listen to Sonata events to trigger syncs:

   // In a service or event subscriber
   $event->getAdminPool()->getAdminByAdminCode('post')->syncToSplash($event->getObject());
   

Integration Tips

• Custom Field Mappers Extend Splash\SonataAdminBundle\Mapper\FieldMapperInterface for custom field transformations:

  class CustomFieldMapper implements FieldMapperInterface
  {
      public function map($sonataValue, $splashField)
      {
          return strtoupper($sonataValue);
      }
  }
  

  Register it in your admin:

  $this->setFieldMapper('title', new CustomFieldMapper());
  

• Conditional Sync Use shouldSyncToSplash() to control when sync happens:

  protected function shouldSyncToSplash($object)
  {
      return $object->isPublished(); // Only sync published posts
  }
  

• Error Handling Implement SplashSyncExceptionHandlerInterface to customize error responses:

  class CustomExceptionHandler implements SplashSyncExceptionHandlerInterface
  {
      public function handle(SplashSyncException $exception)
      {
          // Log or notify the user
      }
  }
  

Gotchas and Tips

Pitfalls

1. Connector Configuration

   • Issue: Forgetting to configure the Splash connector in splash_sonata_admin.yaml.
   • Fix: Ensure connectors are properly defined and the Splash SDK is initialized elsewhere in your app.

2. Field Mismatches

   • Issue: Splash expects a field name that doesn’t match your Sonata entity.
   • Fix: Use setSplashFields() to explicitly map fields. Example:

     $this->setSplashFields(['created_at' => 'date_created']);
     

3. Circular Dependencies

   • Issue: Sonata Admin and Splash models reference each other, causing serialization errors.
   • Fix: Exclude Splash-specific fields from Sonata’s serialization or use @Ignore annotations.

4. Bulk Sync Performance

   • Issue: Slow bulk operations due to large datasets.
   • Fix: Use chunking or queue the sync jobs:

     $this->getSplashService()->syncCollectionInQueue($posts, $this->getSplashModel());
     

5. Caching Conflicts

   • Issue: Cached data in Sonata Admin doesn’t reflect changes from Splash.
   • Fix: Clear the cache after sync operations or disable caching for synced fields:

     $this->setCacheableFields([]); // Disable caching for all fields
     

Debugging Tips

1. Enable Splash Logging Add to config/packages/splash_sonata_admin.yaml:

   splash_sonata_admin:
       debug: true
   

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

2. Validate Splash Responses Use the getLastSplashResponse() method to inspect the last API call:

   $response = $this->getSplashService()->getLastResponse();
   dump($response->getContent());
   

3. Test with a Single Object Before bulk syncing, test with a single object to isolate issues:

   $post = $this->getModelManager()->find($this->getClass(), 1);
   $this->syncToSplash($post);
   

Extension Points

1. Custom Sync Logic Override syncToSplash() to add pre/post-sync logic:

   protected function syncToSplash($object)
   {
       $this->preSyncLogic($object);
       parent::syncToSplash($object);
       $this->postSyncLogic($object);
   }
   

2. Webhook Integration Listen for Splash webhook events and update Sonata entities:

   // In a controller or event subscriber
   $this->get('sonata.admin.post')->updateFromSplash($webhookData);
   

3. Custom Dashboard Widgets Extend the dashboard with Splash-specific widgets:

   use Splash\SonataAdminBundle\Dashboard\SplashDashboardWidget;
   
   class SplashStatsWidget extends SplashDashboardWidget
   {
       public function execute($context)
       {
           return $this->getSplashService()->getStats();
       }
   }
   

   Register it in config/packages/sonata_admin.yaml:

   sonata_admin:
       dashboard:
           groups:
               stats:
                   widgets:
                       - ['splash_stats', SplashStatsWidget, {}]
   

4. Custom Splash Services Bind your own Splash service to replace the default:

   services:
       splash.sonata_admin.service:
           class: App\Service\CustomSplashService
           arguments: ['@splash.client']
           tags: [splash.sonata_admin.service]