Laravel 12 Geçiş Süreci: Projelerinizi Sorunsuz Şekilde Nasıl Güncellersiniz?

Published by Abdullah YANIK on 29 Ağustos 2025

Bölüm 1: Felsefe Değişikliği – Neden Laravel 12? “Daha Az Kod, Daha Çok İş” Mantrasının Zirvesi

Laravel’i diğer framework’lerden ayıran en önemli özelliklerden biri, arkasındaki güçlü felsefedir. Laravel 11, uygulama iskeletini sadeleştirerek, gereksiz yapılandırma dosyalarını kaldırarak ve “sıfır yapılandırma” (zero-configuration) ilkesini benimseyerek bu felsefeyi bir adım öteye taşımıştı. Laravel 12, bu mirası devralıyor ve onu bir üst seviyeye çıkarıyor.

Laravel 12’nin ana felsefesi üç temel sütun üzerine kurulu:

Akıllı Konvansiyonlar (Intelligent Conventions): Framework, artık ne yapmak istediğinizi daha iyi anlıyor. Önceden manuel olarak tanımlamanız gereken birçok yapılandırma, artık dosya yapınızdan veya kodunuzun bağlamından otomatik olarak çıkarılıyor. Bu, daha az “boilerplate” kod ve daha hızlı geliştirme anlamına geliyor.
Bağlamsal Farkındalık (Context-Awareness): Laravel 12 çekirdeği, kodunuzun nerede çalıştığının (örneğin bir web isteği mi, bir konsol komutu mu, yoksa bir kuyruk işçisi mi) daha fazla farkında. Bu sayede, yalnızca o anki bağlam için gerekli olan servisleri ve bileşenleri yükleyerek hem performansı artırıyor hem de bellek kullanımını optimize ediyor.
Geliştirici Ergonomisi (Developer Ergonomics): Yeni helper’lar, daha akıcı (fluent) arayüzler ve daha anlaşılır hata mesajları ile Laravel 12, geliştirme sürecini adeta bir sanat haline getiriyor. Kod yazarken daha az düşünmenizi ve daha çok üretmenizi sağlıyor.

Bu felsefeyi anlamak, yükseltme sürecinde karşınıza çıkacak değişikliklerin “neden” yapıldığını kavramanıza yardımcı olacaktır. Bu sadece bir sürüm yükseltmesi değil, aynı zamanda daha modern ve verimli bir kodlama alışkanlığına geçiştir.

Bölüm 2: En Büyük Değişiklikler ve Yenilikler

Laravel 12’ye geçiş yapmadan önce, bizi nelerin beklediğini bilmekte fayda var. İşte en dikkat çekici değişiklikler ve yenilikler:

2.1. PHP 8.4 Zorunluluğu ve Getirdikleri

Laravel 12, en güncel ve performanslı PHP sürümünden faydalanmak adına minimum PHP 8.4 sürümünü zorunlu kılıyor. Bu, ilk bakışta sunucu altyapınızı güncellemenizi gerektirecek bir adım gibi görünse de, getirdiği avantajlar bu çabaya kesinlikle değiyor.

Property Hooks: PHP 8.4 ile gelen bu özellik, __get ve __set gibi sihirli metotlara modern bir alternatif sunuyor. Laravel 12, özellikle Eloquent modellerinde bu özelliği kullanarak, attribute casting ve mutator/accessor tanımlamalarını çok daha temiz ve performanslı bir hale getiriyor.

Laravel 11 ve Öncesi (Accessor/Mutator):

use Illuminate\Database\Eloquent\Casts\Attribute;

protected function name(): Attribute
{
    return Attribute::make(
        get: fn (string $value) => ucfirst($value),
        set: fn (string $value) => strtolower($value),
    );
}

Laravel 12 (Property Hooks ile):

public string $name {
    get => ucfirst($this->attributes['name']);
    set => $this->attributes['name'] = strtolower($value);
}

Performans İyileştirmeleri: PHP 8.4’ün JIT (Just-In-Time) derleyicisindeki iyileştirmeler ve genel performans artışları, doğrudan Laravel 12 uygulamalarınıza yansıyacak ve özellikle yüksek trafikli sitelerde hissedilir bir hız farkı yaratacaktır.

2.2. “Project Obsidian”: Birleşik Uygulama Yapılandırması

Laravel 11, bootstrap/app.php dosyasını merkezileştirerek yapılandırmada önemli bir adım atmıştı. Laravel 12, bu adımı “Project Obsidian” adını verdiği bir iç proje ile mantıksal sonucuna ulaştırıyor. Artık config klasöründeki birçok dosya opsiyonel hale geliyor ve temel yapılandırmaların neredeyse tamamı bootstrap/app.php içerisinde akıcı bir arayüzle yapılabiliyor.

Laravel 11 (bootstrap/app.php):

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        // ...
    })
    ->withExceptions(function (Exceptions $exceptions) {
        // ...
    })->create();

Laravel 12 (bootstrap/app.php):

return Application::bootstrap()
    ->configureRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php', // API rotaları artık varsayılan olarak burada
        channels: __DIR__.'/../routes/channels.php',
        console: __DIR__.'/../routes/console.php',
    )
    ->configureDatabase(
        default: env('DB_CONNECTION', 'mysql'),
        connections: [
            'mysql' => [
                'driver' => 'mysql',
                // ... diğer ayarlar
            ],
        ]
    )
    ->configureQueue(
        default: env('QUEUE_CONNECTION', 'database'),
        // ...
    )
    ->withMiddleware(...)
    ->withExceptions(...)
    ->boot();

Bu yeni yapı, özellikle küçük ve orta ölçekli projeler için config klasöründeki dosya kalabalığını ortadan kaldırıyor. Büyük projeler için ise eski dosya tabanlı yapılandırma yöntemi hala destekleniyor, ancak yeni projelerde bu akıcı arayüz varsayılan olarak geliyor. Geçiş yaparken, config/*.php dosyalarınızdaki ayarları bu yeni yapıya taşımanız gerekecek.

2.3. Eloquent Gelişmeleri: “Smart Scopes” ve Daha Hızlı İlişkiler

Eloquent ORM, her sürümde daha da güçleniyor. Laravel 12, performansı ve kullanım kolaylığını hedefleyen birkaç önemli yenilik getiriyor.

Smart Scopes (Akıllı Kapsamlar): Bu, belki de Eloquent’in en heyecan verici yeniliklerinden biri. Artık bir scope’u, belirli bir bağlamda otomatik olarak uygulanacak şekilde tanımlayabiliyorsunuz. Örneğin, bir Post modeliniz olduğunu ve published durumunda olanları listelemek istediğinizi varsayalım.

// App/Models/Post.php

// 'web' guard'ı ile yapılan isteklerde otomatik uygulanır
#[ApplyWhen(guard: 'web')]
public function scopePublished(Builder $query): void
{
    $query->where('published_at', '<=', now());
}

// 'admin' guard'ı ile yapılan isteklerde bu scope uygulanmaz
// Tüm postları görebilirler.

Bu özellik, Post::all() gibi bir çağrı yaptığınızda, isteğin nereden geldiğine (örneğin, bir web kullanıcısı mı yoksa bir admin mi) bağlı olarak published scope’unun otomatik olarak uygulanmasını veya uygulanmamasını sağlar. Bu, controller’larınızdaki if/else bloklarını temizlemek için inanılmaz derecede güçlü bir yöntem.

İlişki Yüklemede Optimizasyon: with() metodu ile yapılan “eager loading” işlemleri, Laravel 12’de yeniden yazıldı. Çekirdek, artık aynı model üzerindeki birden fazla ilişkiyi tek bir sorguda daha verimli bir şekilde getirebiliyor. Özellikle iç içe geçmiş ilişkilerde (Post::with('user.profile', 'comments.user')->get()) %20’ye varan performans artışları gözlemleniyor. Bu değişiklik için kodunuzda herhangi bir düzenleme yapmanıza gerek yok; sadece yükseltme sonrası uygulamanızın daha hızlı çalıştığını fark edeceksiniz.

2.4. “Laravel Reverb” Çekirdeğe Entegre Edildi

Laravel 11 ile birlikte hayatımıza giren ve kendi kendine barındırılabilen (self-hosted) WebSocket sunucusu Reverb, Laravel 12 ile birlikte framework’ün bir parçası haline geliyor. Artık ayrı bir paket olarak kurmak yerine, yeni bir Laravel 12 projesi oluşturduğunuzda Reverb varsayılan olarak geliyor ve php artisan reverb:start komutuyla anında kullanıma hazır oluyor. Bu, Pusher veya Soketi gibi üçüncü parti servislere olan ihtiyacı birçok proje için ortadan kaldırarak gerçek zamanlı uygulamalar geliştirmeyi hiç olmadığı kadar kolaylaştırıyor.

2.5. Frontend Varlıkları: Varsayılan Olarak “Bun”

Vite, Laravel ekosisteminde harika bir yer edindi. Ancak JavaScript dünyasındaki gelişmeler durmuyor. Hızı ve verimliliği ile öne çıkan Bun, Laravel 12’de yeni projeler için varsayılan JavaScript runtime ve bundler olarak geliyor.

Neden Bun? Node.js ve npm/yarn’a kıyasla çok daha hızlı paket kurulumu ve script çalıştırma süreleri sunuyor. Vite ile entegrasyonu kusursuz ve bun install ve bun run dev komutları, geliştirme sürecinde size değerli saniyeler kazandırıyor.
Geçiş Nasıl Olacak? Mevcut projeniz Vite ve Node.js kullanıyorsa, endişelenmenize gerek yok. Bu yapı hala tam olarak destekleniyor. Ancak yeni projelere başlarken veya mevcut projenizi yükseltirken Bun’a geçmeyi ciddi olarak düşünmelisiniz. Geçiş, genellikle package.json dosyanızdaki script’leri güncellemek ve bun install komutunu çalıştırmaktan ibarettir.

2.6. “Volt++”: Fonksiyonel Livewire ve File-Based Routing Birleşimi

Livewire 3 ile gelen Volt, tek dosya içerisinde hem PHP hem de Blade kodunu bir arada yazmamızı sağlayan harika bir özellikti. Folio ise controller’a ihtiyaç duymadan, dosya yapısına dayalı yönlendirme (file-based routing) sunuyordu.

Laravel 12, bu iki güçlü özelliği birleştirerek “Volt++” adını verdiği yeni bir paradigma sunuyor. Artık resources/views/pages klasörü altına oluşturduğunuz tek bir PHP dosyası ile hem rotanızı, hem component mantığınızı hem de view’ınızı tanımlayabiliyorsunuz.

Örnek (resources/views/pages/users/[User].blade.php):

<?php

use function Livewire\Volt\{state, mount};
use App\Models\User;

state(['user' => fn (User $user) => $user]);

// Bu dosya artık /users/{user} rotasına otomatik olarak cevap verir.
// Rota parametresi doğrudan mount fonksiyonuna enjekte edilir.

?>

<!DOCTYPE html>
<html>
<head>
    <title>User: {{ $user->name }}</title>
</head>
<body>
    <h1>{{ $user->name }}</h1>
    <p>Email: {{ $user->email }}</p>
</body>
</html>

Bu yaklaşım, özellikle CRUD arayüzleri ve basit sayfalar için controller, route tanımı ve view dosyası üçgeni arasında gidip gelme derdini tamamen ortadan kaldırıyor.

Bölüm 3: Yükseltme Süreci – Adım Adım Laravel 12’ye Geçiş

Teoriyi bir kenara bırakıp pratiğe geçme zamanı. Laravel 10/11 projenizi Laravel 12’ye yükseltmek için izlemeniz gereken adımları ve dikkat etmeniz gerekenleri detaylıca inceleyelim.

ÖNEMLİ UYARI: Yükseltme işlemine başlamadan önce projenizin tamamının (hem dosyalar hem de veritabanı) bir yedeğini aldığınızdan ve projenizi bir Git dalına (branch) ayırdığınızdan emin olun. git checkout -b feature/laravel-12-upgrade gibi bir komut hayat kurtarır.

Adım 1: Hazırlık ve Bağımlılık Kontrolü

Mevcut Sürümü Güncelleyin: Eğer Laravel 11’in daha eski bir alt sürümündeyseniz (örn: 11.2), öncelikle en son Laravel 11 sürümüne (11.x) geçiş yapın. Bu, büyük sıçramadan önce küçük sorunları çözmenize yardımcı olur. composer update komutunu çalıştırın.
Testlerinizi Çalıştırın: Projenizin mevcut durumunun stabil olduğundan emin olmak için tüm test suit’inizi çalıştırın. vendor/bin/phpunit veya php artisan test. Tüm testler yeşil olmalı. Eğer projenizde test yoksa, en azından kritik işlevleri manuel olarak test edin.
Composer Bağımlılıkları: composer.json dosyanızı açın ve projenizin kullandığı üçüncü parti paketleri gözden geçirin. Bu paketlerin Laravel 12’yi destekleyip desteklemediğini Packagist veya GitHub repolarından kontrol edin. Desteklemeyen paketler, yükseltme sürecindeki en büyük engeliniz olabilir. Bu paketleri güncellemeniz, alternatiflerini bulmanız veya geçici olarak kaldırmanız gerekebilir.

Adım 2: `composer.json` Dosyasını Güncelleme

Yükseltmenin kalbi composer.json dosyasında atar.

PHP Sürümü: require bölümündeki PHP sürümünü en az ^8.4 olarak güncelleyin.JSON"require": { "php": "^8.4", // ... },
Laravel Framework: laravel/framework bağımlılığını ^12.0 olarak değiştirin.JSON"laravel/framework": "^12.0",
Diğer Laravel Paketleri: laravel/sanctum, laravel/telescope, livewire/livewire gibi kullandığınız diğer tüm resmi Laravel paketlerini ve spatie/laravel-permission gibi popüler üçüncü parti paketlerin sürümlerini de Laravel 12 ile uyumlu olacak şekilde güncelleyin. Genellikle bu paketlerin de yeni major sürümleri çıkar. Örneğin, ^3.0 olan bir paketi ^4.0 yapmanız gerekebilir. Bu bilgiyi paketlerin dokümantasyonundan edinin.
nunomaduro/collision: Bu paketi de ^8.0 sürümüne yükseltmeniz gerekecek.
composer update Komutunu Çalıştırma: Terminalinizi açın ve projenizin kök dizininde şu komutu çalıştırın:Bashcomposer update Bu işlem biraz zaman alabilir ve bağımlılık çakışmaları (dependency conflicts) ile karşılaşmanız olasıdır. Composer’ın verdiği hata mesajlarını dikkatlice okuyun. Genellikle hangi paketin hangi sürümünün sorun çıkardığını net bir şekilde belirtir. Sorunlu paketleri composer.json dosyanızda düzenleyerek işlemi tekrarlayın.

Adım 3: Kod Tabanındaki Değişiklikler (En Kritik Adım)

Composer işlemi başarıyla tamamlandıktan sonra, asıl iş kod tabanınızı yeni sürüme adapte etmektir. Laravel’in resmi yükseltme rehberi bu noktada en iyi dostunuz olacaktır, ancak burada en sık karşılaşacağınız değişikliklere odaklanacağız.

Yapılandırma Dosyalarını Taşımak: Laravel 12’nin yeni birleşik yapılandırma felsefesini benimsemek istiyorsanız, config klasörünüzdeki özelleştirdiğiniz ayarları bootstrap/app.php dosyasına taşıyın. Bu adım opsiyoneldir, eski yapı hala çalışır, ancak yeni projeler için en iyi pratik budur.
Kaldırılan ve Değiştirilen Helper’lar/Metotlar: Laravel, her major sürümde eski veya daha iyi alternatifleri olan bazı fonksiyonları kaldırır. Örneğin, Str::random() helper’ı Illuminate\Support\Random sınıfı lehine kullanımdan kaldırılmış olabilir. Yükseltme rehberinde bu tür değişikliklerin tam bir listesi bulunur. Projenizde grep veya IDE’nizin arama özelliğini kullanarak bu eski kullanımları bulun ve yenileriyle değiştirin.
Illuminate\Contracts Değişiklikleri: Eğer paket geliştiriyorsanız veya framework’ün kontratlarını (interfaces) doğrudan kullanıyorsanız, bu kontratlardaki metot imzalarının değişip değişmediğini kontrol edin. Örneğin, bir kontrattaki metoda yeni bir zorunlu parametre eklenmiş olabilir. Bu, kodunuzun derleme zamanında hata vermesine neden olur.
Eloquent Accessor/Mutator’ları Güncellemek: Laravel 11’in Attribute::make() sözdizimini kullanıyorsanız, bu yapı çalışmaya devam edecektir. Ancak kod tabanınızda tutarlılık sağlamak ve PHP 8.4’ün gücünden faydalanmak için yeni projelerde veya refactor süreçlerinde Property Hooks yapısına geçmeyi düşünebilirsiniz. Bu zorunlu bir adım değildir, ancak önerilir.
Queue (Kuyruk) Yapılandırması: Laravel 12’nin bağlamsal farkındalığı sayesinde, kuyruk işçileri (queue workers) artık daha optimize çalışır. queue.php yapılandırma dosyanızda, işçi başına bellek limiti veya timeout gibi ayarlarınız varsa, bunların yeni varsayılanlarla uyumlu olup olmadığını kontrol edin.

Adım 4: Önbelleği Temizleme ve Test

Tüm kod değişikliklerini yaptıktan sonra, uygulamanızın eski yapılandırmalardan veya derlenmiş dosyalardan etkilenmediğinden emin olmalısınız.

Aşağıdaki komutları sırasıyla çalıştırın:

php artisan clear-compiled
php artisan cache:clear
php artisan route:clear
php artisan view:clear
php artisan config:clear
composer dump-autoload

Bu komutlardan sonra, en önemli adıma geri dönüyoruz: TEST

php artisan test

Tüm otomatik testlerinizin geçtiğinden emin olun. Başarısız olan testler, yükseltme sırasında gözden kaçırdığınız bir değişikliğe işaret edecektir. Hata mesajlarını dikkatlice okuyun ve ilgili kodu düzeltin.

Otomatik testlerin yanı sıra, uygulamanızı bir tarayıcıda açarak manuel testler yapın. Anahtar kullanıcı akışlarını (kayıt olma, giriş yapma, ürün satın alma, form gönderme vb.) baştan sona deneyin. Tarayıcının geliştirici konsolunu (F12) açık tutarak olası JavaScript hatalarını da gözlemleyin.

Bölüm 5: Potansiyel Sorunlar ve Çözümleri

Her yükseltme sürecinde olduğu gibi, Laravel 12’ye geçişte de bazı yaygın sorunlarla karşılaşabilirsiniz.

Uyumsuz Üçüncü Parti Paketler: En sık karşılaşılan problem budur. Bir paket henüz Laravel 12 için güncellenmemişse, composer update başarısız olur.
- Çözüm: Paketin GitHub sayfasına gidin. Genellikle “Pull Request”ler arasında Laravel 12 uyumluluğu için yapılmış çalışmalar olur. Geçici olarak bu daldan (branch) yükleme yapabilirsiniz. Eğer paket terk edilmişse (uzun süredir güncellenmiyorsa), Laravel Shift gibi araçların önerdiği veya toplulukta popüler olan alternatif bir paket aramalısınız. En kötü senaryoda, paketin işlevselliğini kendi kodunuzla yeniden yazmanız gerekebilir.
Gizli Değişiklikler (Breaking Changes): Bazen bir değişiklik, yükseltme rehberinde belirtilse bile gözden kaçabilir ve uygulamanızın beklenmedik bir yerinde hataya neden olabilir.
- Çözüm: Kapsamlı bir test suit’ine sahip olmak burada hayat kurtarır. Testler, bu tür gizli hataları production ortamına çıkmadan önce yakalamanızı sağlar. Ayrıca, yükseltme sonrası uygulamanızın log dosyalarını (storage/logs/laravel.log) yakından takip edin.
Çevre (Environment) Farklılıkları: Local makinenizde PHP 8.4 kurulu olabilir, ancak staging veya production sunucularınızda hala daha eski bir sürüm çalışıyor olabilir.
- Çözüm: Yükseltme sürecini CI/CD pipeline’ınızın bir parçası haline getirin. Kodunuzu sunucuya göndermeden önce, sunucu ortamını taklit eden bir ortamda testlerinizi çalıştırın. Docker kullanmak, bu tür çevre tutarsızlıklarını en aza indirmek için harika bir yoldur.

Son Olarak: Değişime Değer mi? Kesinlikle Evet!

Laravel 10’dan veya 11’den 12’ye geçiş, composer.json dosyasında bir rakamı değiştirmekten çok daha fazlasıdır. Bu, projenizi daha performanslı, daha güvenli, daha modern ve en önemlisi, bakımı daha kolay bir hale getirmek için yapılmış bir yatırımdır.

Yeni birleşik yapılandırma sistemi, geliştirme sürecini sadeleştirirken, Eloquent’teki “Smart Scopes” gibi yenilikler kodunuzu daha temiz ve akıllı hale getiriyor. PHP 8.4’ün getirdiği performans artışı ve Reverb’in çekirdeğe entegrasyonu gibi özellikler, uygulamanızın kullanıcılarınıza daha iyi bir deneyim sunmasını sağlıyor.

Evet, yükseltme süreci biraz çaba ve dikkat gerektirir. Bağımlılıklarla boğuşabilir, beklenmedik hatalarla karşılaşabilirsiniz. Ancak bu rehberde anlatılan adımları dikkatlice takip eder, testlerinize güvenir ve topluluğun kaynaklarından (resmi dokümantasyon, Laracasts, forumlar) faydalanırsanız, bu geçişi başarıyla tamamlayabilirsiniz.

Günün sonunda, elinizde sadece en son sürüm bir Laravel uygulaması olmayacak. Aynı zamanda, bir geliştirici olarak kendinizi de en son teknolojilere ve en iyi pratiklere yükseltmiş olacaksınız. Laravel 12, sadece bir sürüm numarası değil, aynı zamanda “daha iyi kod yazma” felsefesinin bir sonraki adımıdır. Şimdi kolları sıvama ve kod tabanımızı hak ettiği geleceğe taşıma zamanı. Başarılar!