theradcoza/Laravel-Docker-Dev-Template

Template

Fork 0

Files

theRADcozaDEV 1e868b3ac1 Update documentation for hybrid setup approach

2026-03-09 03:52:30 +02:00

9.0 KiB

Raw Blame History

AI Assistant Context

This document provides context for AI coding assistants working on projects built with this template.

Template Overview

This is a ready-to-use Laravel Docker Development Template with everything pre-installed:

✅ Laravel 11 with Breeze authentication (Blade + dark mode)
✅ Filament v3.3 admin panel with user management
✅ Pest testing framework
✅ Laravel Pint code style
✅ Docker-based development environment
✅ Production deployment to Ubuntu 24.04 (no Docker)
✅ Modular architecture
✅ Multi-database support (MySQL, PostgreSQL, SQLite)

Setup time: 2 minutes - just run ./setup.sh and everything is ready!

Technology Stack

Layer	Technology
Backend	Laravel 11+, PHP 8.2+
Frontend	Blade, Livewire (NO Vue/React/Inertia)
Admin	Filament 3.x
Database	MySQL 8 / PostgreSQL 15 / SQLite
Cache/Queue	Redis
Auth	Laravel Breeze (Blade + Livewire) - PRE-INSTALLED
Testing	Pest - PRE-INSTALLED
Permissions	spatie/laravel-permission
Audit	owen-it/laravel-auditing
Error Tracking	spatie/laravel-flare + spatie/laravel-ignition
Code Style	Laravel Pint

Important: No JavaScript Frameworks

This template deliberately avoids JavaScript frameworks (Vue, React, Inertia) to keep debugging simple. All frontend is:

Blade templates
Livewire for reactivity
Alpine.js (included with Livewire)
Tailwind CSS

Do NOT suggest or implement Vue/React/Inertia solutions.

Architecture

Module Structure

Features are organized as modules in app/Modules/:

app/Modules/
└── ModuleName/
    ├── Config/
    │   └── module_name.php       # Module config (incl. audit settings)
    ├── Database/
    │   ├── Migrations/
    │   └── Seeders/
    ├── Filament/
    │   └── Resources/            # Admin CRUD + Audit Log
    ├── Http/
    │   ├── Controllers/
    │   ├── Middleware/
    │   └── Requests/
    ├── Models/                   # With ModuleAuditable trait
    ├── Policies/
    ├── Services/                 # Business logic goes here
    ├── Routes/
    │   ├── web.php
    │   └── api.php
    ├── Resources/
    │   ├── views/
    │   ├── css/
    │   └── lang/
    ├── Permissions.php           # Module permissions
    └── ModuleNameServiceProvider.php

Creating Modules

# Basic module
php artisan make:module ModuleName

# With model + Filament resource + audit
php artisan make:module ModuleName --model=ModelName

# With API routes
php artisan make:module ModuleName --model=ModelName --api

Key Traits and Interfaces

For auditable models:

use App\Traits\ModuleAuditable;
use OwenIt\Auditing\Contracts\Auditable;

class YourModel extends Model implements Auditable
{
    use ModuleAuditable;
    
    // Exclude sensitive fields from audit
    protected $auditExclude = ['password', 'secret_key'];
}

File Locations

What	Where
Laravel app	`src/`
Docker configs	`docker/`
Production deploy	`deploy/`
Setup scripts	`scripts/`
Documentation	`docs/`
Module code	`src/app/Modules/`
Filament resources	`src/app/Modules/*/Filament/Resources/`
Module views	`src/app/Modules/*/Resources/views/`
Module routes	`src/app/Modules/*/Routes/`
Module migrations	`src/app/Modules/*/Database/Migrations/`

Common Tasks

Add a New Feature

Create module: php artisan make:module FeatureName --model=MainModel
Edit migration: app/Modules/FeatureName/Database/Migrations/
Update model fillables: app/Modules/FeatureName/Models/
Customize Filament resource: app/Modules/FeatureName/Filament/Resources/
Run migrations: php artisan migrate
Seed permissions: php artisan db:seed --class=PermissionSeeder

Add a Model to Existing Module

# Create model manually
php artisan make:model Modules/ModuleName/Models/NewModel -m

# Move migration to module folder
mv database/migrations/*_create_new_models_table.php \
   app/Modules/ModuleName/Database/Migrations/

# Add audit trait to model
# Create Filament resource manually or use:
php artisan make:filament-resource NewModel \
    --model=App\\Modules\\ModuleName\\Models\\NewModel

Add API Endpoint

// app/Modules/ModuleName/Routes/api.php
Route::prefix('api/module-name')
    ->middleware(['api', 'auth:sanctum'])
    ->group(function () {
        Route::get('/items', [ItemController::class, 'index']);
        Route::post('/items', [ItemController::class, 'store']);
    });

Add Permission

// app/Modules/ModuleName/Permissions.php
return [
    'module_name.view' => 'View Module',
    'module_name.create' => 'Create records',
    'module_name.edit' => 'Edit records',
    'module_name.delete' => 'Delete records',
    'module_name.new_action' => 'New custom action',  // Add this
];

Then run: php artisan db:seed --class=PermissionSeeder

Customize Filament Resource

// app/Modules/ModuleName/Filament/Resources/ModelResource.php

public static function form(Form $form): Form
{
    return $form->schema([
        Forms\Components\TextInput::make('name')->required(),
        Forms\Components\Select::make('status')
            ->options(['active' => 'Active', 'inactive' => 'Inactive']),
        // Add more fields
    ]);
}

public static function table(Table $table): Table
{
    return $table->columns([
        Tables\Columns\TextColumn::make('name')->searchable(),
        Tables\Columns\BadgeColumn::make('status'),
        // Add more columns
    ]);
}

Environment

Development

Run commands via make shell then php artisan ...
Or use make artisan cmd='...'
Database: accessible at localhost:3306 (MySQL) or localhost:5432 (PostgreSQL)
Mail: caught by Mailpit at localhost:8025

Production

No Docker - native PHP on Ubuntu 24.04
Web server: Nginx or Apache
Use deploy/scripts/server-setup.sh for initial setup
Use deploy/scripts/deploy.sh for deployments

Code Style

Follow Laravel conventions
Use Pint for formatting: make lint
Business logic in Services, not Controllers
Use Form Requests for validation
Use Policies for authorization
Use Resources for API responses

Testing

# Run tests
make test

# With coverage
make test-coverage

# Create test
php artisan make:test Modules/ModuleName/FeatureTest

Debugging

Check Laravel logs: storage/logs/laravel.log
Check container logs: make logs
Use Telescope (if installed): /telescope
Use Tinker: make tinker
Ignition shows errors in browser (dev only)

Gotchas

Module views use namespace: view('module-slug::viewname')
Module routes are prefixed: /module-slug/...
Permissions use snake_case: module_name.action
Filament resources auto-discover from Filament/Resources/
Migrations auto-load from Database/Migrations/
Always run PermissionSeeder after adding permissions

Quick Reference

Artisan Commands

php artisan make:module Name              # Create module
php artisan make:module Name --model=M    # With model
php artisan make:filament-resource Name   # Filament resource
php artisan make:model Name -m            # Model + migration
php artisan make:controller Name          # Controller
php artisan make:request Name             # Form request
php artisan make:policy Name              # Policy
php artisan migrate                       # Run migrations
php artisan db:seed                       # Run seeders
php artisan config:clear                  # Clear config cache
php artisan route:list                    # List routes

Make Commands

make up                    # Start containers
make down                  # Stop containers
make shell                 # Shell into app
make artisan cmd='...'     # Run artisan
make composer cmd='...'    # Run composer
make test                  # Run tests
make lint                  # Fix code style
make fresh                 # Reset database
make logs                  # View logs
make queue-start           # Start queue worker
make queue-logs            # View queue logs
make scheduler-start       # Start scheduler
make backup                # Backup database
make restore file=...      # Restore database

9.0 KiB Raw Blame History