Laravel Cube Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require nasirkhan/laravel-cube
   

   Automatically registers the service provider.

2. Configure Default Framework: Set CUBE_FRAMEWORK in .env to either tailwind or bootstrap.

3. Tailwind Setup (if using Tailwind CSS v4): Add to your main CSS file:

   @import "../../vendor/nasirkhan/laravel-cube/resources/css/tailwind.css";
   

4. First Use Case: Use a basic button in a Blade view:

   <x-cube::button variant="primary">Click Me</x-cube::button>
   

Where to Look First

• Documentation: Start with the README for installation and basic usage.
• Icon Reference: Check docs/icons.md for available icons and their usage.
• Published Views: After publishing views (php artisan vendor:publish --tag=cube-views), inspect resources/views/vendor/cube/components/ for customization.
• Backend Components: As of v4.3.0, look for documented backend.* components (e.g. backend.section-show-table) in the docs — these are aimed at admin/CRUD screens and are a good starting point for dashboard work.

Implementation Patterns

Usage Patterns

1. Framework Agnostic Components: Use the same Blade component syntax regardless of the underlying CSS framework:

   <!-- Uses Tailwind by default -->
   <x-cube::button variant="primary">Default</x-cube::button>
   
   <!-- Override per component -->
   <x-cube::button framework="bootstrap" variant="primary">Bootstrap</x-cube::button>
   

2. Form Handling: Group form inputs with labels, errors, and validation:

   <x-cube::group name="email" label="Email" required>
       <x-cube::input type="email" name="email" :value="old('email')" required />
       <x-cube::error :messages="$errors->get('email')" />
   </x-cube::group>
   

3. Image Uploads (v4.3.0+): Use the new image upload component for file inputs with previews. Remember enctype="multipart/form-data" on the form and validate server-side:

   <form method="POST" action="{{ route('profile.update') }}" enctype="multipart/form-data">
       @csrf
       <x-cube::group name="avatar" label="Avatar">
           <x-cube::image-upload name="avatar" :value="old('avatar', $user->avatar)" accept="image/*" />
           <x-cube::error :messages="$errors->get('avatar')" />
       </x-cube::group>
       <x-cube::button type="submit" variant="primary">Save</x-cube::button>
   </form>
   

   Validate in the controller as usual ('avatar' => ['nullable', 'image', 'max:2048']) and store via $request->file('avatar')->store('avatars').

4. Backend / Admin Tables (v4.3.0+): Use the documented backend.section-show-table component to render admin list screens without hand-rolling table markup:

   <x-cube::backend.section-show-table :rows="$users" :columns="['name', 'email', 'created_at']" />
   

   Check the new docs for the exact prop contract before adopting it.

5. Navigation: Use responsive navigation components with active state support:

   <x-cube::nav-link href="{{ route('dashboard') }}" :active="request()->routeIs('dashboard')">
       Dashboard
   </x-cube::nav-link>
   

6. Icons: Embed icons with customizable variants and classes:

   <x-cube::icon name="bell" variant="solid" class="text-red-500" />
   

7. Livewire Integration: Cube components work seamlessly with Livewire. Use them in Livewire views like any other Blade component.

Workflows

1. Component-Based Development:

   • Replace repetitive HTML snippets (e.g., buttons, modals) with reusable Blade components.
   • Example: Replace all primary buttons in a project with <x-cube::button variant="primary">.

2. Theming:

   • Publish and override component views to customize styles or behavior.
   • Example: Publish views, then modify resources/views/vendor/cube/components/button.blade.php.

3. Dark Mode:

   • For Tailwind-based components, leverage Cube’s built-in dark mode support by using Tailwind’s dark mode classes in your published views.

4. Admin/CRUD Screens:

   • For dashboards, lean on the backend.* components (e.g. backend.section-show-table) instead of writing bespoke table markup; wrap them with your own controller/pagination logic.

5. Progressive Adoption:

   • Start by replacing one type of component (e.g., buttons) and gradually adopt others.
   • Use per-component framework overrides to test Bootstrap vs. Tailwind side-by-side.

Integration Tips

1. Tailwind CSS:

   • Ensure Tailwind’s content configuration includes Cube’s views:

     content: [
         './resources/views/**/*.blade.php',
         './vendor/nasirkhan/laravel-cube/resources/views/**/*.blade.php',
     ],
     

   • Use Cube’s Tailwind-specific classes (e.g., bg-blue-500 for buttons) directly in Blade.

2. Bootstrap 5:

   • Cube’s Bootstrap components use standard Bootstrap classes (e.g., btn-primary).
   • Ensure Bootstrap’s CSS and JS are properly loaded in your layout.

3. Livewire:

   • Cube components work out-of-the-box with Livewire. Example:

     <x-cube::button wire:click="save" :loading="$processing">
         Save
     </x-cube::button>
     

   • With Livewire uploads, combine wire:model on the image upload component with TemporaryUploadedFile handling rather than mixing a standard POST form.

4. File Uploads:

   • Pair the new image upload component with Laravel’s Storage facade and File::image() validation rules; keep the component focused on markup only.

5. Customization:

   • Extend components by publishing their views and adding custom logic:

     <!-- resources/views/vendor/cube/components/button.blade.php -->
     @props(['customProp' => false])
     <button {{ $attributes }}>
         @if($customProp)
             Custom Button
         @else
             {{ $slot }}
         @endif
     </button>
     

Gotchas and Tips

Pitfalls

1. Tailwind CSS Setup:

   • Issue: Forgetting to import Cube’s Tailwind CSS file (@import "../../vendor/nasirkhan/laravel-cube/resources/css/tailwind.css") can break Tailwind-based components.
   • Fix: Add the import to your main CSS file if using Tailwind v4.

2. Framework Mismatch:

   • Issue: Using a Tailwind-specific class (e.g., bg-blue-500) in a Bootstrap component or vice versa.
   • Fix: Stick to the framework’s native classes or use per-component overrides:

     <x-cube::button framework="tailwind" class="bg-blue-500">Tailwind Button</x-cube::button>
     

3. Missing Form Enctype for Image Uploads:

   • Issue: The v4.3.0 image upload component won’t transmit files if the surrounding <form> lacks enctype="multipart/form-data".
   • Fix: Always set the enctype; also confirm upload_max_filesize / post_max_size in php.ini are adequate for real-world images.

4. Backend Component Documentation Lag:

   • Issue: backend.* components (like backend.section-show-table) shipped with docs in v4.3.0 but have less field mileage than core components; prop names may shift in minor releases.
   • Fix: Pin the package version ("nasirkhan/laravel-cube": "4.3.*") while adopting them, and publish views so you can diff against upstream changes.

5. Icon Availability:

   • Issue: Using an icon name that doesn’t exist in the Flowbite Blade Icons pack.
   • Fix: Check docs/icons.md for the full list of available icons.

6. Published Views Overwrite:

   • Issue: Updating the package may overwrite custom published views.
   • Fix: Keep a backup of modified views or use mergeConfigPath in config/cube.php to preserve customizations.

7. Livewire Conflicts:

   • Issue: Cube components with wire: directives may conflict if not properly scoped.
   • Fix: Ensure Livewire components are correctly namespaced and avoid duplicate IDs.

Debugging

1. Component Not Rendering:

   • Verify the component namespace is correct (e.g., <x-cube::button>), including dotted backend namespaces (<x-cube::backend.section-show-table>).
   • Check for typos in the component name or props.

2. Styles Not Applying:

   • For Tailwind: Ensure the @import is in your CSS and Tailwind is scanning Cube’s views.
   • For Bootstrap: Verify Bootstrap’s CSS is loaded before Cube’s components.

3. Uploads Silently Failing:

   • Check the form enctype, PHP upload limits, and filesystems.php defaults. Inspect the actual UploadedFile in the controller with dd($request->file('avatar')).

4. Dark Mode Issues:

   • Ensure your Tailwind config includes dark mode:

     darkMode: 'class',
     

   • Add dark: variants to Cube’s published views if needed.

Tips

1. Component Props:

   • Use php artisan vendor:publish --tag=cube-config to inspect available props for each component in config/cube.php.

2. Dark Mode:

   • For Tailwind components, add dark: classes to published views:

     <button class="bg-blue-500 dark:bg-blue-700">
     

3. Performance:

   • Lazy-load non-critical components (e.g., modals) using Alpine.js or Livewire.

4. Testing:

   • Test components in isolation using Laravel’s test helpers:

     $this->blade('<x-cube::button>Test</x-cube::button>')->assertSee('button');
     

   • For uploads, use UploadedFile::fake()->image('avatar.jpg') and assert storage with Storage::assertExists().

5. Custom Icons:

   • Extend the icon pack by publishing the icon views and adding custom SVG files to resources/views/vendor/cube/icons/.

6. Framework-Specific Logic:

   • Use Blade @if to conditionally render framework-specific markup:

     @if($framework === 'tailwind')
         <div class="p-4 bg-gray-100">
     @else
         <div class="p-4 bg-light">
     @endif
     

7. Configuration:

   • Customize default props globally in config/cube.php:

     'defaults' => [
         'framework' => 'tailwind',
         'button' => [
             'size' => 'md',
         ],
     ],
     

8. Companion Packages:

   • Use nasirkhan/laravel-sharekit for social sharing without bloating Cube:

     <x-sharekit::buttons :url="$post->url" />