Aiku ERP Development Guidelines
You are an expert Laravel developer working on Aiku, an open-source white-label ERP web application. Follow these guidelines strictly to maintain code quality and consistency.
Technology Stack
PHP 8.4.15Laravel Framework v12Inertia.js v2 (@inertiajs/inertia-laravel, @inertiajs/vue3)Vue 3Pest v4 (testing)Laravel Pint v1 (code formatting)Tailwind CSS v3Additional packages: Horizon v5, Octane v2, Sanctum v4, Scout v10, Telescope v5, Ziggy v2Core Principles
1. **Write clear, self-explanatory code** - NO code comments unless handling very complex logic
2. **Test every change** - Write or update tests, then run them to verify
3. **Follow existing conventions** - Check sibling files for structure, naming, and approach
4. **Use Laravel's built-in features** - Leverage the framework rather than bypassing it
5. **DO NOT run `vendor/bin/pint --dirty`** during development
PHP Standards
Type Declarations
Always use explicit return type declarationsUse PHP 8 constructor property promotionUse appropriate type hints for parameters```php
public function __construct(public GitHub $github) {}
protected function isAccessible(User $user, ?string $path = null): bool
{
// implementation
}
```
Control Structures
Always use curly braces, even for single-line statementsNo empty `__construct()` methods with zero parametersEnums
Use TitleCase for enum keys: `FavoritePerson`, `BestLake`, `Monthly`Laravel Best Practices
File Creation
1. Use `php artisan make:` commands for all new files
2. Pass `--no-interaction` to Artisan commands
3. For generic PHP classes: `php artisan make:class`
Database & Eloquent
**Prefer Eloquent relationships over raw queries**Use `Model::query()` instead of `DB::`Always use proper relationship methods with return type hintsUse eager loading to prevent N+1 queriesWhen creating models, also create factories and seedersMigrations
When modifying a column, include ALL previously defined attributes to avoid data lossControllers & Validation
Create Form Request classes for validation (not inline validation)Check sibling Form Requests for validation rule format (array vs string)Include both validation rules and custom error messagesAPIs
Default to Eloquent API Resources with versioningFollow existing API conventions if already establishedConfiguration
**Never use `env()` outside config files**Always use `config('app.name')` instead of `env('APP_NAME')`URL Generation
Prefer named routes with `route()` functionQueues
Use queued jobs with `ShouldQueue` interface for time-consuming operationsAuthentication
Use Laravel's built-in features: gates, policies, SanctumLaravel 12 Specifics
This project upgraded from Laravel 10 **without migrating to the new streamlined structure**. This is recommended by Laravel.
Laravel 10 Structure (Current)
Middleware: `app/Http/Middleware/`Service providers: `app/Providers/`Middleware registration: `app/Http/Kernel.php`Exception handling: `app/Exceptions/Handler.php`Console commands: `app/Console/Kernel.php`**No `bootstrap/app.php` application configuration**New Laravel 11+ Features Available
Eager load limiting: `$query->latest()->limit(10)`Model casts in `casts()` method (prefer over `$casts` property - follow existing conventions)Inertia.js v2
Place components in `resources/js/Pages` directoryUse `Inertia::render()` instead of Blade viewsLeverage v2 features: polling, prefetching, deferred props, infinite scrolling, lazy loadingForms
Use `<Form>` component (recommended) or `useForm` helper (for programmatic control)Available props: `resetOnError`, `resetOnSuccess`, `setDefaultsOnSuccess`Deferred Props
Add skeleton loaders/empty states when using deferred props```php
// routes/web.php
Route::get('/users', function () {
return Inertia::render('Users/Index', [
'users' => User::all()
]);
});
```
Testing with Pest
Test Requirements
**Every change must be tested**Run minimum number of tests neededTest happy paths, failure paths, and edge casesTests live in `tests/Feature` and `tests/Unit`Creating Tests
Use `php artisan make:test --pest {name}` (feature tests)Add `--unit` flag for unit tests**Never remove tests without approval**Running Tests
```bash
All tests
php artisan test
Specific file
php artisan test tests/Feature/ExampleTest.php
Filter by name
php artisan test --filter=testName
```
Test Syntax
```php
it('returns all', function () {
$response = $this->postJson('/api/docs', []);
$response->assertSuccessful();
});
```
Assertions
Use specific methods: `assertForbidden()`, `assertNotFound()`Not generic: `assertStatus(403)`Factories & Mocking
Use factories when creating models for testsCheck for custom factory states before manual setupUse `use function Pest\Laravel\mock;` before mockingFaker: Use `$this->faker->word()` or `fake()->randomDigit()` (follow existing conventions)Code Quality
Conventions
Use descriptive names: `isRegisteredForDiscounts` not `discount()`Check for existing components before creating new onesStick to existing directory structureDon't create new base folders without approvalDon't change dependencies without approvalDocumentation
Only create documentation files if explicitly requestedBe concise in explanations - focus on what's importantPHPDoc
Prefer PHPDoc blocks over commentsAdd useful array shape type definitionsCommon Issues
Vite Error
If you see "Unable to locate file in Vite manifest":
Run `npm run build` or ask user to run `npm run dev` / `composer run dev`Frontend Changes Not Reflected
User may need to run `npm run build`, `npm run dev`, or `composer run dev`Additional Features
Laravel Pennant
Feature flag management systemControls feature availability across organizations and user typesLaravel Pint
Run `vendor/bin/pint --dirty` before finalizing changesDo not run `vendor/bin/pint --test`Workflow
1. Check existing conventions in sibling files
2. Create files using `php artisan make:` commands
3. Write clear, self-documenting code (no comments)
4. Create/update tests for your changes
5. Run relevant tests to verify
6. Run Pint to format code
7. Ask user if they want to run full test suite