Getting Started

Minimal Setup Steps

Install ElasticMS and the Bundle

composer require elasticms/elasticms
composer require elasticms/admin-ui-bundle

Ensure your composer.json includes:

"require": {
    "laravel/framework": "^10.0",
    "elasticms/elasticms": "^7.0",
    "elasticms/admin-ui-bundle": "^7.0"
}

Publish Configuration and Assets

php artisan vendor:publish --provider="EMS\AdminUIBundle\EMSAdminUIBundleServiceProvider"
php artisan ems:admin:install  # If ElasticMS CLI supports this

Configure Routes Add to routes/web.php:

use EMS\AdminUIBundle\Routing\AdminRouter;

AdminRouter::load(__DIR__.'/admin.php');

Define admin routes in routes/admin.php:

EMS\AdminUIBundle\Routing\AdminRouter::resource('contents', 'EMS\AdminUIBundle\Controller\ContentController');

Run Migrations
```
php artisan migrate
```
Access Admin Panel Visit /admin (default route) and authenticate via Laravel’s default auth or ElasticMS-specific providers.

First Use Case: Content Management

Out of the Box: The bundle provides a CRUD interface for ElasticMS content types (e.g., pages, posts).
Example Workflow:
1. Navigate to /admin/contents to list all content entries.
2. Click "Create" to add a new entry using the bundled form (with ElasticMS field types like text, media, rich_text).
3. Edit or delete entries via the table actions (bulk operations supported).

Where to Look First

Bundle Documentation Check the docs/ folder in the repo for:
- Configuration options (e.g., config/ems_admin.php).
- Customization guides (e.g., overriding templates).
Key Directories
- src/Controller/: Core admin controllers (e.g., ContentController, MediaController).
- src/Resources/views/: Blade templates for tables, forms, and layouts.
- src/Event/: Events for extending admin logic (e.g., ContentCreating).
ElasticMS Integration Review EMS\AdminUIBundle\Service\ElasticMSService.php to understand how the bundle interacts with ElasticMS models (e.g., EMS\Content\Content).

Implementation Patterns

Core Workflows

1. CRUD Operations

List/Table Views: The bundle auto-generates tables for ElasticMS models. Customize via:

// Override the table columns in a service provider
EMS\AdminUIBundle\Table\ContentTable::addColumns([
    'title' => 'Title',
    'status' => 'Status',
    'created_at' => 'Published',
]);

Override the default table template at resources/views/vendor/ems_admin/table.blade.php.

Create/Edit Forms: Forms are dynamic based on ElasticMS field definitions. Extend with:

// Add a custom field to the form
EMS\AdminUIBundle\Form\ContentForm::addField('custom_field', 'text', [
    'label' => 'Custom Label',
    'required' => true,
]);

Override the form template at resources/views/vendor/ems_admin/form.blade.php.

2. Role-Based Access Control (RBAC)

Use Laravel’s built-in gates/policies or extend the bundle’s RBAC:

// In AuthServiceProvider
Gate::define('view-admin', function ($user) {
    return $user->hasRole('admin'); // Custom logic
});

Restrict routes in routes/admin.php:

EMS\AdminUIBundle\Routing\AdminRouter::resource('contents', 'ContentController')->middleware('can:view-admin');

3. Media Management

The bundle integrates with ElasticMS’s media library. Upload files via:

<x-ems-admin::media-uploader field="media_field" />

Customize the uploader settings in config/ems_admin.php:

'media' => [
    'disk' => 'public',
    'allowed_types' => ['jpg', 'png', 'pdf'],
],

4. Event-Driven Extensions

Extend admin logic via events (e.g., ContentCreating, ContentUpdating):

// In a service provider
event(new CreatingContent($content));

Listen to events in EventServiceProvider:

protected $listen = [
    'EMS\AdminUIBundle\Event\ContentCreating' => [
        'App\Listeners\LogContentCreation',
    ],
];

Integration Tips

Laravel-Specific Patterns

Service Providers Bind custom services to the bundle’s container:

$this->app->bind('ems.admin.custom_service', function () {
    return new CustomAdminService();
});

Blade Directives Extend Blade with custom directives for admin-specific logic:

Blade::directive('adminAsset', function ($expr) {
    return "<?php echo asset('vendor/ems-admin/$expr'); ?>";
});

Middleware Add admin-specific middleware to app/Http/Kernel.php:

protected $routeMiddleware = [
    'admin.auth' => \EMS\AdminUIBundle\Http\Middleware\AdminAuth::class,
];

Frontend Integration

Vue/React Components If using InertiaJS, wrap bundle components:

<template>
    <div>
        <x-ems-admin::content-table :contents="contents" />
    </div>
</template>

CSS/JS Assets Publish and compile assets:
```
npm run dev -- --watch
```
Override styles in resources/css/ems_admin.css.

Gotchas and Tips

Pitfalls

ElasticMS Dependency
- Issue: The bundle assumes ElasticMS models (e.g., EMS\Content\Content). If your project uses custom models, you’ll need to:
  - Extend the bundle’s base classes (e.g., EMS\AdminUIBundle\Model\AdminModel).
  - Override controllers to work with your models.
- Fix: Create a trait to bridge your models:
```
use EMS\AdminUIBundle\Traits\AdminModelTrait;

class CustomContent extends Model
{
    use AdminModelTrait;
}
```
Route Conflicts
- Issue: The bundle registers routes under /admin. Conflicts may arise with other admin packages (e.g., Laravel Nova).
- Fix: Override the route prefix in config/ems_admin.php:
```
'routes' => [
    'prefix' => 'app',
],
```
Template Overrides
- Issue: Overriding templates (e.g., table.blade.php) may break if the bundle’s template structure changes in updates.
- Fix: Use symbolic links or a custom view path:
```
// In a service provider
view()->addNamespace('ems_admin', resource_path('views/custom_ems_admin'));
```
Authentication Bypass
- Issue: The bundle may not enforce Laravel’s default auth. If /admin is accessible without login, check:
  - Middleware in routes/admin.php.
  - The AdminAuth middleware in app/Http/Middleware.
- Fix: Add middleware to all admin routes:
```
EMS\AdminUIBundle\Routing\AdminRouter::middleware('auth');
```
Performance with Large Datasets
- Issue: The default table pagination may slow down with >10,000 records.
- Fix: Optimize queries in EMS\AdminUIBundle\Repository\ContentRepository or use Laravel Scout for search.

Debugging Tips

Enable Debug Mode Set APP_DEBUG=true in .env and check logs:
```
tail -f storage/logs/laravel.log
```
Bundle-Specific Logs Enable debug logging in config/ems_admin.php:
```
'debug' => env('EMS_ADMIN_DEBUG', false),
```
Dump Admin Data Use Laravel’s debug tools to inspect admin data:
```
dd(EMS\AdminUIBundle\Facades\Admin::getContent());
```
Check Events Listen for admin events to debug workflows:
```
EMS\AdminUI
```

Admin Ui Bundle Laravel Package