Laravel Starter Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer create-project nasirkhan/laravel-starter
   

   Or clone the repo and run:

   composer install
   php artisan starter:install
   

2. First Use Case:

   • Access the demo backend at http://localhost:8000/admin with credentials:

     User: super@admin.com
     Pass: secret
     

   • Explore the modular structure by navigating to resources/modules/ to see pre-built modules like posts, comments, and categories.

3. Where to Look First:

   • Core Configuration: config/starter.php
   • Module Structure: resources/modules/
   • Backend Routes: routes/backend.php
   • Frontend Routes: routes/web.php
   • Custom Commands: app/Console/Commands/

Implementation Patterns

Workflows

1. Modular Development:

   • Create a new module with:

     php artisan module:build MODULE_NAME
     

   • Follow the module structure:

     resources/modules/MODULE_NAME/
     ├── Http/Controllers/
     ├── Resources/views/
     ├── Database/Migrations/
     ├── Database/Seeders/
     └── ...
     

   • Register the module in config/starter.php under modules.

2. Role-Permission Management:

   • Use the built-in commands to manage permissions:

     php artisan starter:permission:create "module.posts.create" --description="Create Posts"
     php artisan starter:role:assign "admin" "module.posts.*"
     

   • Integrate permissions in controllers:

     public function __construct()
     {
         $this->middleware('can:module.posts.create')->only(['create']);
     }
     

3. Backend/Frontend Separation:

   • Backend: Use Backend namespace (e.g., Backend\Http\Controllers).
   • Frontend: Use Frontend\Http\Controllers.
   • Share logic via App\Services or App\Helpers.

4. Livewire Integration:

   • Use Livewire components in modules (e.g., resources/modules/posts/Http/Livewire/).
   • Example:

     php artisan make:livewire Posts/ManagePosts
     

5. Localization:

   • Add translations in resources/lang/en/ or resources/lang/{locale}/.
   • Use the @lang directive in Blade:

     {{ __('messages.welcome') }}
     

6. Dynamic Menus:

   • Define menus in database/seeders/MenuDatabaseSeeder.php.
   • Display menus in Blade:

     <x-cube::menu :items="$menuItems" />
     

Integration Tips

• Use Companion Packages:
  • nasirkhan/module-manager: For advanced module management.
  • nasirkhan/laravel-cube: For reusable UI components (e.g., modals, cards).
  • nasirkhan/laravel-jodit: For WYSIWYG editors in modules.
• Backup System:
  • Trigger backups via:

    php artisan starter:backup
    

  • Configure backup paths in config/starter.php.
• Log Viewer:
  • Access logs at /admin/logs.
  • Customize log levels in config/logging.php.

Gotchas and Tips

Pitfalls

1. Module Caching:

   • After creating/updating a module, run:

     php artisan clear-all
     

   • Or clear module-specific caches:

     php artisan module:clear-cache
     

2. Permission Caching:

   • Forget the Spatie permission cache after changes:

     php artisan cache:forget spatie.permission.cache
     

3. Frontend Asset Mixing:

   • Avoid mixing npm and yarn lockfiles (especially on Windows).
   • Use npm run dev or npm run build for frontend assets.

4. Livewire Conflicts:

   • Ensure Livewire components are namespaced correctly (e.g., Posts\ManagePosts).
   • Avoid naming conflicts with existing Livewire classes.

5. Database Seeders:

   • Disable dummy data in production by setting SEED_DUMMY_DATA=false in .env.
   • Use --force for production seeders:

     php artisan db:seed-essential --fresh --force
     

6. IDE Helper Files:

   • Regenerate helpers after model changes:

     composer ide-helper
     

   • Ensure .phpstorm.meta.php is included in your IDE’s inspection scope.

Debugging Tips

• Module Not Loading:

  • Verify the module is enabled in config/starter.php.
  • Check for missing migrations:

    php artisan module:migrate MODULE_NAME
    

• Permission Denied:

  • Test permissions with:

    php artisan starter:permission:list
    

  • Use tinker to debug:

    php artisan tinker
    >>> \Spatie\Permission\Models\Permission::where('name', 'module.posts.create')->get();
    

• Livewire Errors:

  • Check for JavaScript conflicts (e.g., duplicate Alpine.js or jQuery).
  • Use @error directives in Blade:

    @error('message') <div>{{ $message }}</div> @enderror
    

• Backup Failures:

  • Verify storage permissions:

    chmod -R 775 storage/
    

  • Check config/starter.php for correct backup paths.

Extension Points

1. Custom Commands:

   • Extend existing commands in app/Console/Commands/.
   • Example:

     php artisan make:command CustomBackup
     

2. Module Events:

   • Listen to module events in EventServiceProvider:

     protected $listen = [
         'module.created' => ['App\Listeners\LogModuleCreation'],
     ];
     

3. Service Providers:

   • Register custom providers in config/app.php.
   • Example:

     'providers' => [
         // ...
         App\Providers\CustomServiceProvider::class,
     ],
     

4. Middleware:

   • Add middleware to app/Http/Kernel.php:

     'backend' => [
         \App\Http\Middleware\CheckForBackend::class,
         \App\Http\Middleware\Authenticate::class,
     ],
     

5. Blade Directives:

   • Extend Blade directives in app/Providers/BladeServiceProvider:

     Blade::directive('custom', function ($expression) {
         return "<?php echo customFunction($expression); ?>";
     });
     

6. API Routes:

   • Extend API routes in routes/api.php:

     Route::prefix('v1')->group(function () {
         Route::resource('posts', \App\Http\Controllers\Api\PostController::class);
     });
     

Configuration Quirks

• Dark Mode:

  • Toggle dark mode via localStorage or session:

    localStorage.setItem('dark_mode', 'true');
    

  • Ensure CSS variables are updated in resources/css/app.css.

• Social Login:

  • Configure credentials in .env:

    GOOGLE_CLIENT_ID=your_id
    GOOGLE_CLIENT_SECRET=your_secret
    

  • Use the Socialite facade:

    use Socialite;
    $user = Socialite::driver('google')->user();
    

• WYSIWYG Editor:

  • Configure Jodit in config/jodit.php.
  • Use the Blade component:

    <x-jodit::editor name="content" />