Base Admin Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require edezacas/base-admin
   

   Register the bundle in config/bundles.php (Symfony 4.4+):

   return [
       // ...
       EDC\BaseAdminBundle\EDCBaseAdminBundle::class => ['all' => true],
   ];
   

2. Configure Add to config/packages/edc_base_admin.yaml:

   edc_base_admin:
       site_name: 'MyApp Admin'
       login_check: 'app_login'  # Your login route
       logout: 'app_logout'      # Your logout route
       admin_home: 'admin_dashboard'  # Your admin home route
   

3. First Login Page Create templates/login.html.twig:

   {% include '@EDCBaseAdmin/login.html.twig' %}
   

   Route it in routes.yaml:

   app_login:
       path: /admin/login
       controller: App\Controller\AdminController::login
   

4. First Admin Layout Create templates/admin/_layout.html.twig:

   {% extends '@EDCBaseAdmin/base.html.twig' %}
   
   {% block title %}Admin Panel{% endblock %}
   
   {% block sidebar %}
       <ul class="nav flex-column">
           <li class="nav-item"><a href="{{ path('admin_dashboard') }}">Dashboard</a></li>
       </ul>
   {% endblock %}
   

5. First Admin Page Create templates/admin/dashboard.html.twig:

   {% extends 'admin/_layout.html.twig' %}
   
   {% block content %}
       <h1>Welcome to Admin Panel</h1>
   {% endblock %}
   

First Use Case: Quick Admin Dashboard

Extend _layout.html.twig for all admin pages, then create individual pages (e.g., users.html.twig, settings.html.twig) extending the layout. Use the built-in Bootstrap 5 components for forms, modals, and alerts.

Implementation Patterns

Core Workflows

1. Authentication Flow

   • Use the login_check and logout config routes for Symfony’s security system.
   • Customize login logic in App\Controller\AdminController (e.g., handle form submission, redirect after login).
   • Example login controller:

     public function login(AuthenticationUtils $authenticationUtils): Response
     {
         $error = $authenticationUtils->getLastAuthenticationError();
         return $this->render('login.html.twig', ['error' => $error]);
     }
     

2. Layout Inheritance

   • Base Template: Extend @EDCBaseAdmin/base.html.twig via _layout.html.twig.
   • Page Templates: Extend _layout.html.twig for each admin page (e.g., dashboard.html.twig).
   • Blocks to Override:
     • title: Page title (appears in <title> and sidebar).
     • sidebar: Navigation menu (uses Bootstrap 5 nav classes).
     • dropdown: User dropdown menu (e.g., profile, logout).
     • footer: Custom footer content.
     • content: Main page content.

3. Routing

   • Prefix admin routes with /admin (e.g., admin/dashboard).
   • Use _route_name_or_url_to_* in config for flexibility (supports both route names and URLs).
   • Example routes:

     admin_dashboard:
         path: /admin/dashboard
         controller: App\Controller\Admin\DashboardController::index
     

4. Asset Management

   • Bundle includes Bootstrap 5.1.3 and jQuery 3.6. Override in _layout.html.twig if needed:

     {% block stylesheets %}
         {{ parent() }}
         <link href="{{ asset('css/custom.css') }}" rel="stylesheet">
     {% endblock %}
     

5. Form Handling

   • Use Bootstrap 5 form classes (e.g., form-control, btn-primary) in templates.
   • Example form in templates/admin/users/create.html.twig:

     <form method="post">
         <div class="mb-3">
             <label class="form-label">Username</label>
             <input type="text" name="username" class="form-control">
         </div>
         <button type="submit" class="btn btn-primary">Save</button>
     </form>
     

6. Dynamic Content

   • Pass data from controllers to templates:

     return $this->render('admin/dashboard.html.twig', [
         'stats' => $this->getStatsService()->getData(),
     ]);
     

   • Use in templates:

     {% for stat in stats %}
         <div class="card">{{ stat.value }}</div>
     {% endfor %}
     

7. Modals and Alerts

   • Leverage Bootstrap 5 components:

     <!-- Modal -->
     <div class="modal fade" id="confirmDelete">
         <div class="modal-dialog">
             <div class="modal-content">
                 <div class="modal-body">Are you sure?</div>
                 <div class="modal-footer">
                     <button class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
                     <a href="{{ path('admin_users_delete', { id: user.id }) }}" class="btn btn-danger">Delete</a>
                 </div>
             </div>
         </div>
     </div>
     
     <!-- Alert -->
     {% if success %}
         <div class="alert alert-success">{{ success }}</div>
     {% endif %}
     

Gotchas and Tips

Pitfalls

1. Bundle Registration

   • Gotcha: Forgetting to register the bundle in bundles.php will silently fail (no errors, no assets).
   • Fix: Verify the bundle is listed and enabled for the all environment.

2. Route Configuration

   • Gotcha: Using _route_name_or_url_to_* in config requires either a valid route name or a full URL (e.g., /admin/login). Mixing these will break authentication.
   • Fix: Stick to route names for consistency:

     login_check: app_login  # Route name (recommended)
     # logout: /admin/logout  # Avoid URLs unless necessary
     

3. Template Overrides

   • Gotcha: Extending @EDCBaseAdmin/base.html.twig directly (instead of via _layout.html.twig) will overwrite all customizations for every page.
   • Fix: Always extend through _layout.html.twig:

     {% extends 'admin/_layout.html.twig' %}  {# Correct #}
     {% extends '@EDCBaseAdmin/base.html.twig' %}  {# Avoid #}
     

4. Asset Loading

   • Gotcha: If you override assets (e.g., CSS/JS), ensure paths are correct in _layout.html.twig. Missing assets will break the layout.
   • Fix: Use {{ asset() }} for local files and verify the bundle’s assets are loaded first:

     {% block stylesheets %}
         {{ parent() }}  {# Load bundle's CSS first #}
         <link href="{{ asset('css/admin.css') }}" rel="stylesheet">
     {% endblock %}
     

5. jQuery Dependencies

   • Gotcha: The bundle includes jQuery 3.6, but some plugins may require older versions (e.g., jQuery UI).
   • Fix: Load plugins after jQuery and check for conflicts:

     {% block javascripts %}
         {{ parent() }}  {# Loads jQuery #}
         <script src="https://code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
         <script src="{{ asset('js/admin.js') }}"></script>
     {% endblock %}
     

6. Security

   • Gotcha: The login_check route must be secured in security.yaml to prevent brute force attacks.
   • Fix: Configure rate limiting:

     firewalls:
         main:
             form_login:
                 login_path: app_login
                 check_path: app_login
             logout: app_logout
             remember_me:
                 secret: '%kernel.secret%'
                 lifetime: 86400  # 1 day
                 path: /
     

7. Debugging

   • Gotcha: Twig template errors may not show line numbers if the bundle’s templates are cached.
   • Fix: Clear cache and check the correct path:

     php bin/console cache:clear
     

   • Tip: Use {{ dump(_context) }} in templates to inspect variables during development.

Tips

1. Customize Without Forking

   • Override the bundle’s templates in templates/@EDCBaseAdmin/ (e.g., templates/@EDCBaseAdmin/login.html.twig) to modify default views without extending the bundle.

2. Partial Overrides

   • Use Twig’s {% block %} inheritance to modify only