Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require elasticms/core-bundle
   

   Ensure your project uses Laravel 9.x+ (check documentation for exact compatibility).

2. Publish Configuration:

   php artisan vendor:publish --provider="ElasticMS\CoreBundle\ElasticMSCoreBundle" --tag="config"
   

   This generates config/elasticms.php with default settings.

3. Register Bundle: Add to config/app.php under providers:

   ElasticMS\CoreBundle\ElasticMSCoreBundle::class,
   

4. First Use Case:

   • Admin Panel Integration: Use the built-in admin generator to scaffold CRUD interfaces for Eloquent models.

     php artisan elasticms:generate:admin --model=App\Models\Post
     

   • API Endpoints: Leverage the @ElasticMS\Api annotation to auto-generate API routes for your models.

Key Entry Points

• Documentation: Official Docs (focus on Admin Generator and API sections).
• CLI Commands: Run php artisan elasticms to list available commands (e.g., elasticms:install, elasticms:generate:admin).
• Configuration: Modify config/elasticms.php for:
  • Admin panel branding (title, logo).
  • API settings (e.g., api_prefix, auth_middleware).
  • Database connections for migrations.

Implementation Patterns

1. Admin Panel Development

Workflow:

1. Scaffold CRUD:

   php artisan elasticms:generate:admin --model=App\Models\Article --fields=id,title,content,published_at
   

   • Generates a full admin interface with:
     • List view (filtering, sorting, pagination).
     • Create/Edit forms (with validation).
     • Delete actions.

2. Customize Fields: Override field types in a service provider:

   // config/elasticms.php
   'admin' => [
       'fields' => [
           'App\Models\Article' => [
               'content' => \ElasticMS\CoreBundle\Form\Type\CKEditorType::class,
           ],
       ],
   ],
   

3. Extend Functionality:

   • Actions: Add custom buttons (e.g., "Publish") via event listeners:

     use ElasticMS\CoreBundle\Event\AdminActionEvent;
     
     public function onAdminAction(AdminActionEvent $event) {
         if ($event->getModel() === Article::class && $event->getAction() === 'publish') {
             $event->getEntity()->update(['published_at' => now()]);
         }
     }
     

   • Filters: Extend the list view with custom filters using ElasticMS\CoreBundle\Event\AdminListEvent.

Integration Tips:

• Laravel Mix/Webpack: The admin panel uses Vue.js under the hood. Extend it by publishing assets:

  php artisan vendor:publish --provider="ElasticMS\CoreBundle\ElasticMSCoreBundle" --tag="assets"
  

• Authentication: Integrate with Laravel’s auth system via config/elasticms.php:

  'auth' => [
      'driver' => 'laravel', // or 'custom'
      'guard' => 'web',
  ],
  

2. API Development

Workflow:

1. Auto-Generate API: Annotate your model:

   use ElasticMS\Api\Annotation\ApiResource;
   
   #[ApiResource(
       operations: ['index', 'store', 'show', 'update', 'destroy'],
       uri: 'articles'
   )]
   class Article extends Model {}
   

   Run:

   php artisan elasticms:generate:api
   

2. Customize API:

   • Requests/Responses: Override serializers:

     use ElasticMS\CoreBundle\Serializer\Serializer;
     
     Serializer::extend(Article::class, function (Serializer $serializer) {
         $serializer->addField('custom_field', function (Article $article) {
             return $article->content->excerpt();
         });
     });
     

   • Routes: Manually define routes in routes/api.php:

     use ElasticMS\CoreBundle\Routing\ApiRouter;
     
     ApiRouter::resource('articles', \App\Models\Article::class);
     

3. Authentication: Use Laravel Sanctum/Passport or configure in config/elasticms.php:

   'api' => [
       'auth' => [
           'middleware' => 'auth:sanctum',
       ],
   ],
   

Integration Tips:

• Rate Limiting: Apply Laravel’s throttle middleware to API routes.
• Documentation: Use elasticms:generate:api-docs to auto-generate Swagger/OpenAPI specs.

3. Event-Driven Extensions

Leverage events to hook into the core bundle’s lifecycle:

• Admin Events:
  • AdminListEvent: Modify list queries.
  • AdminFormEvent: Alter form fields/validation.
  • AdminActionEvent: Handle custom actions (e.g., bulk operations).
• API Events:
  • ApiRequestEvent: Transform incoming requests.
  • ApiResponseEvent: Modify outgoing responses.

Example listener:

use ElasticMS\CoreBundle\Event\AdminListEvent;

public function onAdminList(AdminListEvent $event) {
    $event->getQuery()->where('published_at', '<=', now());
}

4. Database Migrations

• Shared Migrations: The bundle includes migrations for core tables (e.g., elasticms_admin_roles). Run:

  php artisan migrate
  

• Custom Migrations: Extend with your own tables while reusing the bundle’s auth system.

Gotchas and Tips

Pitfalls

1. Version Mismatches:

   • The bundle is tightly coupled with ElasticMS Admin (monorepo). Ensure all elasticms/* packages are on the same major version.
   • Fix: Use composer require elasticms/*@dev-main for bleeding-edge features.

2. Asset Conflicts:

   • The admin panel ships with Vue.js 3 and Bootstrap 5. Overriding assets may break UI.
   • Fix: Publish assets first (php artisan vendor:publish --tag=elasticms-assets) and extend the published files.

3. Caching Issues:

   • Admin panel routes are cached aggressively. Clear views after changes:

     php artisan view:clear
     php artisan cache:clear
     

4. Eloquent Model Requirements:

   • Models used with the admin/API must:
     • Extend ElasticMS\CoreBundle\Model\BaseModel (or implement ElasticMS\CoreBundle\Contracts\ElasticMSModel).
     • Gotcha: Forgetting this causes silent failures in generated CRUD.

5. Permission System:

   • The bundle includes a role-based permission system. Default roles (admin, editor) are created on install.
   • Tip: Use php artisan elasticms:install to reset permissions if corrupted.

Debugging Tips

1. Log Level: Enable debug mode in config/elasticms.php:

   'debug' => env('APP_DEBUG', false),
   

   Logs appear in storage/logs/elasticms.log.

2. Dump Events: Temporarily add a listener to dump events:

   public function debugEvents(object $event) {
       \Log::debug('Event:', [$event->getName(), get_class($event)]);
   }
   

3. Database Queries: Use Laravel’s query logging:

   \DB::enableQueryLog();
   // Trigger admin/API action
   \Log::info(\DB::getQueryLog());
   

Configuration Quirks

1. Dynamic Configuration: Override settings per-environment using config/elasticms.php:

   'admin' => [
       'title' => env('ELASTICMS_ADMIN_TITLE', 'My Admin'),
   ],
   

2. Multi-Tenant Support: The bundle supports tenants via config/elasticms.php:

   'tenancy' => [
       'enabled' => true,
       'model' => \App\Models\Tenant::class,
       'tenant_key' => 'domain',
   ],
   

   • Tip: Use ElasticMS\CoreBundle\Middleware\TenantMiddleware in app/Http/Kernel.php.

3. Localization: Translations are stored in resources/lang/vendor/elasticms. Extend them by publishing:

   php artisan vendor:publish --tag=elasticms-translations
   

Extension Points

1. Custom Admin Controllers: Override generated controllers by publishing the template:

   php artisan vendor:publish --tag