L-Ami-Fiduciaire/docs/development-guide.md

Development Guide — L'Ami Fiduciaire

Generated: 2026-03-08 | Scan Level: Quick

Prerequisites

• PHP 8.2+ (recommended: 8.4)
• Composer v2
• Node.js 22+
• npm
• Docker (for Laravel Sail)

Quick Start

1. Clone & Install

composer install
npm install

2. Environment Setup

cp .env.example .env
php artisan key:generate

3. Start Development Environment (Docker/Sail)

vendor/bin/sail up -d
vendor/bin/sail artisan migrate

4. Run Development Servers

# All-in-one: PHP server + Queue + Logs + Vite (hot reload)
vendor/bin/sail composer run dev

# Or with SSR:
vendor/bin/sail composer run dev:ssr

This runs concurrently:

• php artisan serve — Laravel application server
• php artisan queue:listen — Queue worker
• php artisan pail — Log viewer
• npm run dev — Vite dev server (HMR)

Docker Services

Service	Image	Ports
laravel.test	sail-8.5/app	80 (app), 5173 (Vite)
mysql	mysql:8.4	3306
mailpit	axllent/mailpit	1025 (SMTP), 8025 (UI)
soketi	soketi:latest	6001 (WS), 9601 (metrics)

All commands should be prefixed with vendor/bin/sail when running inside Docker.

Build Commands

# Development build with HMR
npm run dev

# Production build
npm run build

# Production build with SSR
npm run build:ssr

Code Quality

PHP Formatting (Laravel Pint)

# Fix formatting (dirty files only)
vendor/bin/sail bin pint --dirty --format agent

# Run all formatting
composer lint

# Check without fixing
composer test:lint

JavaScript/TypeScript Linting

# ESLint (fix mode)
npm run lint

# Prettier (fix mode)
npm run format

# Prettier (check only)
npm run format:check

Testing

Running Tests

# Run all tests
vendor/bin/sail artisan test --compact

# Run with filter
vendor/bin/sail artisan test --compact --filter=testName

# Run specific test file
vendor/bin/sail artisan test --compact tests/Feature/Auth/AuthenticationTest.php

# Full test suite (includes lint + tests)
composer test

Test Structure

• tests/Feature/ — Feature/integration tests (13 files)
  • Auth/ — Authentication tests (login, registration, 2FA, email verification, password)
  • Settings/ — Settings tests (profile, password, 2FA)
  • DashboardTest.php, UserGroupTest.php
• tests/Unit/ — Unit tests

Creating Tests

# Feature test (default)
vendor/bin/sail artisan make:test --pest MyFeatureTest

# Unit test
vendor/bin/sail artisan make:test --pest --unit MyUnitTest

Key Development Patterns

Controllers

• Render Inertia pages: Inertia::render('PageName', ['prop' => $data])
• Use Form Request classes for validation (never inline validation)
• Invokable controllers for single-action endpoints

Route Functions (Wayfinder)

• Import from @/actions/ (controllers) or @/routes/ (named routes)
• Type-safe route generation for frontend

Frontend Components

• All pages in resources/js/pages/ (mapped to routes by Inertia)
• shadcn-vue components in resources/js/components/ui/
• Composables in resources/js/composables/
• Layouts in resources/js/layouts/

Database

• Use Eloquent models and relationships (avoid DB:: facade)
• Create Form Requests for all CRUD operations
• Use factories for test data

Artisan Commands

# Create model with migration, factory, seeder
vendor/bin/sail artisan make:model ModelName -mfs --no-interaction

# Create controller
vendor/bin/sail artisan make:controller ControllerName --no-interaction

# Create form request
vendor/bin/sail artisan make:request StoreEntityRequest --no-interaction

# Run migrations
vendor/bin/sail artisan migrate

# Fresh migration with seeding
vendor/bin/sail artisan migrate:fresh --seed

CI/CD

GitHub Actions run on push/PR to develop, main, master, workos:

1. Lint (lint.yml): Pint → Prettier → ESLint
2. Tests (tests.yml): Full test suite on PHP 8.4 and 8.5 matrix