Vormia Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require vormiaphp/vormia
   php artisan vormia:install
   

   • Select Livewire or Inertia during interactive setup (or use --stack=livewire|inertia for CI).
   • Confirm overwrites for routes/api.php and app/Notifications.

2. Run Migrations:

   php artisan migrate
   

3. User Model Setup (Critical): Add traits to app/Models/User.php:

   use Vormia\Vormia\Traits\Model\HasSlugs;
   use Vormia\Vormia\Traits\Model\HasUserMeta;
   use Vormia\Vormia\Traits\Model\HasRolesPermissions;
   
   class User extends Authenticatable
   {
       use HasSlugs, HasUserMeta, HasRolesPermissions;
   }
   

4. First Use Case:

   // Create a user with meta data
   $user = User::create([
       'name' => 'John Doe',
       'email' => 'john@example.com',
       'password' => bcrypt('password'),
   ]);
   $user->setMeta('preferences', ['theme' => 'dark']);
   $user->assignRole('admin'); // Requires HasRolesPermissions
   

Where to Look First

• Documentation: docs/INSTALLATION.md (Laravel 12/Livewire 4 specific)
• Traits: vendor/vormiaphp/vormia/src/Vormia/Vormia/Traits/ (Core functionality)
• Middleware: vendor/vormiaphp/vormia/src/Vormia/Vormia/Middleware/ (Role/Permission checks)
• Jobs: app/Jobs/Vrm/ and app/Jobs/V1/ (Post-installation)

Implementation Patterns

Core Workflows

1. Role-Based Access Control (RBAC)

// Assign roles to user
$user->assignRole('editor');
$user->assignRole('moderator');

// Check permissions
if ($user->can('edit_posts')) {
    // Grant access
}

// Middleware (auto-registered)
Route::middleware(['role:admin'])->group(function () {
    // Admin-only routes
});

2. Media Handling (Image Processing)

use Vormia\Vormia\Facades\MediaForge;

// Upload and process image
$path = $request->file('avatar')->store('avatars');
$processed = MediaForge::make($path)
    ->resize(200, 200)
    ->watermark('logo.png', 0.2)
    ->save();

// Store processed path in user meta
$user->setMeta('avatar_processed', $processed);

3. Notifications

// Send notification
$user->notify(new Vrm\WelcomeNotification($user));

// Queue delayed notification
Vrm\WelcomeNotification::dispatch($user)->delay(now()->addHours(1));

4. API Authentication

// Protected API route (auto-handled by `api-auth` middleware)
Route::middleware(['api-auth'])->get('/user', function (Request $request) {
    return $request->user();
});

Integration Tips

Livewire Integration

1. Form Handling:

   use Vormia\Vormia\Livewire\Forms\VrmForm;
   
   public function mount() {
       $this->form = new VrmForm([
           'name' => '',
           'email' => '',
       ]);
   }
   
   public function rules() {
       return [
           'name' => 'required|string|max:255',
           'email' => 'required|email',
       ];
   }
   

2. Livewire Components:

   • Extend Vormia\Vormia\Livewire\Components\VrmComponent for shared functionality.
   • Use VrmTable for data grids with built-in pagination/sorting.

Inertia Integration

1. Page Components:

   // Inertia Controller
   public function show(User $user) {
       return Inertia::render('Users/Show', [
           'user' => $user->load('roles', 'meta'),
       ]);
   }
   

2. Shared Logic:

   • Use Vormia\Vormia\Services\VrmService for cross-cutting concerns (e.g., role checks).

Database Organization

• Meta Data: Store flexible data in meta table (key-value pairs).

  $user->setMeta('analytics', ['last_visit' => now()]);
  

• Slugs: Auto-generate with HasSlugs trait.

  $post = Post::create(['title' => 'Hello World']);
  // $post->slug = 'hello-world' (auto-generated)
  

Gotchas and Tips

Pitfalls

1. Missing Traits:

   • Error: Call to undefined method App\Models\User::setMeta()
   • Fix: Ensure all required traits (HasSlugs, HasUserMeta, HasRolesPermissions) are added to User model.

2. API Authentication:

   • Error: 401 Unauthorized on API routes
   • Fix: Add HasApiTokens trait to User model and run php artisan install:api during installation.

3. Livewire JS Dependencies:

   • Error: $ is not defined (jQuery missing)
   • Fix: Run npm install if using Livewire stack (installer should handle this, but verify resources/js/app.js includes Vormia imports).

4. Meta Data Serialization:

   • Issue: Arrays/objects in meta not persisting
   • Fix: Use json_encode()/json_decode() manually or rely on Vormia’s built-in serialization:

     $user->setMeta('settings', ['theme' => 'dark', 'notifications' => true]);
     $settings = $user->getMeta('settings', []); // Returns decoded array
     

5. Middleware Order:

   • Issue: role middleware not working
   • Fix: Ensure middleware is registered after auth:sanctum in app/Http/Kernel.php:

     'api' => [
         \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
         'throttle:api',
         \Vormia\Vormia\Middleware\ApiAuth::class,
         \Vormia\Vormia\Middleware\Role::class, // <-- Must come after auth
     ],
     

Debugging Tips

1. Log Middleware Decisions:

   // In app/Http/Middleware/Role.php (override Vormia's middleware)
   public function handle($request, Closure $next) {
       \Log::info('Role check for user: ' . $request->user()->id);
       return $next($request);
   }
   

2. Check Meta Data:

   // Dump all meta for a model
   \Log::debug('User meta:', $user->meta);
   

3. Validate Roles/Permissions:

   // Debug role assignments
   \Log::debug('User roles:', $user->roles->pluck('name'));
   

Configuration Quirks

1. Environment Variables:

   • Vormia uses standard Laravel .env keys (e.g., APP_URL, FILESYSTEM_DISK).
   • Custom Config: Publish config with:

     php artisan vendor:publish --provider="Vormia\Vormia\VormiaServiceProvider" --tag="config"
     

2. File System:

   • Defaults to public disk for uploads. Override in config/vormia.php:

     'disk' => 's3',
     'path' => 'vormia/uploads',
     

3. Notification Channels:

   • Extend Vormia\Vormia\Notifications\Channels\VrmChannel for custom channels.

Extension Points

1. Custom Roles/Permissions:

   // Extend Vormia's role system
   use Vormia\Vormia\Contracts\Role;
   
   class CustomRole implements Role {
       public function getPermissions() {
           return ['custom:permission'];
       }
   }
   

2. Media Processing:

   // Add custom image filter
   MediaForge::extend('custom', function ($image) {
       return $image->sepia();
   });
   

3. Livewire Components:

   // Create reusable Livewire component
   class VrmUserTable extends VrmComponent {
       public function render() {
           return view('livewire.vrm-user-table', [
               'users' => User::with('roles')->paginate(10),
           ]);
       }
   }
   

4. API Resources:

   // Extend Vormia's API responses
   class ExtendedUserResource extends \Vormia\Vormia\Http\Resources\UserResource {