Getting Started

Minimal Setup

Installation:
```
composer require austral/admin-bundle
```
Ensure Austral\AdminBundle\AustralAdminBundle is registered in config/bundles.php.
First Use Case: Generate a basic admin module for an existing entity (e.g., User):
```
php bin/console austral:admin:generate User
```
This creates a CRUD interface with list, create, edit, and delete actions.
Key Files:
- config/packages/austral_admin.yaml: Bundle configuration.
- src/Admin/: Auto-generated admin modules (e.g., UserAdmin.php).
- templates/admin/: Twig templates for customization.
Quick Start: Access the admin panel at /admin (configured in routing.yaml). The bundle auto-generates routes for all modules.

Implementation Patterns

Core Workflows

Entity Integration:
- Annotate entities with #[Austral\AdminBundle\Annotation\Admin] to enable admin access:
```
#[Admin(title: "Users", icon: "fas fa-users")]
class User {}
```
- Use #[Austral\AdminBundle\Annotation\AdminField] to customize fields:
```
#[AdminField(type: "text", options: ["label" => "Full Name"])]
#[Assert\NotBlank]
private string $name;
```

Module Customization:

Extend auto-generated modules (e.g., UserAdmin.php) to override actions:

public function configureActions(): array
{
    return [
        'index' => ['label' => 'List Users'],
        'new'   => ['label' => 'Add User'],
        'edit'  => ['label' => 'Edit User'],
        'delete'=> ['label' => 'Delete User', 'icon' => 'fas fa-trash'],
    ];
}

Multi-Domain Support:

Enable domain filtering in config/austral_admin.yaml:
```
austral_admin:
    multi_domain: true
```

Add domain filters to entities:

#[Austral\AdminBundle\Annotation\AdminFilter(domain: true)]
private ?string $domain;

Form and List Customization:
- Use #[Austral\FormBundle\Annotation\Form] and #[Austral\ListBundle\Annotation\List] annotations for granular control over forms and lists.
- Example for a custom form:
```
#[Form(type: "custom_form_type")]
private string $bio;
```

Twig Integration:

Override templates in templates/admin/YourModule/. Example:

{# templates/admin/User/edit.html.twig #}
{{ extend('admin/_edit.html.twig') }}
{# Customize fields here #}

Event Listeners:

Subscribe to admin events (e.g., AdminModuleEvent):

public static function getSubscribedEvents(): array
{
    return [
        AdminModuleEvent::PRE_SAVE => 'onPreSave',
    ];
}

API Endpoints:
- Enable JSON API responses in config/austral_admin.yaml:
```
austral_admin:
    api: true
```
- Access endpoints at /admin/api/users.

Gotchas and Tips

Pitfalls

Entity Annotations:
- Forgetting to annotate entities with #[Admin] will exclude them from the admin panel. Run:
```
php bin/console austral:admin:generate EntityName
```
  to regenerate missing modules.
Multi-Domain Quirks:
- If multi_domain: true is enabled but no domain field exists, the bundle will throw a RuntimeException. Ensure entities have a domain field annotated with #[AdminFilter(domain: true)].
Template Overrides:
- Overriding templates in templates/admin/ requires clearing the cache:
```
php bin/console cache:clear
```
Mercure Dependency:
- The bundle uses Mercure for real-time updates. If Mercure is disabled in config/austral_security.yaml, some features (e.g., live list updates) may not work.

Form Type Conflicts:

Custom form types must be registered as services. Example:

# config/services.yaml
services:
    App\Form\Type\CustomFormType:
        tags: ['form.type']

Route Conflicts:
- The bundle auto-generates routes under /admin. Ensure no existing routes conflict. Customize the prefix in config/austral_admin.yaml:
```
austral_admin:
    prefix: '/backend'
```

Debugging Tips

Log Admin Events: Enable debug mode in config/austral_admin.yaml:
```
austral_admin:
    debug: true
```
Logs will appear in var/log/dev.log.
Check Generated Modules: Inspect auto-generated modules in src/Admin/ to verify annotations and overrides.
Validate Entities: Use the austral:admin:validate command to check for missing annotations or misconfigurations:
```
php bin/console austral:admin:validate
```
Clear Cache: Always clear the cache after generating modules or updating configurations:
```
php bin/console cache:clear
```

Extension Points

Custom Actions: Add new actions to modules by extending the configureActions() method:

public function configureActions(): array
{
    return array_merge(parent::configureActions(), [
        'export' => ['label' => 'Export', 'icon' => 'fas fa-file-export'],
    ]);
}

Dynamic Field Mapping: Use #[AdminField(type: "dynamic")] to load fields dynamically via a service:

#[AdminField(type: "dynamic", options: ["service" => "app.dynamic_field_service"])]
private $dynamicField;

Bulk Actions: Enable bulk actions in configureActions():

public function configureActions(): array
{
    return [
        'bulk_delete' => ['label' => 'Delete Selected'],
    ];
}

Custom Templates: Create reusable template fragments in templates/admin/_partials/. Example:

{# templates/admin/_partials/custom_field.html.twig #}
<div class="custom-field">
    {{ form_row(form.field) }}
</div>

API Extensions: Extend the API by creating custom controllers and routing them under /admin/api:

# config/routes.yaml
austral_admin_api:
    resource: "@AustralAdminBundle/Resources/config/api.yaml"
    prefix: /admin/api

Localization: Translate admin labels and messages using Symfony’s translation system. Example:

# translations/messages.en.yaml
admin:
    user:
        list: "User List"
        create: "Create User"

Reference in annotations:

#[Admin(title: "admin.user.list")]

Download Formats: Customize download formats (e.g., CSV, Excel) by extending the configureDownloads() method:

public function configureDownloads(): array
{
    return [
        'csv' => ['label' => 'CSV Export', 'icon' => 'fas fa-file-csv'],
        'excel' => ['label' => 'Excel Export', 'icon' => 'fas fa-file-excel'],
    ];
}

Admin Bundle Laravel Package