218 lines
17 KiB
Markdown
218 lines
17 KiB
Markdown
<laravel-boost-guidelines>
|
|
=== projekt szabályok ===
|
|
|
|
# Hibrid architektúra: Legacy vs. Modern
|
|
|
|
A projekt jelenleg átmeneti fázisban van a régi Laravel 8-as architektúráról a modern Laravel 12-es felépítésre. KRITIKUS fontosságú a két "világ" megkülönböztetése:
|
|
|
|
### 1. Legacy Világ (Csak karbantartás)
|
|
- **Technológiai stekk**: jQuery, Bootstrap, Laravel Mix (`webpack.mix.js`), DataTables, Mustache.js.
|
|
- **Belépési pont**: `resources/views/layout/core.blade.php`, `/legacy` útvonalak, és a hagyományos Blade nézeteket használó kontrollerek.
|
|
- **Assetek**: A `mix()` függvénnyel kezelve. A fájlok a `resources/js/` mappában találhatók (kivéve a `modern` almappát).
|
|
- **Szabály**: Ezekhez CSAK hibajavítás vagy kisebb módosítás esetén nyúlj. NE implementálj ide új funkciókat, hacsak nincs rá kifejezett kérés.
|
|
|
|
### 2. Modern Világ (Elsődleges fejlesztés)
|
|
- **Technológiai stekk**: Laravel 12, Filament v4 (TALL stekk: Tailwind, Alpine.js, Laravel, Livewire), Vite (`vite.config.js`).
|
|
- **Belépési pont**: `/admin` (Filament Dashboard), `resources/modern/` mappa.
|
|
- **Assetek**: A `vite()` függvénnyel kezelve. A stílusokhoz Tailwind CSS v4-et használunk.
|
|
- **Szabály**: MINDEN új funkciót Filament resource-ok/oldalak vagy modern Livewire komponensek használatával kell megvalósítani.
|
|
|
|
### 3. Átállás és Modernizáció
|
|
- **"Clean Cut" megközelítés**: Szisztematikusan váltjuk ki a régi jQuery megoldásokat modern Laravel 12-es megfelelőkre.
|
|
- **Auditálás**: Használd a `BaseAuditable` osztályt minden új modellnél a konzisztens követhetőség érdekében.
|
|
- **Refaktorálás**: Ha egy legacy kontroller/nézet jelentős átalakítást igényel, javasold annak áthelyezését egy Filament Resource-ba.
|
|
|
|
# Projekt-specifikus szabályok
|
|
|
|
- **API válaszok**: Használd a `flugger/laravel-responder` csomagot (`responder()` helper) minden API válaszhoz. Kövesd az `OrderController.php`-ban látható mintát.
|
|
- **API verziózás**: Az API verziókat a névterekből kell kinyerni a `parseAPIVersionFromNamespace(__NAMESPACE__)` helper segítségével.
|
|
- **Dokumentáció**: Használd a Scribe-ot az API dokumentációhoz. Használj `@group`, `@authenticated`, `@bodyParam`, és `@responseField` annotációkat a kontrollerekben.
|
|
- **Modellek**: Az új modelleknek jellemzően a `BaseAuditable` osztályból kell származniuk a sima Eloquent `Model` helyett, ha auditálás szükséges.
|
|
- **Helperek**: Használd az `app/helpers.php` fájlban definiált projekt-specifikus helpereket (pl. `formatterPhoneNumber`, `formatterDateTime`, `getSql`).
|
|
- **Fordítások**: Használd a `laravel-lang/lang` csomagot a többnyelvű támogatáshoz.
|
|
- **Enumok**: Használd a `bensampo/laravel-enum` csomagot a típusbiztos felsorolásokhoz (pl. `OrderStatusEnum`, `OrderType`).
|
|
|
|
=== alapvető szabályok ===
|
|
|
|
# Laravel Boost Irányelvek
|
|
|
|
A Laravel Boost irányelveket kifejezetten a Laravel karbantartói állították össze ehhez az alkalmazáshoz. Ezeket az irányelveket szigorúan be kell tartani a legjobb Laravel fejlesztési élmény biztosítása érdekében.
|
|
|
|
## Alapvető kontextus
|
|
|
|
Ez egy Laravel alkalmazás, a fő ökoszisztéma csomagok és verziók alább láthatók. Te ezeknek a szakértője vagy. Gondoskodj róla, hogy tartsd magad ezekhez a specifikus csomagokhoz és verziókhoz.
|
|
|
|
- php - 8.4
|
|
- filament/filament (FILAMENT) - v4
|
|
- laravel/framework (LARAVEL) - v12
|
|
- laravel/prompts (PROMPTS) - v0
|
|
- laravel/sanctum (SANCTUM) - v4
|
|
- livewire/livewire (LIVEWIRE) - v3
|
|
- laravel/boost (BOOST) - v2
|
|
- laravel/mcp (MCP) - v0
|
|
- laravel/pail (PAIL) - v1
|
|
- laravel/sail (SAIL) - v1
|
|
- pestphp/pest (PEST) - v3
|
|
- phpunit/phpunit (PHPUNIT) - v11
|
|
- tailwindcss (TAILWINDCSS) - v4
|
|
|
|
## Képességek aktiválása
|
|
|
|
Ez a projekt tartomány-specifikus képességekkel rendelkezik. Kötelező aktiválnod a releváns képességet, amikor abban a tartományban dolgozol — ne várd meg, amíg elakadsz.
|
|
|
|
- `laravel-best-practices` — Használd ezt a képességet Laravel PHP kód írásakor, átnézésekor vagy refaktorálásakor. Ez magában foglalja kontrollerek, modellek, migrációk, form requestek, policy-k, jobok, ütemezett parancsok, service osztályok és Eloquent lekérdezések készítését vagy módosítását. Aktiváld N+1 és lekérdezési teljesítményproblémák, gyorsítótárazási stratégiák, autorizációs és biztonsági minták, validáció, hibakezelés, sor- és job konfiguráció, útvonal definíciók és architektúrális döntések esetén. Használd továbbá Laravel kód áttekintéséhez és meglévő kódok refaktorálásához a legjobb gyakorlatok szerint. Minden Laravel háttér PHP kódmintát érintő feladathoz.
|
|
- `livewire-development` — Használd minden olyan feladathoz vagy kérdéshez, amely a Livewire-t érinti. Aktiváld, ha a felhasználó említi a Livewire-t, a wire: direktívákat, vagy Livewire-specifikus koncepciókat, mint a wire:model, wire:click. Lefedi az új komponensek építését, reaktivitási hibák keresését, valós idejű form validációt, betöltési állapotokat, a Livewire 2-ről 3-ra való migrációt, komponens formátumok konvertálását és teljesítményoptimalizálást. Ne használd nem-Livewire reaktív UI-hoz (React, Vue, csak Alpine, Inertia.js) vagy standard Laravel formokhoz Livewire nélkül.
|
|
- `pest-testing` — Ezt a képességet kizárólag Pest PHP teszteléshez használd Laravel projektekben. Aktiváld, amikor tesztet írsz, szerkesztesz, javítasz vagy refaktorálsz — beleértve a kódmódosítás után eltört tesztek javítását, asszerciók hozzáadását, PHPUnit tesztek Pest-re konvertálását, datasetek hozzáadását és TDD munkafolyamatokat. Mindig aktiváld, ha a felhasználó Pest-ben való írásról kérdez, teszt fájlokat vagy könyvtárakat említ (tests/Feature, tests/Unit), vagy architektúra teszteket. Lefedi az it()/expect() szintaxist, dataseteket, mockolást, böngésző tesztelést, arch()-ot, Livewire komponens teszteket, RefreshDatabase-t és minden Pest 4 funkciót. Ne használd factory-k, seeder-ek, migrációk, kontrollerek, modellek vagy nem teszt jellegű PHP kódok szerkesztéséhez.
|
|
- `tailwindcss-development` — Mindig aktiváld, ha a felhasználó üzenete bármilyen formában tartalmazza a 'tailwind' szót. Továbbá használd: responzív rács elrendezések (többoszlopos kártya rácsok, termék rácsok), flex/grid oldalstruktúrák (oldalsávos dashboardok, fix fejlécek, mobil-navigáció), UI komponensek stílusozása (kártyák, táblázatok, navigációs sávok, árazási szakaszok, formok, inputok, jelvények), sötét mód variánsok hozzáadása, térköz vagy tipográfia javítása, valamint Tailwind v3/v4 munkák esetén. Fő felhasználási eset: Tailwind utility osztályok írása vagy javítása HTML sablonokban (Blade, JSX, Vue). Hagyd ki háttér PHP logika, adatbázis lekérdezések, API útvonalak, HTML/CSS komponens nélküli JavaScript, CSS fájl auditok, build eszköz konfiguráció és vanilla CSS esetén.
|
|
|
|
## Konvenciók
|
|
|
|
- Követned kell az alkalmazásban használt összes meglévő kódkonvenciót. Fájl létrehozásakor vagy szerkesztésekor ellenőrizd a szomszédos fájlokat a helyes struktúra, megközelítés és elnevezés érdekében.
|
|
- Használj leíró neveket a változókhoz és metódusokhoz. Például: `isRegisteredForDiscounts`, nem pedig `discount()`.
|
|
- Új komponens írása előtt ellenőrizd a meglévő komponenseket az újrahasznosíthatóság érdekében.
|
|
|
|
## Ellenőrző szkriptek
|
|
|
|
- Ne készíts ellenőrző szkripteket vagy kísérletezz, ha a tesztek lefedik az adott funkciót és bizonyítják a működését. Az egység- és funkcionális tesztek fontosabbak.
|
|
|
|
## Alkalmazás struktúra és architektúra
|
|
|
|
- Tartsd magad a meglévő könyvtárstruktúrához; ne hozz létre új alapkatalógusokat jóváhagyás nélkül.
|
|
- Ne változtasd meg az alkalmazás függőségeit jóváhagyás nélkül.
|
|
|
|
## Frontend csomagolás
|
|
|
|
- Ha a felhasználó nem látja a frontend változást a felületen, az jelentheti azt, hogy futtatnia kell az `npm run build`, `npm run dev` vagy `composer run dev` parancsot. Kérdezz rá.
|
|
|
|
## Dokumentációs fájlok
|
|
|
|
- Dokumentációs fájlokat csak akkor hozz létre, ha a felhasználó kifejezetten kéri.
|
|
|
|
## Válaszok
|
|
|
|
- Légy tömör a magyarázatokban - fókuszálj a fontos dolgokra, ahelyett, hogy nyilvánvaló részleteket magyaráznál.
|
|
|
|
=== boost szabályok ===
|
|
|
|
# Laravel Boost
|
|
|
|
## Eszközök
|
|
|
|
- A Laravel Boost egy kifejezetten ehhez az alkalmazáshoz tervezett eszközökkel rendelkező MCP szerver. Preferáld a Boost eszközöket a manuális alternatívákkal szemben, mint a shell parancsok vagy fájlbeolvasások.
|
|
- Használd a `database-query` eszközt csak olvasható lekérdezések futtatásához az adatbázison, ahelyett, hogy nyers SQL-t írnál a tinkerbe.
|
|
- Használd a `database-schema` eszközt a táblák szerkezetének vizsgálatához migrációk vagy modellek írása előtt.
|
|
- Használd a `get-absolute-url` eszközt a projekt URL-jeinek helyes sémájának, domainjének és portjának feloldásához. Mindig használd ezt, mielőtt URL-t osztanál meg a felhasználóval.
|
|
- Használd a `browser-logs` eszközt a böngésző naplók, hibák és kivételek beolvasásához. Csak a friss naplók hasznosak, hagyd figyelmen kívül a régi bejegyzéseket.
|
|
|
|
## Dokumentáció keresése (FONTOS)
|
|
|
|
- Kódmódosítás előtt mindig használd a `search-docs` eszközt. Ne hagyd ki ezt a lépést. Ez automatikusan a telepített csomagok alapján ad verzióspecifikus dokumentációt.
|
|
- Adj át egy `packages` tömböt az eredmények szűkítéséhez, ha tudod, mely csomagok relevánsak.
|
|
- Használj több széles, téma alapú keresést: `['rate limiting', 'routing rate limiting', 'routing']`. Számíts rá, hogy a legrelevánsabb eredmények lesznek elöl.
|
|
- Ne adj csomagneveket a kereséshez, mert a csomaginformáció már meg van osztva. Használd a `test resource table` kifejezést, ne a `filament 4 test resource table`-t.
|
|
|
|
### Keresési szintaxis
|
|
|
|
1. Használj szavakat az automatikusan csonkolt ÉS logikához: a `rate limit` találatot ad a "rate" ÉS "limit" szavakra is.
|
|
2. Használj `"idézőjeles kifejezéseket"` a pontos pozícióillesztéshez: az `"infinite scroll"` megköveteli az egymás melletti szavakat a megadott sorrendben.
|
|
3. Kombináld a szavakat és kifejezéseket a vegyes kereséshez: `middleware "rate limit"`.
|
|
4. Használj több keresést a VAGY logikához: `queries=["authentication", "middleware"]`.
|
|
|
|
## Artisan
|
|
|
|
- Futtasd az Artisan parancsokat közvetlenül a parancssorból (pl. `php artisan route:list`). Használd a `php artisan list` parancsot az elérhető parancsok felfedezéséhez, és a `php artisan [command] --help` parancsot a paraméterek ellenőrzéséhez.
|
|
- Vizsgáld meg az útvonalakat a `php artisan route:list` paranccsal. Szűrj: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`.
|
|
- Olvass be konfigurációs értékeket pont jelöléssel: `php artisan config:show app.name`, `php artisan config:show database.default`. Vagy olvasd a konfigurációs fájlokat közvetlenül a `config/` könyvtárból.
|
|
- A környezeti változók ellenőrzéséhez olvasd közvetlenül a `.env` fájlt.
|
|
|
|
## Tinker
|
|
|
|
- Futtass PHP kódot az alkalmazás környezetében hibakereséshez és teszteléshez. Ne hozz létre modelleket felhasználói jóváhagyás nélkül, preferáld a factory-kkal ellátott teszteket. Preferáld a meglévő Artisan parancsokat az egyedi tinker kódok helyett.
|
|
- Mindig használj szimpla idézőjeleket a shell kifejtés megakadályozására: `php artisan tinker --execute 'Your::code();'`
|
|
- Használj dupla idézőjelet a PHP stringekhez belül: `php artisan tinker --execute 'User::where("active", true)->count();'`
|
|
|
|
=== php szabályok ===
|
|
|
|
# PHP
|
|
|
|
- Mindig használj kapcsos zárójeleket a vezérlési szerkezeteknél, még az egysoros törzseknél is.
|
|
- Használd a PHP 8 konstruktor property promotion-t: `public function __construct(public GitHub $github) { }`. Ne hagyj üres, nulla paraméteres `__construct()` metódusokat, hacsak a konstruktor nem privát.
|
|
- Használj explicit visszatérési típus deklarációkat és típusjelzéseket minden metódus paraméternél: `function isAccessible(User $user, ?string $path = null): bool`
|
|
- Használj TitleCase-t az Enum kulcsokhoz: `FavoritePerson`, `BestLake`, `Monthly`.
|
|
- Preferáld a PHPDoc blokkokat az inline kommentekkel szemben. Csak kivételesen összetett logika esetén adj hozzá inline kommenteket.
|
|
- Használj array shape típusdefiníciókat a PHPDoc blokkokban.
|
|
|
|
=== laravel/core szabályok ===
|
|
|
|
# Csináld a Laravel Útján
|
|
|
|
- Használd a `php artisan make:` parancsokat új fájlok (pl. migrációk, kontrollerek, modellek stb.) létrehozásához. Az elérhető Artisan parancsokat a `php artisan list` paranccsal listázhatod, és a paramétereiket a `php artisan [command] --help` paranccsal ellenőrizheted.
|
|
- Ha generikus PHP osztályt hozol létre, használd a `php artisan make:class` parancsot.
|
|
- Minden Artisan parancsnak add át a `--no-interaction` jelzőt a felhasználói beavatkozás nélküli működés érdekében. A helyes működéshez a megfelelő `--options` opciókat is meg kell adnod.
|
|
|
|
### Modell létrehozás
|
|
|
|
- Új modellek létrehozásakor készíts hozzájuk hasznos factory-kat és seedereket is. Kérdezz rá a felhasználónál, ha másra is szükség van, a `php artisan make:model --help` segítségével ellenőrizve az elérhető opciókat.
|
|
|
|
## API-k és Eloquent Resource-ok
|
|
|
|
- API-k esetén alapértelmezés szerint használj Eloquent API Resource-okat és API verziózást, hacsak a meglévő API útvonalak nem másképp teszik, ekkor kövesd a meglévő alkalmazáskonvenciót.
|
|
|
|
## URL generálás
|
|
|
|
- Más oldalakra mutató linkek generálásakor preferáld a nevesített útvonalakat és a `route()` függvényt.
|
|
|
|
## Tesztelés
|
|
|
|
- Modellek létrehozásakor a tesztekhez használd a modellek factory-jait. Ellenőrizd, hogy a factory rendelkezik-e egyedi állapotokkal (states), amelyeket használni lehet, mielőtt manuálisan állítanád be a modellt.
|
|
- Faker: Használj olyan metódusokat, mint a `$this->faker->word()` vagy a `fake()->randomDigit()`. Kövesd a meglévő konvenciókat, hogy a `$this->faker`-t vagy a `fake()`-et használd.
|
|
- Tesztek létrehozásakor használd a `php artisan make:test [opciók] {név}` parancsot funkcionális teszt létrehozásához, és add át a `--unit` jelzőt egységteszt készítéséhez. A legtöbb tesztnek funkcionális tesztnek kell lennie.
|
|
|
|
## Vite hiba
|
|
|
|
- Ha "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" hibát kapsz, futtathatod az `npm run build` parancsot, vagy kérd meg a felhasználót, hogy futtassa az `npm run dev` vagy a `composer run dev` parancsot.
|
|
|
|
=== laravel/v12 szabályok ===
|
|
|
|
# Laravel 12
|
|
|
|
- KRITIKUS: MINDIG használd a `search-docs` eszközt a verzióspecifikus Laravel dokumentációhoz és frissített kódpéldákhoz.
|
|
- Ez a projekt a Laravel 10-ről lett frissítve az új, áramvonalasított Laravel fájlstruktúrára való áttérés nélkül.
|
|
- Ez teljesen rendben van és a Laravel által ajánlott. Kövesd a Laravel 10-ből származó meglévő struktúrát. Nem kell áttérnünk az új Laravel struktúrára, hacsak a felhasználó kifejezetten nem kéri.
|
|
|
|
## Laravel 10 struktúra
|
|
|
|
- A middleware-ek jellemzően az `app\Http/Middleware/` mappában, a service providerek pedig az `app\Providers/` mappában találhatók.
|
|
- Nincs `bootstrap/app.php` alkalmazáskonfiguráció a Laravel 10 struktúrában:
|
|
- A middleware regisztráció az `app\Http/Kernel.php` fájlban történik.
|
|
- A kivételkezelés az `app\Exceptions/Handler.php` fájlban található.
|
|
- A konzol parancsok és az ütemezés az `app\Console/Kernel.php` fájlban vannak regisztrálva.
|
|
- A sebességkorlátok (rate limits) valószínűleg a `RouteServiceProvider`-ben vagy az `app\Http/Kernel.php`-ban találhatók.
|
|
|
|
## Adatbázis
|
|
|
|
- Oszlop módosításakor a migrációnak tartalmaznia kell az oszlophoz korábban definiált összes attribútumot. Ellenkező esetben azok elvesznek.
|
|
- A Laravel 12 natívan lehetővé teszi az eager loaded rekordok korlátozását külső csomagok nélkül: `$query->latest()->limit(10);`.
|
|
|
|
### Modellek
|
|
|
|
- A castok beállíthatók és célszerű is beállítani a modell `casts()` metódusában a `$casts` tulajdonság helyett. Kövesd a többi modell meglévő konvencióit.
|
|
|
|
=== livewire/core szabályok ===
|
|
|
|
# Livewire
|
|
|
|
- A Livewire lehetővé teszi dinamikus, reaktív felületek építését PHP-ben, JavaScript írása nélkül.
|
|
- Az Alpine.js-t használhatod kliensoldali interakciókhoz JavaScript keretrendszerek helyett.
|
|
- Tartsd az állapotot a szerver oldalon, hogy a UI azt tükrözze. Validálj és autorizálj az action-ökben, ahogy a HTTP kéréseknél tennéd.
|
|
|
|
=== pest/core szabályok ===
|
|
|
|
## Pest
|
|
|
|
- Ez a projekt a Pest-et használja teszteléshez. Hozz létre teszteket: `php artisan make:test --pest {név}`.
|
|
- Futtasd a teszteket: `php artisan test --compact` vagy szűrj: `php artisan test --compact --filter=tesztNeve`.
|
|
- NE törölj teszteket jóváhagyás nélkül.
|
|
|
|
</laravel-boost-guidelines>
|