Turbine Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   laravel new my-app
   composer require clarkeash/turbine
   php artisan turbine:install [--teams]
   php artisan migrate:fresh
   npm run build
   

   • Run php artisan turbine:install without --teams for a basic setup or include it for team support.

2. First Use Case:

   • Access /login to test authentication flow.
   • Register a new user via /register.
   • Navigate to /dashboard post-login to see the starter dashboard.

3. Where to Look First:

   • Configuration: config/turbine.php for customization (e.g., team settings, branding).
   • Views: resources/views for Flux-based UI components (e.g., auth/login.blade.php).
   • Livewire Components: app/Http/Livewire for reusable logic (e.g., Auth/Login, Profile/UpdatePassword).
   • Routes: routes/web.php for predefined routes (e.g., /dashboard, /profile).

Implementation Patterns

Core Workflows

1. Authentication Flow:

   • Use Auth/Login Livewire component for login logic.
   • Extend app/Http/Livewire/Auth/Login.php to customize validation or redirect logic.
   • Example:

     protected function redirectTo(): string
     {
         return route('dashboard'); // Override default redirect
     }
     

2. Team Management (if enabled):

   • Invite users via Team/InviteUsers Livewire component.
   • Update team details using Team/UpdateTeam (e.g., team name).
   • Example team route:

     Route::middleware(['auth', 'team'])->group(function () {
         Route::get('/teams/{team}', [TeamController::class, 'show']);
     });
     

3. Profile Management:

   • Update user details (name/email) via Profile/UpdateProfile Livewire.
   • Change password using Profile/UpdatePassword Livewire.
   • Example extension:

     // app/Http/Livewire/Profile/UpdateProfile.php
     protected $rules = [
         'name' => 'required|string|max:255',
         'email' => 'required|email|max:255|unique:users,email,'.$this->user->id,
         // Add custom rules (e.g., 'phone' => 'nullable|digits:10')
     ];
     

4. Dashboard Customization:

   • Extend the starter dashboard by modifying resources/views/dashboard.blade.php.
   • Add new Livewire components to the dashboard layout:

     @livewire('custom.component-name')
     

5. Legal Pages:

   • Customize /privacy and /terms by editing resources/views/legal/privacy.blade.php and terms.blade.php.

Integration Tips

• Flux Pro Components:

  • Turbine assumes you have a paid Flux Pro account. Use Flux’s documentation to integrate custom components.
  • Example: Replace Turbine’s default button with a Flux Pro variant:

    <x-flux.button type="primary">Custom Action</x-flux.button>
    

• Middleware:

  • Add custom middleware to app/Http/Kernel.php for route protection:

    protected $routeMiddleware = [
        'team' => \App\Http\Middleware\TeamMiddleware::class,
    ];
    

• Testing:

  • Use Laravel’s testing helpers for authentication:

    $this->actingAs(User::factory()->create());
    $this->get('/dashboard')->assertStatus(200);
    

  • Test Livewire components with livewire():

    $this->livewire(Auth\Login::class)->set('email', 'test@example.com');
    

• Asset Customization:

  • Override default styles by publishing assets:

    php artisan vendor:publish --tag=turbine-assets
    

  • Modify resources/css/app.css or resources/js/app.js.

Gotchas and Tips

Pitfalls

1. Flux Pro Dependency:

   • Issue: Turbine requires a paid Flux Pro account to render UI components. Without it, the app will break.
   • Fix: Ensure your Flux Pro account is active and the license is linked in your project.
   • Workaround: Use Flux’s free tier for development, but switch to Pro for production.

2. Team Middleware Conflicts:

   • Issue: If you enable --teams but don’t configure the team middleware correctly, users may access team routes without belonging to a team.
   • Fix: Verify app/Http/Middleware/TeamMiddleware.php checks for auth and team_id:

     public function handle(Request $request, Closure $next)
     {
         if (!auth()->check() || !auth()->user()->team_id) {
             abort(403);
         }
         return $next($request);
     }
     

3. Migration Conflicts:

   • Issue: Running migrate:fresh after adding custom columns (e.g., phone to users) may fail if the migration order is incorrect.
   • Fix: Place custom migrations in database/migrations/2024_XX_XX_XX_add_custom_columns_to_users_table.php and run them manually:

     php artisan migrate --path=database/migrations/2024_XX_XX_XX_add_custom_columns_to_users_table.php
     

4. Livewire Component Caching:

   • Issue: Changes to Livewire components (e.g., app/Http/Livewire/Auth/Login.php) may not reflect immediately due to caching.
   • Fix: Clear Livewire cache:

     php artisan livewire:discover
     php artisan view:clear
     

5. Asset Build Failures:

   • Issue: npm run build may fail if node_modules are corrupted or dependencies are outdated.
   • Fix: Reinstall dependencies:

     rm -rf node_modules package-lock.json
     npm install
     npm run build
     

Debugging Tips

1. Livewire Errors:

   • Check storage/logs/livewire.log for component-specific errors.
   • Use dd() or dump() in Livewire methods to inspect data:

     public function updatedEmail()
     {
         dump($this->email); // Debug input
     }
     

2. Flux Component Issues:

   • Verify Flux Pro components are correctly imported in resources/js/app.js:

     import { Button } from '@fluxui/pro';
     

   • Check browser console for Flux-related errors (e.g., missing licenses).

3. Route Debugging:

   • List all routes to verify Turbine’s routes are registered:

     php artisan route:list
     

   • Example output should include:

     |        | GET|HEAD | dashboard | App\Http\Controllers\DashboardController@index | web,auth
     |        | GET|HEAD | login     | Livewire|\App\Http\Livewire\Auth\Login | web,guest
     

4. Database Debugging:

   • Use Tinker to inspect user/team data:

     php artisan tinker
     >>> \App\Models\User::with('team')->get();
     

Extension Points

1. Custom Livewire Components:

   • Add new components to app/Http/Livewire and register them in resources/views/layouts/app.blade.php:

     @livewireScripts
     @stack('scripts')
     

   • Example: Create app/Http/Livewire/CustomComponent.php:

     namespace App\Http\Livewire;
     use Livewire\Component;
     class CustomComponent extends Component
     {
         public function render()
         {
             return view('livewire.custom-component');
         }
     }
     

2. Custom Validation:

   • Extend Turbine’s validation rules in app/Providers/AppServiceProvider.php:

     use Illuminate\Support\Facades\Validator;
     Validator::extend('custom_rule', function ($attribute, $value, $parameters, $validator) {
         return $value === 'expected';
     });
     

3. API Endpoints:

   • Add API routes in routes/api.php and use Turbine’s auth middleware:

     Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
         return $request->user();
     });
     

4. Email Customization:

   • Override Turbine’s email templates by publishing them:

     php artisan vendor:publish --tag=turbine-views
     

   • Modify resources/views/vendor/turbine/emails/ (e.g., password-reset.blade.php).

5. Notifications:

   • Extend Turbine’s notifications by creating custom notification classes:

     namespace App\Notifications;
     use Illuminate\Bus\Queueable;
     use Illuminate\Notifications\Notification;
     class