Getting Started

Minimal Steps to Begin

Installation:
```
composer create-project nasirkhan/laravel-starter
php artisan starter:install
```
- Follow prompts for .env, database, and asset setup.
- Use --demo flag for pre-seeded data.
First Use Case:
- Access the backend at /admin with default credentials:
```
User: super@admin.com
Pass: secret
```
- Explore the Dashboard and Posts modules to understand the modular structure.
Key Directories:
- app/Modules/ – Core modules (e.g., Auth, Posts, Settings).
- resources/views/ – Separated into backend/ and frontend/ themes.
- routes/ – web.php (frontend), admin.php (backend).

Implementation Patterns

1. Modular Development

Create a New Module:
```
php artisan module:build MODULE_NAME
```
- Generates:
  - Database migrations (/database/migrations/).
  - Controllers (/app/Modules/MODULE_NAME/Http/Controllers/).
  - Views (/resources/views/backend/modules/MODULE_NAME/).
  - Routes (/routes/admin.php or web.php).
- Pattern: Extend BaseModule for shared functionality (e.g., permissions, CRUD logic).

Module Structure:

MODULE_NAME/
├── Config/          # Module-specific config
├── Database/        # Migrations, seeders
├── Http/            # Controllers, Forms, Requests
├── Resources/       # Views, assets
└── Providers/       # Service providers

2. Frontend/Backend Separation

Routes:
- Frontend: routes/web.php (e.g., /posts, /categories).
- Backend: routes/admin.php (e.g., /admin/posts, /admin/settings).
Views:
- Backend uses CoreUI (Bootstrap 5) with dark mode.
- Frontend uses Tailwind CSS.
- Shared components in resources/views/layouts/.

3. Dynamic Menus

Management:
- Admin panel at /admin/menus.
- Menu items are nested under their parent menu (no standalone index).
Usage:
- Define menus in database/seeders/MenuDatabaseSeeder.php.
- Render menus in views using:
```
@include('backend.partials.menu', ['menu' => 'sidebar'])
```

4. Authentication & Authorization

Roles/Permissions:
- Use Spatie’s spatie/laravel-permission package.
- Seed roles/permissions via AuthTableSeeder.
- Assign permissions to users:
```
$user->givePermissionTo('edit_posts');
```
- Gate checks in controllers:
```
public function __construct() {
    $this->middleware('can:manage_posts')->only(['index', 'store']);
}
```
Social Login:
- Pre-configured for Google, Facebook, GitHub.
- Extend SocialAccountService to add new providers.

5. Livewire Integration

Usage:
- Example: PostsTable in app/Modules/Posts/Http/Livewire/.
- Bind Livewire components to Blade:
```
<livewire:posts-table />
```
Patterns:
- Use withPagination() for datatables.
- Share data with $this->posts = Post::latest()->get();.

6. Localization & Theming

Languages:
- Switcher in the backend header.
- Translations in resources/lang/ (e.g., en/posts.php).
- Use __('posts.title') in views.
Themes:
- Toggle dark mode via data-theme attribute.
- Override CSS in resources/css/backend/custom.css.

7. Backup & Logs

Backups:
- Trigger via /admin/backups or CLI:
```
php artisan backup:run
```
- Stored in storage/app/backups/.
Logs:
- View logs at /admin/log-viewer.
- Filter by level (error, warning, info).

Gotchas and Tips

Pitfalls

Permission Caching:

After adding new permissions, run:

php artisan cache:forget spatie.permission.cache

Or clear all caches:
```
php artisan clear-all
```

Module Namespace Conflicts:
- Ensure module names are unique (e.g., Posts vs. BlogPosts).
- Avoid naming modules after Laravel core classes (e.g., User).

Livewire Component Isolation:

Livewire components in modules must be namespaced:

<livewire:modules.posts.posts-table /> <!-- Correct -->
<livewire:posts-table /> <!-- Fails -->

Asset Compilation:
- Run npm run dev or npm run build after adding frontend assets.
- Use mix in webpack.mix.js to customize builds.
Database Seeders:
- Disable dummy data in production:
```
SEED_DUMMY_DATA=false
```
- Run essential seeders separately:
```
php artisan db:seed-essential --fresh
```
Menu Hierarchy:
- Menu items cannot be deleted if they have children.
- Use the "Delete with Children" option in the dropdown.

Debugging Tips

Artisan Commands:

List all custom commands:
```
php artisan list
```

Debug module generation:

php artisan module:build MODULE_NAME --verbose

Livewire Errors:
- Check the browser console for JavaScript errors.
- Enable Livewire logging in .env:
```
LIVEWIRE_LOG_LEVEL=debug
```
Permission Denied:
- Verify the user has the correct role/permission:
```
dd(auth()->user()->getAllPermissions()->pluck('name'));
```
- Check middleware in app/Http/Kernel.php.
Route Conflicts:
- Dump all routes:
```
php artisan route:list
```
- Ensure module routes are namespaced (e.g., admin.posts.index).

Extension Points

Custom Modules:
- Extend BaseModule to add shared logic (e.g., app/Modules/BaseModule.php).
- Override module templates in resources/views/backend/modules/MODULE_NAME/.

Social Login:

Add new providers by extending SocialAccountService:

public function getTwitterProvider()
{
    return Socialite::driver('twitter')->stateless();
}

Theming:
- Override CoreUI/Tailwind variables in:
  - resources/css/backend/custom.scss (backend).
  - resources/css/frontend/custom.css (frontend).

Backup Customization:

Extend BackupService to add custom backup items:

public function items()
{
    return [
        \Spatie\Backup\Tasks\DumpDatabaseTask::new(),
        \Spatie\Backup\Tasks\FilesTask::new([
            'storage/app/public',
        ]),
    ];
}

Dynamic Forms:

Use Livewire Forms for dynamic CRUD:

public $form = [
    'title' => '',
    'content' => '',
];

Bind to Blade:
```
<input wire:model="form.title" />
```

Performance Quirks

Eager Loading:

Avoid N+1 queries in Livewire:

public function mount()
{
    $this->posts = Post::with('author', 'category')->get();
}

Menu Caching:
- Clear menu cache after updates:
```
php artisan cache:clear
```

Asset Optimization:

Use mix.version() to bust caches in production:

<link href="{{ mix('css/backend/app.css', 'v' . config('app.version')) }}" rel="stylesheet">

Laravel Starter Laravel Package