User Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require crunch/user-admin-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Crunch\UserAdminBundle\CrunchUserAdminBundle::class => ['all' => true],
   ];
   

2. Configure FOSUserBundle Ensure FOSUserBundle is properly installed and configured (e.g., User entity extends FOS\User\Model\User).

3. Enable SonataAdmin Integration Extend your UserAdmin class (typically in src/App/Admin/UserAdmin.php):

   use Crunch\UserAdminBundle\Admin\UserAdmin as BaseUserAdmin;
   
   class UserAdmin extends BaseUserAdmin
   {
       // Override methods as needed (e.g., fields, filters, actions)
   }
   

4. First Use Case Access the admin panel at /admin/app_user (or your configured route) to manage users via Sonata’s UI.

Implementation Patterns

1. Customizing the Admin Panel

Extend BaseUserAdmin to modify fields, filters, or actions:

protected function configureFields(FieldMap $fields)
{
    $fields
        ->add('username', 'text')
        ->add('email', 'email')
        ->add('enabled', 'boolean', [
            'editable' => true,
        ]);
}

2. Adding Custom Actions

Create custom CRUD actions (e.g., bulk email send):

protected function configureRoutes(RouteCollection $collection)
{
    $collection->add('send_emails', $this->getRouterIdParameter() . '/send-emails');
}

public function sendEmailsAction()
{
    $users = $this->getRequest()->get('users'); // Selected users
    // Logic to send emails...
    $this->addFlash('success', 'Emails sent!');
    return $this->redirectToList();
}

3. Filtering and Sorting

Customize filters in configureFilters():

protected function configureFilters(FilterBuilder $filter)
{
    $filter
        ->add('username', 'string')
        ->add('enabled', 'boolean');
}

4. Integration with FOSUser Events

Leverage FOSUser’s events (e.g., user_registered) to trigger admin actions:

// In a service or listener
public function onUserRegistered(UserEvent $event)
{
    $user = $event->getUser();
    // Log or notify admin via Sonata flash messages
}

5. Overriding Templates

Extend Sonata’s templates (e.g., edit.html.twig) to add custom fields or buttons:

{# app/Resources/views/UserAdmin/edit.html.twig #}
{{ parent() }}
<button onclick="sendBulkEmails()">Send Emails</button>

Gotchas and Tips

Pitfalls

1. FOSUserBundle Version Mismatch

   • Ensure crunch/user-admin-bundle is compatible with your FOSUserBundle version (check composer.json constraints).
   • Fix: Pin versions or use ^ carefully.

2. Missing SonataAdmin Configuration

   • If SonataAdmin routes aren’t registered, check config/packages/sonata_admin.yaml for proper admin class mappings.
   • Fix: Explicitly map UserAdmin in sonata_admin.yaml:

     sonata_admin:
         options:
             security:
                 handler: sonata.admin.security.handler.role
         managers:
             app:
                 class: Sonata\AdminBundle\Datagrid\ProxyQueryManager
                 options:
                     group_by: false
         admin:
             App\Admin\UserAdmin:
                 label: User
                 translation_domain: AppBundle
     

3. Field Overrides Not Applying

   • If custom fields don’t appear, clear cache:

     php bin/console cache:clear
     

   • Tip: Use dump() in configureFields() to debug field definitions.

4. Permission Issues

   • SonataAdmin uses roles (e.g., ROLE_SONATA_ADMIN). Ensure users have the correct roles in your security config.
   • Fix: Add to security.yaml:

     role_hierarchy:
         ROLE_ADMIN:       [ROLE_USER, ROLE_SONATA_ADMIN]
     

Debugging Tips

• Check Logs: Enable debug mode (APP_DEBUG=true) and inspect var/log/dev.log for SonataAdmin errors.
• Dump Admin Class: Use var_dump(get_class($this->getSubject())) in UserAdmin to verify the entity being managed.
• Sonata Debug Tool: Install sonata-project/admin-bundle’s debug toolbar for admin insights.

Extension Points

1. Custom Data Providers Override getQuery() to fetch users from a custom source (e.g., API):

   protected function getQuery($context = 'list')
   {
       $query = $this->getModelManager()->createQuery();
       // Custom query logic...
       return $query;
   }
   

2. Dynamic Field Visibility Use isVisible() to conditionally show fields:

   public function isVisible($name)
   {
       return $name === 'sensitive_data' && $this->getSubject()->isAdmin();
   }
   

3. API Integration Extend the admin to expose endpoints via sonata_admin’s REST integration:

   # config/packages/sonata_admin.yaml
   sonata_admin:
       rest:
           group_by: false
           url_generator: sonata.admin.rest.url_generator
   

4. Localization Translate labels/actions by extending configureFormFields() and using sonata_formatter:

   $formMapper
       ->add('username', 'text', [
           'label' => 'app.user.username',
       ]);