Koverae Ui Builder Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require koverae/koverae-ui-builder
   

   The package auto-registers its service provider and Blade directives.

2. Publish Config (if customization is needed):

   php artisan vendor:publish --tag=koverae-ui-builder-config
   

3. Generate a Basic Component:

   php artisan koverae:make-form login-form
   

   This creates a Blade component (resources/views/components/login-form.blade.php) with a pre-configured form structure.

4. Use in Blade:

   <x-login-form />
   

   The component is now ready for customization via Blade slots or props.

First Use Case

Build a login form with validation and CSRF protection in 3 steps:

1. Generate the form:

   php artisan koverae:make-form auth/login
   

2. Customize fields in the Blade file:

   <x-auth.login>
       <x-slot name="email">
           <input type="email" name="email" required>
       </x-slot>
       <x-slot name="password">
           <input type="password" name="password" required>
       </x-slot>
   </x-auth.login>
   

3. Use in a view:

   <x-auth.login action="{{ route('login') }}" />
   

Implementation Patterns

Core Workflows

1. Component Generation

• Forms: Scaffold forms with pre-defined slots for fields, buttons, and validation.

  php artisan koverae:make-form user/profile
  

• Tables: Generate data tables with sortable columns and pagination.

  php artisan koverae:make-table users-table
  

• Carts: Create e-commerce cart components with add/remove actions.

  php artisan koverae:make-cart shopping-cart
  

2. Customization via Blade Slots

Override default sections of components:

<x-user.profile>
    <x-slot name="header">
        <h1>Custom Header</h1>
    </x-slot>
    <x-slot name="actions">
        <button>Save</button>
    </x-slot>
</x-user.profile>

3. Dynamic Props

Pass data dynamically:

<x-users-table :users="$users" :columns="['id', 'name', 'email']" />

4. Integration with Koverae Ecosystem

• Validation: Use Koverae’s validation rules by extending the component’s validate() method (if supported in future versions).
• Localization: Leverage Koverae’s translation system for multi-language support.

5. Reusable Components

• Extract Logic: Move business logic to controllers or services, keeping Blade components lightweight.
• Partial Reuse: Use @include or @component for shared UI snippets (e.g., modals, alerts).

Integration Tips

1. Laravel Mix/Vite: Ensure your build system processes Blade components. Add to resources/js/app.js:

   import './../../views/components/**/*.js';
   

2. Testing: Use Laravel’s render() helper to test components:

   $this->assertStringContainsString('Login', $this->render('components.auth.login'));
   

3. Livewire/Alpine.js: Combine with Livewire for dynamic forms:

   <x-auth.login wire:model="formData">
       <!-- Fields -->
   </x-auth.login>
   

4. Tailwind CSS: Extend the package’s default styles by publishing assets:

   php artisan vendor:publish --tag=koverae-ui-builder-assets
   

   Then override in your tailwind.config.js.

Gotchas and Tips

Pitfalls

1. Component Naming Collisions: Avoid naming conflicts with existing Blade components. Use namespaces:

   php artisan koverae:make-form admin/user-form
   

   Blade usage:

   <x-admin.user-form />
   

2. Slot Overrides Not Working: Ensure slot names match exactly (case-sensitive). Debug with:

   @dump($__env->slot('header'))
   

3. Dynamic Props Not Binding: Verify props are passed as arrays or objects:

   <!-- Wrong -->
   <x-users-table columns="id,name">
   
   <!-- Correct -->
   <x-users-table :columns="['id', 'name']" />
   

4. Asset Loading Issues: If CSS/JS fails to load, check the published assets path in config/koverae-ui-builder.php.

Debugging

1. Check Generated Files: Components are created in resources/views/components/. Inspect for errors.

2. Enable Blade Debugging: Add to AppServiceProvider:

   Blade::setEchoFormat(function ($value) {
       return "<!-- {{ $value }} -->";
   });
   

3. Log Component Data: Use @dd in Blade to inspect props/slots:

   @dd($this->header)
   

Tips

1. Component Templates: Use --template flag to customize scaffolding (if supported in future versions):

   php artisan koverae:make-form login --template=auth
   

2. Partial Updates: For SPAs, combine with Inertia.js or Laravel Livewire for partial rendering.

3. Dark Mode: Extend the package’s theme system (if available) or override CSS variables:

   @layer components {
       .koverae-dark .btn-primary {
           @apply bg-gray-800;
       }
   }
   

4. Version Pinning: Pin the package version in composer.json to avoid breaking changes:

   "koverae/koverae-ui-builder": "1.0.0"
   

5. Community Extensions: Monitor the repo for plugins (e.g., additional component types, integrations). Contribute if missing features are critical.