Beacon Admin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require devgeek/beacon-admin
   

   Ensure symfony/doctrine-bundle and symfony/security-bundle are installed (required dependencies).

2. Basic Configuration Add to config/packages/beacon_admin.yaml:

   beacon_admin:
       route_prefix: /admin
       title: 'MyApp Admin'
       menu:
           - { label: 'Dashboard', route: beacon_admin_dashboard, icon: fas fa-tachometer-alt }
   

3. Route Import Add to config/routes.yaml:

   beacon_admin:
       resource: '@BeaconAdminBundle/config/routes/beacon_admin.yaml'
       prefix: /admin
   

4. First CRUD Controller Generate a controller for an existing entity (e.g., Product):

   php bin/console make:crud Admin/ProductCrudController App\Entity\Product
   

   Extend AbstractCrudController and override getEntityClass():

   class ProductCrudController extends AbstractCrudController
   {
       protected function getEntityClass(): string
       {
           return Product::class;
       }
   }
   

5. Access Admin Panel Visit /admin (ensure Symfony Security is configured for /admin/* routes).

First Use Case: Quick CRUD for an Entity

1. Auto-Generated CRUD The package auto-detects Doctrine entities and generates:

   • List view with server-side datatables (search, sort, pagination).
   • Create/Edit forms (auto-generated from entity metadata).
   • Delete actions with confirmation.

2. Customize List Columns Override configureCrud() in your controller:

   protected function configureCrud(CrudConfig $config): void
   {
       $config->setColumns(['id', 'name', 'price', 'createdAt']);
   }
   

3. Add a Widget to Dashboard Create a custom widget service and register it in beacon_admin.yaml:

   beacon_admin:
       dashboard:
           widgets:
               - { type: 'stats', title: 'Total Products', route: 'admin_product_index' }
   

Implementation Patterns

Workflows

1. Entity-Based CRUD

• Pattern: Extend AbstractCrudController for each entity.
• Example:

  class UserCrudController extends AbstractCrudController
  {
      protected function getEntityClass(): string { return User::class; }
  
      protected function configureCrud(CrudConfig $config): void
      {
          $config->setSearchFields(['email', 'username']);
          $config->setActions(['edit', 'delete', 'custom_action']);
      }
  }
  

• Key Methods:
  • configureCrud(): Modify list view, search, actions, or columns.
  • configureForm(): Customize form fields (e.g., disable a field).
  • prePersist()/preUpdate(): Add logic before saving.

2. Custom Actions

• Add custom buttons to the list view:

  $config->addAction(
      'publish',
      'fas fa-paper-plane',
      'admin_user_publish',
      'Publish',
      ['confirm' => 'Are you sure?']
  );
  

• Handle the action in a controller method (e.g., publishAction()).

3. Form Customization

• Override form fields using configureForm():

  protected function configureForm(FormBuilder $builder, array $options): void
  {
      $builder->remove('password'); // Hide sensitive fields
      $builder->add('role', EntityType::class, [
          'class' => Role::class,
          'choice_label' => 'name',
      ]);
  }
  

• Use Symfony’s FormBuilder or FormInterface for advanced logic.

4. Dashboard Widgets

• Built-in Widgets: Stats, charts (via devgeek/beacon-admin-charts), or custom HTML.
• Custom Widgets:
  1. Create a service tagged as beacon_admin.widget:

     services:
         App\Widget\CustomWidget:
             tags: [beacon_admin.widget]
     

  2. Implement WidgetInterface:

     class CustomWidget implements WidgetInterface
     {
         public function getTitle(): string { return 'Custom Data'; }
         public function getContent(): string { return $this->twig->render('widget/custom.html.twig'); }
     }
     

• Register in config:

  beacon_admin:
      dashboard:
          widgets:
              - { type: 'custom', title: 'My Widget', service: 'App\Widget\CustomWidget' }
  

5. Authentication & Authorization

• Role-Based Access: Use Symfony’s voter system or ACLs. Example voter for a CRUD controller:

  use Symfony\Component\Security\Core\Authorization\Voter\Voter;
  class AdminVoter extends Voter
  {
      protected function supports(string $attribute, $subject): bool
      {
          return $attribute === 'EDIT' && $subject instanceof Product;
      }
      protected function voteOnAttribute(string $attribute, $subject, TokenInterface $token): bool
      {
          return $token->getUser()->hasRole('ROLE_ADMIN');
      }
  }
  

• Route Access: Secure routes in security.yaml:

  access_control:
      - { path: ^/admin, roles: ROLE_ADMIN }
  

6. Theming

• Override Twig templates in templates/BeaconAdminBundle/ (e.g., dashboard.html.twig).
• Custom CSS/JS: Add to assets/beacon-admin/ and enable in beacon_admin.yaml:

  beacon_admin:
      assets:
          css: ['/bundles/beaconadmin/custom.css']
          js: ['/bundles/beaconadmin/custom.js']
  

Integration Tips

Doctrine Events

• Listen to entity events (e.g., prePersist) in your CRUD controller:

  use Doctrine\ORM\Event\LifecycleEventArgs;
  public function prePersist(LifecycleEventArgs $args): void
  {
      $entity = $args->getEntity();
      $entity->setCreatedAt(new \DateTime());
  }
  

API Integration

• Use the CRUD controller to proxy API calls:

  public function apiExportAction(Request $request): JsonResponse
  {
      $data = $this->crudService->getAllData();
      return new JsonResponse($data);
  }
  

Testing

• Test CRUD controllers with WebTestCase:

  public function testCrudList()
  {
      $client = static::createClient();
      $client->request('GET', '/admin/products');
      $this->assertResponseIsSuccessful();
      $this->assertSelectorTextContains('h1', 'Products');
  }
  

Gotchas and Tips

Pitfalls

1. Entity Metadata Caching

   • Clear cache after adding new entities or fields:

     php bin/console cache:clear
     php bin/console doctrine:cache:clear-metadata
     

2. Form Type Conflicts

   • If auto-generated forms fail, ensure your entity fields use valid Doctrine types (e.g., DateTime instead of string for dates).
   • Debug with:

     php bin/console debug:form App\Entity\ProductType
     

3. Route Conflicts

   • Avoid naming CRUD controllers ambiguously (e.g., ProductController may clash with API routes).
   • Prefix with Crud or Admin (e.g., ProductCrudController).

4. Widget Registration

   • Custom widgets must implement WidgetInterface and be tagged as beacon_admin.widget. Forgetting the tag will silently ignore the widget.

5. Translation Issues

   • Translate labels/actions in translations/messages.en.yaml:

     'beacon_admin.action.edit': 'Modify'
     

6. Performance with Large Datasets

   • Server-side datatables use Doctrine queries. Optimize with:
     • DQL PARTIAL INDEXES or database views.
     • Pagination limits in CrudConfig:

       $config->setItemsPerPage(50);
       

Debugging

1. Enable Debug Mode Set BEACON_ADMIN_DEBUG: true in .env to log SQL queries and widget errors.

2. Check Twig Errors Enable Twig debug mode in config/packages/twig.yaml:

   twig:
       debug: '%kernel.debug%'
       strict_variables: '%kernel.debug%'
   

3. Log Crud Events Add a subscriber to log CRUD actions:

   class CrudLoggerSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribed