Aura Cms Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require eminiarts/aura-cms
   php artisan aura:install
   

   Follow the interactive prompts to configure core settings (admin user, team structure, etc.).

2. First Resource:

   php artisan aura:resource posts --fields="title:text,content:textarea,status:select:published,draft"
   

   This generates a posts resource with basic fields and CRUD routes.

3. Access Admin Panel: Visit /admin (or configured route) and log in with the admin credentials created during installation.

First Use Case: Creating a Blog

1. Define a Resource:

   php artisan aura:resource blog-posts --fields="title:text,slug:slug,content:wysiwyg,published_at:datetime,featured_image:image"
   

2. Customize Fields (via admin UI or config):
   • Set slug to auto-generate from title
   • Configure featured_image to allow multiple uploads
3. Create Content:
   • Navigate to Resources > Blog Posts in the admin panel
   • Click "New" and populate fields using the visual editor

Implementation Patterns

Core Workflows

Resource Development

1. Scaffolding:

   php artisan aura:resource products --fields="name:text,price:decimal,sku:text,description:textarea,images:gallery,stock:integer"
   

   Generates:

   • Eloquent model (Product.php)
   • Migration
   • Livewire components (List, Create, Edit, View)
   • Admin routes and policies

2. Field Customization:

   // In a service provider or custom field class
   public function configure()
   {
       return [
           'label' => 'Product Price',
           'hint' => 'Enter price in USD',
           'validation' => 'required|numeric|min:0',
           'default' => 0.00,
       ];
   }
   

3. Dynamic Field Logic:

   // Conditional fields example
   public function rules()
   {
       return [
           'is_digital' => [
               'type' => 'boolean',
               'label' => 'Digital Product',
               'show' => ['sku' => 'hidden'],
           ],
           'sku' => [
               'type' => 'text',
               'label' => 'SKU',
               'rules' => 'required|unique:products,sku',
               'show' => ['is_digital' => false],
           ],
       ];
   }
   

Multi-Tenancy

1. Enable Teams:

   // config/aura.php
   'teams' => [
       'enabled' => true,
       'default_team' => '1',
   ],
   

2. Team-Aware Models:

   use Aura\Base\Traits\TeamScope;
   
   class Product extends Model
   {
       use TeamScope;
   }
   

3. Team Switching:

   // In a controller or Livewire component
   $this->impersonateUser($team->users()->first());
   

Plugin Development

1. Scaffold Plugin:

   php artisan aura:plugin seo-tools
   

2. Register Plugin:

   // In AppServiceProvider
   Aura::registerPlugin(new \App\Plugins\SeoToolsPlugin());
   

3. Add Plugin Fields:

   public function fields()
   {
       return [
           'meta_title' => [
               'type' => 'text',
               'label' => 'SEO Title',
               'resource' => 'posts',
           ],
           'meta_description' => [
               'type' => 'textarea',
               'label' => 'SEO Description',
               'resource' => 'posts',
           ],
       ];
   }
   

Integration Tips

1. Frontend Integration:

   // Display resource data in a Blade view
   @foreach($posts as $post)
       <article>
           <h2>{{ $post->title }}</h2>
           <div>{!! $post->content !!}</div>
           @if($post->featured_image)
               <img src="{{ $post->featured_image->url }}" alt="{{ $post->title }}">
           @endif
       </article>
   @endforeach
   

2. API Endpoints:

   // routes/api.php
   Route::get('/posts', [PostController::class, 'index'])
       ->middleware('auth:sanctum')
       ->middleware('can:view,post');
   

3. Custom Actions:

   // In a resource definition
   'actions' => [
       'publish' => [
           'label' => 'Publish',
           'method' => 'POST',
           'icon' => 'heroicon-o-paper-airplane',
           'handler' => [PostActionHandler::class, 'handlePublish'],
       ],
   ],
   

4. Event Listeners:

   // Listen for resource creation
   public function handle(PostCreated $event)
   {
       // Send notification, update search index, etc.
   }
   

Gotchas and Tips

Common Pitfalls

1. Field Initialization:

   • Issue: Custom fields may not appear in the admin panel.
   • Fix: Ensure your field class extends Aura\Base\Fields\Field and is registered in config/aura.php under fields.

2. Team Scoping:

   • Issue: Data not filtering by team in multi-tenancy mode.
   • Fix: Verify your models use TeamScope trait and the teams feature is enabled in config.

3. Livewire Component Loading:

   • Issue: Custom Livewire components not loading.
   • Fix: Publish assets first:

     php artisan aura:publish
     

4. Permission Denied:

   • Issue: Getting "403 Forbidden" on admin routes.
   • Fix: Check:
     • User has the admin role
     • Middleware is properly registered in app/Http/Kernel.php
     • No custom policies are blocking access

5. Migration Conflicts:

   • Issue: Schema conflicts when adding custom tables.
   • Fix: Use php artisan aura:database-to-resources to generate resources from existing tables.

Debugging Tips

1. Enable Debug Mode:

   // config/aura.php
   'debug' => env('APP_DEBUG', false),
   

   This adds console logs and error boundaries.

2. Field Validation:

   • Use php artisan aura:field:validate to test field rules independently.

3. Livewire Debugging:

   • Add {{ dd($this->data) }} to Livewire components to inspect form data.
   • Check browser console for Livewire-specific errors.

4. Database Queries:

   • Enable Laravel query logging:

     DB::enableQueryLog();
     // ... perform operations ...
     dd(DB::getQueryLog());
     

Configuration Quirks

1. Resource Storage:

   • By default, resources use a shared posts table. To use custom tables:

     // In resource definition
     'table' => 'custom_posts',
     

2. Field Defaults:

   • Set defaults in the field definition:

     'status' => [
         'type' => 'select',
         'options' => ['draft', 'published'],
         'default' => 'draft',
     ],
     

3. Media Handling:

   • Configure storage disks in config/aura.php:

     'media' => [
         'disk' => 'public',
         'optimize' => true,
         'max_size' => '10MB',
     ],
     

4. Theme Customization:

   • Publish theme assets:

     php artisan aura:publish --theme
     

   • Override default views in resources/views/vendor/aura.

Extension Points

1. Custom Field Types:

   // Create a new field class
   namespace App\Fields;
   
   use Aura\Base\Fields\Field;
   
   class CustomField extends Field
   {
       public function render()
       {
           return view('aura::fields.custom', ['field' => $this]);
       }
   
       public function process($value)
       {
           // Custom processing logic
           return $value;
       }
   }
   

2. Resource Actions:

   // Register a custom action
   Aura::extend('posts', function ($resource) {
       $resource->actions()->add('custom_action', [
           'label' => 'Custom Action',
           'method' => 'POST',
           'icon' => 'heroicon-o-star',
           'handler' => function ($model) {
               // Custom logic
           },
       ]);
   });
   

3. Plugin System:

   • Extend core functionality without modifying package files:

     namespace App\Plugins;
     
     use Aura\Base\Plugins\Plugin;
     
     class MyPlugin extends Plugin
     {
         public function boot()
         {
             // Add custom fields, resources, or middleware
         }
     }