Тема
Сверка спеков с Laravel 12.x — что валидно и подходит
Проверено против официальной документации laravel.com/docs/12.x и API-референса api.laravel.com/docs/12.x (через context7, источник
/websites/laravel_12_x). Дата сверки: 2026-07-10. Вывод: все 13 файлов спеков корректны для Laravel 12, расхождений с версией не найдено. Ниже — пофайловая привязка утверждений к докам L12.
models.md — Eloquent Models
| Утверждение спеки | Раздел доки L12 | API-референс |
|---|---|---|
$casts / касты обязательны на JSON/date/bool/enum | eloquent-mutators#attribute-casting | Model::casts() |
Attribute cast вместо getXxxAttribute() | eloquent-mutators#accessors-and-mutators | Casts\Attribute |
Обе стороны связей hasMany ↔ belongsTo, belongsToMany | eloquent-relationships | HasMany · BelongsToMany |
->with() явно, запрет $with в модели, N+1 = баг | eloquent-relationships#eager-loading | Builder::with() |
withCount() для подсчёта без загрузки | eloquent-relationships#counting-related-models | Builder::withCount() |
Scopes (scopeActive, scopePublished) | eloquent#query-scopes | — |
$fillable whitelist / $guarded | eloquent#mass-assignment | Model::$fillable |
| Soft Deletes только по бизнес-требованию | eloquent#soft-deleting | SoftDeletes |
Примечание (не ошибка): в L11/L12 официально рекомендуемый способ объявления кастов — метод protected function casts(): array (не свойство $casts). Свойство $casts по-прежнему работает и не deprecated. Спека валидна; при желании можно упомянуть метод.
controllers.md — Controllers, Routing, Middleware, Validation
| Утверждение спеки | Раздел доки L12 | API-референс |
|---|---|---|
Route Model Binding по slug ({product:slug}) | routing#implicit-binding | Route::get() |
scopeBindings() для вложенных моделей | routing#implicitly-scoping-bindings | Route::scopeBindings() |
Каждый роут через ->name() | routing#named-routes | Route::name() |
| 301 permanent redirect при смене URL | routing#redirect-routes | Router::permanentRedirect() |
| Fallback-роут для 404 | routing#fallback-routes | Route::fallback() |
FormRequest: authorize(), messages(), $redirectRoute | validation#form-request-validation | FormRequest |
unique:table,column с ignoreRecord/ignore | validation#rule-unique | Rule::unique() |
Middleware в bootstrap/app.php через ->withMiddleware() | middleware#registering-middleware | Configuration\Middleware |
throttle:X,Y rate limiting на POST | routing#rate-limiting | RateLimiter |
| API Resources для трансформации в JSON | eloquent-resources | JsonResource |
migrations.md — Migrations & Seeders
| Утверждение спеки | Раздел доки L12 | API-референс |
|---|---|---|
->constrained() + ->index() на FK | migrations#foreign-key-constraints | ForeignIdColumnDefinition::constrained() |
cascadeOnDelete() / nullOnDelete() / restrictOnDelete() | migrations#foreign-key-constraints | Blueprint |
->json('column')->nullable() | migrations#column-method-json | Blueprint::json() |
$table->enum('status', [...]) | migrations#available-column-types | Blueprint::enum() |
Composite index index(['a', 'b']), unique(), fullText() | migrations#creating-indexes | Blueprint::index() · Blueprint::fullText() |
down() обязателен, dropIfExists | migrations#migration-structure | Schema::dropIfExists() |
Seeders firstOrCreate / updateOrCreate (идемпотентность) | seeding | Model::updateOrCreate() |
Примечание: PostgreSQL-специфика (partial/GIN/covering-индексы через DB::statement, CREATE INDEX CONCURRENTLY, $withinTransaction = false) — не часть Laravel API, а прямой SQL. Валидно и не конфликтует с L12. $withinTransaction — свойство класса миграции, migrations#running-migrations.
relations.md — Smart Relations (pivot)
Проектная конвенция поверх стандартного belongsToMany. Всё соответствует L12:
- eloquent-relationships#many-to-many
- Дополнительные pivot-колонки (
is_primary,sort_order) → withPivot() has('services')фильтр по наличию связи → querying-relationship-existenceinsertOrIgnore()в сидерах → Query Builder::insertOrIgnore()
services.md — Services, Jobs, Events, Notifications
| Утверждение спеки | Раздел доки L12 | API-референс |
|---|---|---|
| DI через конструктор, auto-wiring | container#automatic-injection | Container |
Интерфейс → реализация bind, singleton | container#binding | Application::singleton() |
DB::transaction() для атомарности | database#database-transactions | DB::transaction() |
Job: $tries, $backoff, failed() | queues#max-job-attempts-and-timeout · queues#dealing-with-failed-jobs | InteractsWithQueue |
SerializesModels — передавать модель/ID | queues#handling-relationships | SerializesModels |
Events — DTO, Listener → Service, ShouldQueue | events | ShouldQueue |
Notifications: каналы mail/database/custom, via(), queue | notifications | Notification |
blade.md — Blade Templates
| Утверждение спеки | Раздел доки L12 | API-референс |
|---|---|---|
{!! !!} — доверенный HTML | blade#displaying-data | — |
@js($var) / @ для JS | blade#the-at-symbol | — |
| Anonymous vs class-based компоненты | blade#components | Component |
@props с типизацией и default | blade#data-properties-attributes | — |
@stack / @push для скриптов | blade#stacks | — |
@forelse / @empty | blade#loops | — |
@vite() для ассетов | vite#loading-your-scripts-and-styles | Vite::__invoke() |
@auth / @guest / @isset / @env | blade#authentication-directives | — |
filament.md — FilamentPHP Admin
Не часть Laravel core. Синтаксис в спеке — Filament 3 (
Section,Toggle,SpatieMediaLibraryFileUpload,TextColumn::make('relation.name'),SelectFilter,TernaryFilter). Filament 3 совместим с Laravel 12 — валидно. Уже вышли Filament 4 и 5 (иной синтаксис схем форм), но спека не привязана к номеру версии явно, что корректно.
- Docs: filamentphp.com/docs/3.x
afterSave()в CreateRecord/EditRecord +Cache::tags()->flush()— валидно, см. cache ниже.
testing.md — Testing
| Утверждение спеки | Раздел доки L12 | API-референс |
|---|---|---|
| Pest по умолчанию (L11+), PHPUnit валиден | testing | — |
RefreshDatabase только на _test БД | database-testing#resetting-the-database-after-each-test | RefreshDatabase |
Feature: HTTP-ассерты, статусы, $this->seed() | http-tests | TestResponse |
Mail::fake(), Queue::fake() | mocking#mail-fake · mocking#queue-fake | Mail::fake() |
--parallel | testing#running-tests-in-parallel | — |
seo.md — SEO
Проектная система (seo_blocks, шаблоны, Schema.org). Laravel-механики:
- Sitemap:
spatie/laravel-sitemap(пакет) — github.com/spatie/laravel-sitemap - Artisan-команда
sitemap:generate→ artisan#writing-commands - Всё остальное (meta, JSON-LD, robots.txt, canonical) — HTML/HTTP, вне версии Laravel.
docker.md — Docker
Инфраструктура, не Laravel API. Соответствует рекомендациям L12:
- Драйверы
CACHE_STORE=redis(в L11+ переименован изCACHE_DRIVER),SESSION_DRIVER,QUEUE_CONNECTION→ cache#configuration · session#configuration queue:work,schedule:work→ queues#running-the-queue-worker · scheduling#running-the-scheduler-locally- opcache preloading,
.env/config()→ configuration
⚠️ Единственная возможная неточность в docker.md — переменная кеша. В
.envтаблице (docker.md:66-69) указанCACHE_DRIVER. В L11/L12 ключ по умолчанию —CACHE_STORE(CACHE_DRIVERостаётся как fallback, но новое имя —CACHE_STORE).
mcp.md, anti-hardcode.md, code-quality.md
Внутренние конвенции студии и правила выбора MCP-инструментов — вне Laravel API. Laravel-механики, которые они упоминают, валидны для L12:
config()вместоenv()в коде → configuration#accessing-configuration-values- PHP Enum + cast → eloquent-mutators#enum-casting
__()/trans()локализация → localizationCache::tags()->flush()(только Redis/Memcached) → cache#cache-tags · Repository::tags()throw_if()/throw_unless()→ helpers#method-throw-ifchunk()/lazy()для больших выборок → eloquent#chunking-resultsdeclare(strict_types=1), constructor property promotion — PHP 8.2+ (требование L12), не Laravel-специфично.
Итог
| Файл | Вердикт для L12 | Замечания |
|---|---|---|
| models.md | ✅ Валиден | опц.: метод casts() вместо $casts |
| controllers.md | ✅ Валиден | — |
| migrations.md | ✅ Валиден | PG-специфика — сырой SQL, ок |
| relations.md | ✅ Валиден | — |
| services.md | ✅ Валиден | — |
| blade.md | ✅ Валиден | — |
| filament.md | ✅ Валиден | Filament 3 (совместим с L12) |
| testing.md | ✅ Валиден | — |
| seo.md | ✅ Валиден | вне версии Laravel |
| docker.md | ⚠️ Почти | CACHE_DRIVER → CACHE_STORE (L11+) |
| mcp.md | ✅ Валиден | вне версии Laravel |
| anti-hardcode.md | ✅ Валиден | — |
| code-quality.md | ✅ Валиден | — |
Требования окружения L12: PHP 8.2+, поддержка до PHP 8.4. Официальные release notes: laravel.com/docs/12.x/releases.