Data List Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aygon/data-list-bundle
   

   Add to AppKernel.php (Symfony 2.x):

   new Aygon\DataListBundle\AygonDataListBundle(),
   

2. First Use Case: Basic Data List Define a list in a controller:

   use Aygon\DataListBundle\DataList;
   
   public function listAction()
   {
       $list = new DataList();
       $list->setModel('AppBundle:Post'); // Doctrine entity
       $list->setFields(['title', 'content']); // Fields to display
       $list->setOrder('createdAt', 'DESC');
   
       return $this->render('AppBundle:Post:list.html.twig', [
           'list' => $list->getData(),
       ]);
   }
   

3. Twig Template

   {% for item in list %}
       <tr>
           <td>{{ item.title }}</td>
           <td>{{ item.content }}</td>
       </tr>
   {% endfor %}
   

4. Pagination

   $list->setItemsPerPage(10); // Default: 20
   

Implementation Patterns

Common Workflows

1. Filtering with Forms

   $list->setFilterForm([
       'title' => ['type' => 'text', 'label' => 'Search Title'],
       'published' => ['type' => 'checkbox', 'label' => 'Published Only'],
   ]);
   

   Render the form in Twig:

   {{ form_start(list.filterForm) }}
       {{ form_widget(list.filterForm) }}
       <button type="submit">Filter</button>
   {{ form_end(list.filterForm) }}
   

2. Dynamic Field Selection

   $list->setFields(['title', 'createdAt']);
   $list->addField('author'); // Add dynamically
   

3. Custom Query Logic Override the query builder:

   $list->setQueryBuilder(function ($qb) {
       $qb->leftJoin('p.user', 'u');
       return $qb;
   });
   

4. Bulk Actions

   $list->setBulkActions([
       'delete' => ['label' => 'Delete Selected'],
       'publish' => ['label' => 'Publish'],
   ]);
   

   Handle actions in the controller:

   if ($list->isBulkAction('delete')) {
       $list->deleteSelected();
   }
   

Integration Tips

1. Symfony Forms Integration Use Symfony’s FormBuilder for complex filters:

   $builder = $this->createFormBuilder();
   $builder->add('title', TextType::class);
   $list->setFilterForm($builder->getForm());
   

2. Event Listeners Attach listeners for pre/post actions:

   $list->addPreAction(function ($list) {
       $list->addFilter('status', 'published');
   });
   

3. API Responses Serialize data for APIs:

   $data = $list->getData();
   $serializer = $this->get('serializer');
   return new JsonResponse($serializer->serialize($data, 'json'));
   

4. Caching Cache filtered results:

   $cache = $this->get('cache');
   $key = 'list_' . md5(serialize($list->getFilters()));
   if (!$cache->has($key)) {
       $data = $list->getData();
       $cache->set($key, $data, 3600);
   } else {
       $data = $cache->get($key);
   }
   

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2.x

   • Issue: Bundle targets Symfony 2.1.x. Use with Symfony 3/4/5 may break.
   • Fix: Fork and update dependencies if needed.

2. No Built-in Security

   • Issue: Bulk actions (e.g., deleteSelected) lack CSRF protection by default.
   • Fix: Add @Security annotations or validate requests manually.

3. Query Builder Overrides

   • Issue: Custom setQueryBuilder may conflict with pagination/filtering logic.
   • Fix: Extend the base class or use addPreAction to modify the query.

4. Field Naming Collisions

   • Issue: Fields like id or createdAt may clash with Doctrine metadata.
   • Fix: Use aliases:

     $list->setFields(['p.title as post_title']);
     

5. Filter Form Submission

   • Issue: Form submission may not update the list state if not handled.
   • Fix: Always call $list->handleRequest($request) in the controller.

Debugging Tips

1. Enable Query Logging

   $list->setDebug(true); // Logs SQL queries
   

2. Dump Filters

   dump($list->getFilters()); // Debug applied filters
   

3. Check Form Errors

   {% if list.filterForm.errors %}
       <div class="alert">{{ list.filterForm.errors|join(', ') }}</div>
   {% endif %}
   

Extension Points

1. Custom Field Types Override rendering for fields:

   {% block aygon_data_list_field_default %}
       {{ item[field] }}
   {% endblock %}
   

2. Add Actions Extend bulk actions:

   $list->addBulkAction('archive', function ($ids) {
       // Custom logic
   });
   

3. Modify Data Before Rendering

   $list->addPostAction(function ($data) {
       foreach ($data as &$item) {
           $item->formattedDate = $item->createdAt->format('Y-m-d');
       }
       return $data;
   });
   

4. Override Twig Templates Copy templates from vendor/aygon/data-list-bundle/Resources/views/ to your bundle’s Resources/views/AygonDataListBundle/ to customize.

Pro Tip: For complex projects, wrap DataList in a service to centralize configuration and reuse logic across controllers.