Toolbox Bundle Laravel Package

Getting Started

Minimal Setup

1. Enable Contrib Support Run in your project root:

   composer config extra.symfony.allow-contrib true
   composer require codyas/toolbox-bundle
   

2. Register the Bundle Ensure Codyas\Toolbox\CodyasToolboxBundle is enabled in config/bundles.php:

   return [
       // ...
       Codyas\Toolbox\CodyasToolboxBundle::class => ['all' => true],
   ];
   

3. Route the CRUD Controller Add to config/routes/codyas_toolbox.yaml:

   codyas_toolbox_bundle:
       resource: '@CodyasToolboxBundle/Controller/CrudController.php'
       type: annotation
   

4. First Use Case: Quick CRUD for an Entity Annotate a Doctrine entity with @Codyas\Toolbox\Annotation\Crud:

   use Codyas\Toolbox\Annotation\Crud;
   
   /**
    * @Crud(title="User Management", icon="user")
    */
   class User {}
   

   Access via /admin/user (or your configured route prefix).

Implementation Patterns

Workflow: Rapid CRUD Development

1. Annotate Entities Use @Crud on any Doctrine entity to auto-generate:

   • List view (with search/filter)
   • Create/Edit forms (auto-mapped to fields)
   • Delete confirmation
   • Bulk actions (if configured)

   /**
    * @Crud(
    *     title="Products",
    *     icon="cube",
    *     searchFields={"name", "sku"},
    *     actions={"edit", "delete"}
    * )
    */
   class Product {}
   

2. Customize Templates Override default Twig templates in templates/CodyasToolboxBundle/:

   • Crud/list.html.twig (modify list table)
   • Crud/form.html.twig (alter form fields)
   • base.html.twig (extend admin layout)

3. Integrate with Forms Extend form types via codyas_toolbox.form.type_extension service:

   # config/services.yaml
   services:
       App\Form\Extension\ProductTypeExtension:
           tags:
               - { name: codyas_toolbox.form.type_extension, entity: App\Entity\Product }
   

4. Access CRUD Data in Controllers Use the CrudManager service to fetch CRUD configurations:

   use Codyas\Toolbox\Manager\CrudManager;
   
   public function __construct(private CrudManager $crudManager) {}
   
   public function someAction() {
       $crudConfig = $this->crudManager->getCrudConfig(Product::class);
   }
   

Integration Tips

• Doctrine Events: Hook into codyas_toolbox.crud.pre_save or codyas_toolbox.crud.post_delete events for custom logic.
• Security: Restrict access via Symfony’s voter system (e.g., @IsGranted("ROLE_ADMIN") on routes).
• Assets: The bundle includes SCSS for admin styling. Compile via:

  yarn encore dev --watch
  

• API Endpoints: Use the CrudApiController (if available) for JSON responses alongside Twig views.

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • The bundle auto-generates routes under /admin/{entity}.
   • Fix: Explicitly prefix routes in codyas_toolbox.yaml:

     codyas_toolbox_bundle:
         prefix: /app
     

2. Template Overrides Not Loading

   • Ensure your custom templates extend CodyasToolboxBundle:base.html.twig.
   • Debug: Clear cache (php bin/console cache:clear) and check var/cache/dev/twig/ for compiled templates.

3. Form Field Exclusions

   • Fields marked @ORM\Column(editable=false) are hidden by default.
   • Workaround: Use excludeFields in @Crud or override the form type.

4. Doctrine Proxy Issues

   • Lazy-loaded associations may break in CRUD forms.
   • Solution: Fetch entities with DISTINCT or use fetch="EAGER" in mappings.

Debugging

• Enable Debug Mode Set debug: true in config/packages/codyas_toolbox.yaml to log CRUD operations.
• Check Annotations Run php bin/console debug:container --tag=codyas_toolbox.crud to verify annotated entities.
• Log Events Subscribe to codyas_toolbox.crud.exception to catch runtime errors:

  use Symfony\Component\EventDispatcher\GenericEvent;
  
  public function onCrudException(GenericEvent $event) {
      if ($event->getSubject() instanceof \Exception) {
          error_log($event->getSubject()->getMessage());
      }
  }
  

Extension Points

1. Custom Actions Add buttons to the list view via codyas_toolbox.crud.action events:

   $event->addAction(new Action('custom', 'Custom', 'fas fa-rocket'));
   

2. Dynamic Field Mapping Override field types in config/packages/codyas_toolbox.yaml:

   codyas_toolbox:
       form_types:
           App\Entity\Product:
               name: App\Form\Type\AutocompleteType
   

3. Theming

   • Copy vendor/codyas/toolbox-bundle/Resources/views/ to templates/CodyasToolboxBundle/ for full control.
   • Extend SCSS variables in assets/styles/variables.scss:

     $codyas-admin-primary: #20c997;
     

4. Multi-Entity CRUD Use batchEntities in @Crud to group related entities (e.g., User + UserProfile):

   @Crud(batchEntities={"User", "UserProfile"})