Platform Datagrid Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require digitalstate/platform-datagrid-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       DigitalState\PlatformDataGridBundle\DigitalStatePlatformDataGridBundle::class => ['all' => true],
   ];
   

2. First Use Case: Extend an existing OroDataGrid grid or create a new one by configuring a data source in your custom bundle. Example: Override oro_datagrid.datagrid.your_entity in config/packages/your_bundle.yaml:

   oro_datagrid:
       grids:
           your_entity:
               source:
                   acl_resource: 'your_entity_view'
                   type: 'orm'
                   query:
                       select: ['e.id', 'e.name']
                       from: ['{YourBundle:Entity} e']
   

3. Key Files to Explore:

   • Resources/config/oro/datagrid.yml (default configurations)
   • DependencyInjection/Extension.php (bundle extension points)
   • EventListener/ (event-driven hooks for customization)

Implementation Patterns

Core Workflows

1. Data Source Customization:

   • Extend Oro\ORM\DataGrid\ORMDataGridProvider for complex queries.
   • Use query builders for dynamic filtering:

     $queryBuilder->andWhere('e.status = :status')->setParameter('status', 'active');
     

2. Column Configuration:

   • Define columns in YAML or PHP:

     columns:
         id:
             label: 'ID'
             frontend_type: 'integer'
         name:
             label: 'Name'
             frontend_type: 'string'
             editable: true
     

3. Event-Driven Extensions:

   • Subscribe to oro_datagrid.build.query.before or oro_datagrid.build.result.after:

     public function onBuildQueryBefore(GridBuildQueryBeforeEvent $event) {
         $event->getQueryBuilder()->leftJoin('e.relatedEntity', 're');
     }
     

4. Integration with Forms:

   • Use oro_datagrid.edit_form and oro_datagrid.view_form to bind grids to edit/view forms:

     oro_datagrid:
         grids:
             your_entity:
                 edit_form:
                     form_type: 'YourBundle\Form\Type\YourEntityType'
                     options:
                         data_class: 'YourBundle\Entity\Entity'
     

5. API/Export Integration:

   • Leverage oro_datagrid.export for CSV/Excel exports:

     export:
         enabled: true
         formats: ['csv', 'xlsx']
     

Gotchas and Tips

Common Pitfalls

1. ACL Resource Mismatches:

   • Ensure acl_resource in the grid config matches your Symfony security roles.
   • Debug with bin/console debug:acl if grids fail to load.

2. Query Performance:

   • Avoid SELECT *; explicitly define columns to reduce overhead.
   • Use DQL for complex joins (e.g., WITH clauses) but test performance.

3. Caching Issues:

   • Clear cache after modifying grid configs:

     php bin/console cache:clear
     

   • Disable caching during development in config/packages/dev/oro_datagrid.yaml:

     oro_datagrid:
         caching: false
     

4. Frontend Template Conflicts:

   • Override templates in templates/oro_datagrid/ to customize rendering.
   • Use {{ grid('your_entity') }} in Twig; avoid hardcoding IDs.

Pro Tips

1. Dynamic Column Visibility:

   • Use visible option with conditions:

     columns:
         advanced_field:
             visible: '@=grid.getParameter("show_advanced")'
     

2. Bulk Actions:

   • Configure actions for mass updates/deletes:

     actions:
         update:
             type: 'update'
             label: 'Update'
             acl_resource: 'your_entity_update'
     

3. Debugging Queries:

   • Enable SQL logging in .env:

     APP_DEBUG=true
     DATABASE_URL="mysql://user:pass@localhost/db?serverVersion=8.0&charset=utf8mb4&enable_query_log=true"
     

   • Check logs in var/log/dev.log for generated DQL.

4. Extension Points:

   • Override DigitalState\PlatformDataGridBundle\Provider\DataGridProvider for custom data sources.
   • Extend DigitalState\PlatformDataGridBundle\Event\GridEvents for pre/post-processing.

5. Testing:

   • Use oro_datagrid.tester service in PHPUnit:

     $this->get('oro_datagrid.tester')->loadGrid('your_entity');