Laravel Starter Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer create-project nasirkhan/laravel-starter
   php artisan starter:install
   

   • Follow prompts for .env setup, database configuration, and asset compilation.

2. First Use Case: Create a Module

   php artisan module:build Blog --force
   

   • This generates a modular structure with:
     • Controllers (Backend/BlogController.php, Frontend/BlogController.php)
     • Routes (routes/backend/blog.php, routes/frontend/blog.php)
     • Views (resources/views/backend/blog/, resources/views/frontend/blog/)
     • Migrations (database/migrations/xxxx_create_blog_posts_table.php)
     • Livewire components (if applicable)

3. Key Directories to Explore

   • Modules: modules/ – Default modules like Auth, Article, Settings.
   • Backend: app/Http/Controllers/Backend/ – Admin controllers.
   • Frontend: app/Http/Controllers/Frontend/ – Public controllers.
   • Livewire: app/Livewire/ – Reusable components (e.g., Backend/Dashboard/Stats).
   • Resources: resources/views/ – Separated backend (backend/) and frontend (frontend/).

Implementation Patterns

1. Modular Development Workflow

• Create a Module:

  php artisan module:build [module-name] --force
  

  • Overwrites existing files with default stubs (e.g., controllers, routes, views).
• Extend a Module:
  • Add custom logic in app/Modules/[ModuleName]/ (e.g., app/Modules/Blog/Http/Controllers/Backend/).
  • Override default views in resources/views/backend/blog/ or resources/views/frontend/blog/.
• Register Module Routes:

  // In routes/backend.php or routes/frontend.php
  Route::module('blog', 'Blog');
  

2. Backend vs. Frontend Separation

• Backend Routes:

  // routes/backend.php
  Route::prefix('admin')->middleware(['auth', 'admin'])->group(function () {
      Route::resource('posts', 'Backend\PostController');
  });
  

• Frontend Routes:

  // routes/frontend.php
  Route::get('blog', 'Frontend\BlogController@index')->name('blog.index');
  

• Shared Logic: Place in app/Http/Controllers/ or modularize further.

3. Livewire Integration

• Create a Livewire Component:

  php artisan make:livewire Backend/Post/Index
  

• Use in Blade:

  <livewire:backend.post.index />
  

• Default Components:
  • Backend/Dashboard/Stats (for admin dashboards).
  • Backend/Settings/General (for configuration panels).

4. Role-Permission Management

• Assign Permissions:

  php artisan starter:assign-permission user@user.com create_post
  

• Create Roles:

  php artisan starter:create-role editor
  

• Dynamic Menu System:
  • Define menus in database/seeders/MenuDatabaseSeeder.php.
  • Render in Blade:

    <livewire:backend.menu />
    

5. Localization and Theming

• Switch Themes:
  • Backend: Toggle dark mode via app/Providers/AppServiceProvider or user preferences.
  • Frontend: Use Tailwind classes (e.g., dark:bg-gray-800).
• Language Switcher:

  <livewire:frontend.language-switcher />
  

6. API Development

• API Routes:

  // routes/api.php
  Route::middleware('auth:sanctum')->group(function () {
      Route::apiResource('posts', 'Api\PostController');
  });
  

• Sanctum Setup:
  • Ensure config/sanctum.php is configured.
  • Use HasApiTokens trait in models.

7. Testing Patterns

• Unit Tests:

  // tests/Unit/Modules/Blog/PostTest.php
  public function test_post_creation()
  {
      $post = Post::factory()->create();
      $this->assertDatabaseHas('posts', ['id' => $post->id]);
  }
  

• Feature Tests:

  // tests/Feature/Blog/PostTest.php
  public function test_post_page_loading()
  {
      $response = $this->get('/blog/post/1');
      $response->assertStatus(200);
  }
  

• Dusk Tests:

  // tests/Browser/Backend/PostTest.php
  public function test_admin_can_create_post()
  {
      $this->browse(function (Browser $browser) {
          $browser->loginAs(User::first())
                  ->visit('/admin/posts/create')
                  ->type('title', 'Test Post')
                  ->press('Save')
                  ->assertSee('Test Post');
      });
  }
  

Gotchas and Tips

Pitfalls

1. Module Namespace Conflicts

   • Issue: Modules may clash with core Laravel namespaces (e.g., Auth module vs. Illuminate\Auth).
   • Fix: Prefix module namespaces (e.g., Modules\Auth\ instead of Auth\).
   • Tip: Use php artisan module:build with unique names (e.g., BlogPosts instead of Blog).

2. Livewire Component Caching

   • Issue: Changes to Livewire components may not reflect immediately due to caching.
   • Fix:

     php artisan view:clear
     php artisan cache:clear
     

   • Tip: Use wire:ignore for dynamic content to bypass caching:

     <div wire:ignore>{{ $dynamicContent }}</div>
     

3. Permission Cache Stale Data

   • Issue: After adding new permissions, the cache may not update.
   • Fix:

     php artisan cache:forget spatie.permission.cache
     php artisan config:clear
     

   • Tip: Use the starter:update-permissions command to refresh:

     php artisan starter:update-permissions
     

4. Frontend Asset Compilation

   • Issue: npm run dev or npm run build may fail silently.
   • Fix:
     • Ensure node_modules is clean:

       rm -rf node_modules package-lock.json
       npm install
       

     • Use npm run format for Blade templates if Prettier fails.
   • Tip: Add a script to package.json for debugging:

     "scripts": {
         "dev": "vite",
         "debug": "vite --force"
     }
     

5. Database Seed Order

   • Issue: Seeders may run out of order, causing foreign key errors.
   • Fix:
     • Use --fresh to reset the database:

       php artisan db:seed --fresh
       

     • For essential data only:

       php artisan db:seed-essential --fresh
       

6. Docker/Sail Quirks

   • Issue: Sail containers may not pick up .env changes.
   • Fix:
     • Rebuild containers:

       sail build --no-cache
       sail up -d
       

     • Ensure .env is mounted in docker-compose.yml:

       volumes:
           - ./.env:/opt/app/.env
       

Debugging Tips

1. Livewire Debugging

   • Enable Livewire logging in config/livewire.php:

     'log' => env('LIVEWIRE_LOG', true),
     

   • Check logs at storage/logs/livewire.log.

2. Route Debugging

   • List all routes:

     php artisan route:list
     

   • Debug module routes:

     php artisan route:list --module=blog
     

3. Permission Debugging

   • Check a user’s permissions:

     dd(auth()->user()->getAllPermissions()->pluck('name'));
     

   • List all permissions:

     php artisan starter:list-permissions
     

4. Module Debugging

   • Check if a module is registered:

     dd(app('modules')->get('blog'));
     

   • Verify module routes:

     Route::get('/debug-module', function () {
         return app('modules')->get('blog')->getRoutes();
     });
     

Extension Points

1. Custom Module Templates
   • Override default module stubs by publishing them:

     php artisan vendor:publish --tag=module-stubs
     

   • Edit