Crud Bundle Laravel Package

Getting Started

Minimal Steps to First CRUD Operation

1. Installation:

   composer require araise/crud-bundle
   bin/console araise:crud:setup
   

   Add Tailwind CSS dependencies and configure twig.yaml:

   twig:
       form_themes:
           - '@araiseCrud/form_layout.html.twig'
   

2. Create an Entity:

   bin/console make:entity
   

   Ensure your entity has a __toString() method.

3. Generate a Definition:

   bin/console make:definition
   

   This creates a YAML/JSON config file (e.g., src/Definition/UserDefinition.php) defining CRUD behavior.

4. Update Database:

   bin/console doctrine:schema:update --force
   

5. Access CRUD Interface: Visit /app_user (replace app_user with your entity’s route prefix).

First Use Case: Quick User Management

1. Create a User entity with fields like name, email, and role.
2. Generate a UserDefinition to configure:
   • List columns (e.g., name, email).
   • Filterable fields.
   • Form layout (e.g., hide password in list view).
3. Test the auto-generated CRUD interface at /app_user.

Implementation Patterns

Workflows

1. Entity-Definition Pairing

• Pattern: One entity → one definition file (e.g., UserDefinition for User entity).
• Example:

  # src/Definition/UserDefinition.php
  fields:
      name:
          label: 'Full Name'
          type: text
          sortable: true
      email:
          type: email
          filterable: true
  actions:
      list:
          - create
          - edit
          - delete
  

2. Custom Controllers

• Extend araise\CrudBundle\Controller\CrudController for custom logic.
• Example:

  #[Route('/users/export', name: 'user_export', defaults: ['_resource' => UserDefinition::class])]
  public function exportAction(Request $request): Response
  {
      $definition = $this->getDefinition(UserDefinition::class);
      $data = $this->getCrudService()->getRepository()->findAll();
      // Custom export logic
  }
  

3. Dynamic Field Configuration

• Use type: relation for many-to-one/many-to-many fields:

  fields:
      role:
          type: relation
          entity: App\Entity\Role
          property: name
  

4. Bulk Actions

• Configure in definition:

  actions:
      list:
          - bulk_delete
          - bulk_export
  

Integration Tips

1. Tailwind Customization

• Override styles by extending tailwind.config.js:

  module.exports = {
      content: [
          './templates/**/*.html.twig',
          './vendor/araise/**/*.twig',
      ],
      theme: {
          extend: {
              colors: {
                  primary: '#3b82f6', // Custom primary color
              },
          },
      },
  };
  

2. Search Integration

• Pair with araise/SearchBundle for global search:

  # config/packages/araise_search.yaml
  araise_search:
      enabled: true
  

3. Form Theming

• Extend form_layout.html.twig to customize form fields:

  {# templates/araiseCrud/form_layout.html.twig #}
  {% block araise_crud_form_row %}
      <div class="mb-4">
          {{ form_row(form, { required: false }) }}
      </div>
  {% endblock %}
  

4. API Endpoints

• Use Symfony’s Serializer to expose CRUD as API:

  #[Route('/api/users', name: 'api_user_list', methods: ['GET'])]
  public function apiListAction(): JsonResponse
  {
      $data = $this->getCrudService()->getRepository()->findAll();
      return $this->json($this->serializer->serialize($data, 'json'));
  }
  

Gotchas and Tips

Pitfalls

1. Locale Mismatch:

   • Issue: German translations are default. Non-German locales may break UI.
   • Fix: Set default_locale: en in translation.yaml or add translations via PR.

2. Missing __toString:

   • Issue: CRUD fails silently if entity lacks __toString().
   • Fix: Add to entity:

     public function __toString(): string
     {
         return $this->name ?? 'No name';
     }
     

3. Route Conflicts:

   • Issue: Custom routes may clash with bundle defaults.
   • Fix: Use _resource in route annotations:

     #[Route('/custom', defaults: ['_resource' => UserDefinition::class])]
     

4. Tailwind Dependencies:

   • Issue: Missing @tailwindcss/forms or postcss breaks form styling.
   • Fix: Install dependencies:

     yarn add @tailwindcss/forms postcss-loader
     

5. Definition Caching:

   • Issue: Changes to Definition files may not reflect immediately.
   • Fix: Clear cache:

     bin/console cache:clear
     

Debugging Tips

1. Check Definition Validation:

   • Run bin/console araise:crud:validate to catch misconfigurations.

2. Log Crud Events:

   • Enable debug in araise_crud.yaml:

     araise_crud:
         debug: true
     

3. Inspect Twig Templates:

   • Override templates in templates/araiseCrudBundle/ to debug rendering issues.

4. Database Schema:

   • Verify araise_search_index and araise_table_filter tables exist after setup.

Extension Points

1. Custom Actions:

   • Add actions in Definition:

     actions:
         list:
             - custom_action
     

   • Implement controller method:

     public function customAction(Request $request): Response
     {
         // Logic here
     }
     

2. Field Types:

   • Extend with custom types by implementing araise\CrudBundle\Field\FieldTypeInterface.

3. Menu Customization:

   • Override MenuBuilder to modify navigation:

     class AppMenuBuilder extends DefinitionMenuBuilder
     {
         public function createMainMenu(): ItemInterface
         {
             $menu = $this->factory->createItem('root');
             $menu->addChild('Custom Menu Item', ['route' => 'custom_route']);
             return $menu;
         }
     }
     

4. Event Listeners:

   • Subscribe to CRUD events (e.g., CrudEntityPrePersistEvent):

     #[Tags('kernel.event_listener', tag: 'araise_crud.entity_pre_persist')]
     class MyListener implements EventSubscriberInterface
     {
         public static function getSubscribedEvents(): array
         {
             return [
                 CrudEntityPrePersistEvent::NAME => 'onPrePersist',
             ];
         }
     }
     

5. Translation Overrides:

   • Extend translations in translations/messages.en.yaml:

     araise_crud:
         action:
             create: 'Add New Entry'