Datatablesbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bunta/datatablesbundle
   

   Add to config/bundles.php:

   Bunta\DatatablesBundle\SgDatatablesBundle::class => ['all' => true],
   

2. Enable in Routing Add to config/routes.yaml:

   sg_datatables:
       resource: "@SgDatatablesBundle/Resources/config/routing.yml"
       prefix: /datatables
   

3. First Use Case Annotate an entity (e.g., src/Entity/User.php):

   use Bunta\DatatablesBundle\Annotation\DataTable;
   use Bunta\DatatablesBundle\Annotation\Column;
   
   /**
    * @DataTable
    */
   class User
   {
       /**
        * @Column(name="name", type="string")
        */
       private $name;
   }
   

   Access via /datatables/user with GET params:

   $.ajax({
       url: '/datatables/user',
       data: { search: { value: 'John' } }
   });
   

Implementation Patterns

Workflows

1. CRUD Integration

   • Use DataTable annotation on entities to auto-generate API endpoints.
   • Extend with custom controllers for actions (e.g., POST /datatables/user/_action):

     // src/Controller/UserDataTableController.php
     use Bunta\DatatablesBundle\Controller\DataTableController;
     
     class UserDataTableController extends DataTableController
     {
         public function actionEdit($id)
         {
             $user = $this->getDoctrine()->getRepository(User::class)->find($id);
             // Custom logic...
         }
     }
     

2. Column Customization

   • Override column types via YAML (config/packages/sg_datatables.yaml):

     sg_datatables:
         columns:
             User:
                 email: { type: "email", searchable: true }
     

   • Use Column annotation for per-property overrides.

3. Server-Side Processing

   • Leverage DataTableBuilder for complex queries:

     $builder = $this->get('sg_datatables.builder');
     $query = $builder->createQueryBuilder(User::class)
         ->add('where', 'u.active = :active', ['active' => true])
         ->getQuery();
     

4. Frontend Integration

   • Pair with DataTables.js for client-side rendering:

     $('#user-table').DataTable({
         ajax: '/datatables/user',
         columns: [
             { data: 'name' },
             { data: 'email' }
         ]
     });
     

Integration Tips

• Doctrine Events: Hook into preFlush/postLoad for dynamic data (e.g., computed columns).
• Security: Use Symfony’s voter system to restrict table access:

  // src/Security/Voter/DataTableVoter.php
  public function supportsAttribute($attribute)
  {
      return $attribute === 'DATATABLE_ACCESS';
  }
  

• Caching: Cache queries with sg_datatables.cache_provider (default: null).

Gotchas and Tips

Pitfalls

1. Annotation Parsing

   • Issue: Annotations ignored if autoload is misconfigured.
   • Fix: Ensure composer dump-autoload runs post-install.

2. Doctrine Mismatches

   • Issue: Column annotations on non-Doctrine properties (e.g., getFullName()) cause errors.
   • Fix: Use type="method" and specify the method name:

     /**
      * @Column(name="full_name", type="method")
      */
     public function getFullName() { ... }
     

3. Routing Conflicts

   • Issue: /datatables/{entity} clashes with custom routes.
   • Fix: Override routing in config/routes.yaml:

     sg_datatables:
         path: /api/datatables
     

4. Pagination Limits

   • Issue: Default length (10) may be too low for large datasets.
   • Fix: Set globally in config:

     sg_datatables:
         default_length: 100
     

Debugging

• Enable Verbose Logging Add to config/packages/dev/sg_datatables.yaml:

  sg_datatables:
      debug: true
  

  Logs SQL queries and processing steps to var/log/dev.log.

• Check QueryBuilder Dump the generated QueryBuilder in a controller:

  $builder = $this->get('sg_datatables.builder');
  $qb = $builder->createQueryBuilder(User::class);
  dump($qb->getDQL());
  

Extension Points

1. Custom Column Types Extend Bunta\DatatablesBundle\Column\ColumnTypeInterface:

   class CustomType implements ColumnTypeInterface
   {
       public function getType() { return 'custom'; }
       public function getSearchCondition($value, $alias) {
           return "$alias LIKE :val";
       }
   }
   

   Register in services:

   services:
       sg_datatables.type.custom:
           class: App\Column\CustomType
           tags: [sg_datatables.type]
   

2. Post-Process Responses Subscribe to sg_datatables.post_process event:

   // src/EventListener/DataTableListener.php
   public function onPostProcess(PostProcessEvent $event)
   {
       $data = $event->getData();
       $data['custom_field'] = 'value';
       $event->setData($data);
   }
   

   Bind in services.yaml:

   services:
       App\EventListener\DataTableListener:
           tags: [kernel.event_listener, sg_datatables.post_process]
   

3. Override Default Templates Copy vendor/bunta/datatablesbundle/Resources/views/ to templates/bundles/sgdatatables/ and modify.