Mottapg Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require agusmoita/mottapg-bundle
   

   Ensure Agusmoita\MottaPgBundle\AgusmoitaMottaPgBundle is registered in config/bundles.php.

2. First Use Case: Basic Pagination

   • Controller: Inject Paginator and a repository into your controller.

     use MottaPgBundle\Util\Paginator\Paginator;
     
     public function index(Paginator $paginator, PersonRepository $repo)
     {
         return $paginator
             ->setView('person/index.html.twig')
             ->paginate($repo);
     }
     

   • Repository: Implement buildQuery() to return a QueryBuilder instance.

     public function buildQuery($query, $paginator)
     {
         return $query->select('p'); // Adjust as needed
     }
     

   • Twig Template: Extend the bundle’s base template and define table headers/data.

     {% extends '@MottaPg/Paginator/table.html.twig' %}
     
     {% block paginator_table_header %}
         <th>Name</th>
     {% endblock %}
     
     {% block paginator_table_data %}
         <td>{{ entity.name }}</td>
     {% endblock %}
     

3. Key Files to Review

   • vendor/agusmoita/mottapg-bundle/Resources/views/Paginator/table.html.twig (base template).
   • src/Util/Paginator/Paginator.php (core logic).

Implementation Patterns

Core Workflow

1. Repository Integration

   • Override buildQuery() to customize queries (e.g., add WHERE, JOIN, or ORDER BY).
   • Example: Filter by active records:

     public function buildQuery($query, $paginator)
     {
         return $query->where('p.isActive = :active')->setParameter('active', true);
     }
     

2. Twig Customization

   • Override Blocks: Extend @MottaPg/Paginator/table.html.twig to modify:
     • paginator_table_header: Column headers.
     • paginator_table_data: Cell data.
     • paginator_actions: Custom action buttons (e.g., "Export").
   • Global Settings: Configure pagination defaults in config/packages/mottapg.yaml (if available).

3. Pagination Controls

   • The bundle auto-generates pagination links (next/prev/page numbers). Customize via Twig:

     {% block paginator_links %}
         {{ parent() }} {# Extend default links #}
         <a href="{{ path('custom_route') }}">Custom Action</a>
     {% endblock %}
     

4. Export Functionality

   • Leverage whiteoctober/tcpdf-bundle (dependency) for PDF/Excel exports.
   • Example: Add an export button in Twig:

     {% block paginator_actions %}
         <a href="{{ path('person_export_pdf') }}">Export PDF</a>
     {% endblock %}
     

   • Controller logic:

     public function exportPdf(Paginator $paginator, PersonRepository $repo)
     {
         $data = $paginator->paginate($repo)->getResults();
         // Use TCPDF to generate PDF from $data
     }
     

5. Mass Actions

   • Implement bulk operations (e.g., delete, update) via repository methods.
   • Example: Add a "Delete Selected" button in Twig:

     {% block paginator_actions %}
         <form method="POST" action="{{ path('person_mass_delete') }}">
             <button type="submit">Delete Selected</button>
         </form>
     {% endblock %}
     

Gotchas and Tips

Pitfalls

1. Outdated Dependency

   • The bundle depends on whiteoctober/tcpdf-bundle, which may have compatibility issues with newer Symfony versions. Test thoroughly or fork the bundle to update dependencies.

2. Limited Documentation

   • The README lacks details on:
     • Advanced query customization (e.g., dynamic sorting).
     • Twig template inheritance quirks (e.g., overriding paginator_links may break default behavior).
   • Workaround: Inspect the base template (table.html.twig) and Paginator.php for undocumented features.

3. No Built-in DTO Support

   • The bundle assumes repositories return entities directly. For complex queries, manually hydrate results or use a DTO layer.

4. Pagination State Not Persisted

   • Page state (e.g., current page, filters) is not stored in the session by default. Implement this manually if needed:

     $paginator->setPage($request->query->getInt('page', 1));
     

5. Twig Template Caching

   • Overriding blocks may fail if the base template is cached. Clear cache after changes:

     php bin/console cache:clear
     

Debugging Tips

1. Query Inspection

   • Log the QueryBuilder in buildQuery() to verify SQL:

     public function buildQuery($query, $paginator)
     {
         \Log::debug($query->getSQL(), ['params' => $query->getParameters()]);
         return $query;
     }
     

2. Template Debugging

   • Use Twig’s dump() to inspect variables:

     {% block paginator_table_data %}
         {{ dump(entity) }}
         <td>{{ entity.name }}</td>
     {% endblock %}
     

3. Common Issues

   • Blank Page: Ensure setView() points to a valid Twig template.
   • Broken Pagination Links: Verify buildQuery() returns a valid QueryBuilder with SELECT and ORDER BY.
   • Export Failures: Check whiteoctober/tcpdf-bundle configuration and permissions for generated files.

Extension Points

1. Custom Pagination Logic

   • Extend Paginator class to add features (e.g., infinite scroll):

     namespace App\Util\Paginator;
     use MottaPgBundle\Util\Paginator\Paginator as BasePaginator;
     
     class CustomPaginator extends BasePaginator
     {
         public function infiniteScroll($repository)
         {
             // Custom logic
         }
     }
     

   • Bind the service in config/services.yaml:

     services:
         App\Util\Paginator\CustomPaginator: autowire: true
     

2. Dynamic Column Sorting

   • Modify buildQuery() to accept a sort parameter:

     public function buildQuery($query, $paginator)
     {
         $sort = $paginator->getSort(); // Hypothetical method
         return $query->orderBy("p.$sort", 'ASC');
     }
     

3. Override Base Template

   • Copy vendor/agusmoita/mottapg-bundle/Resources/views/Paginator/table.html.twig to templates/bundles/MottaPg/Paginator/table.html.twig for safe customization.

4. Add New Export Formats

   • Use whiteoctober/tcpdf-bundle to extend PDF generation or integrate phpoffice/phpexcel for Excel:

     use TCPDF;
     
     public function exportExcel(Paginator $paginator, PersonRepository $repo)
     {
         $data = $paginator->paginate($repo)->getResults();
         // Use PhpExcel to generate Excel from $data
     }