Laravel 10’dan Laravel 11’e Geçiş: Adım Adım Rehber

Erhan ÜRGÜNErhan ÜRGÜN
6 min read

Table of contents

Selamlar, bu yazımda sizlerle, Laravel 10’dan Laravel 11’e geçiş sürecimi paylaşmak istiyorum. Bu yazıyı hazırlarken Laravel’in resmi yükseltme dökümanını (https://laravel.com/docs/11.x/upgrade) detaylıca inceledim ve kendi projelerimde uyguladığım adımları not aldım… Artık 24 Şubat’ta Laravel v12 çıkıyor; ancak ben hâlâ birçok projemi Laravel v10 ile çalıştırıyordum. İşte bu durum, bu yükseltme sürecine başlamam için son nokta oldu. Artık artık eski sürümlere veda etme zamanı!

1. Ortam Hazırlığı ve Bağımlılık Güncellemeleri

Laravel 11’e geçişte ilk adım, ortamımızı güncel hale getirmek oldu. Öncelikle, sunucumda ve yerel geliştirme ortamımda PHP sürümünü kontrol ettim; çünkü Laravel 11 için minimum PHP 8.2 gerekliliğini yerine getirmem gerekiyordu. Aynı şekilde, curl sürümümü de 7.34 veya üzeri olacak şekilde güncelledim.

Composer bağımlılıklarına gelince, projemdeki composer.json dosyasını açıp, Laravel framework’ünü ^11.0 sürümüne ve nunomaduro/collision paketini ^8.1 sürümüne güncelledim. Benim projemde ayrıca Laravel Breeze, Cashier, Dusk, Jetstream, Octane, Passport, Sanctum, Scout, Spark Stripe, Telescope, Livewire ve InertiaJS gibi ek paketlerden de bazıları vardı. Bu paketleri de uyumlu sürümlere çekmek gerekiyordu. Resmi dokümandan yola çıkarak, şöyle bir güncelleme yaptım:

composer require laravel/framework:^11.0
composer require nunomaduro/collision:^8.1

Ayrıca, Cashier Stripe, Passport, Sanctum, Spark Stripe ve Telescope gibi paketlerin artık migration’larını otomatik yüklemediğini fark ettim. Bu yüzden vendor publish komutlarını kullanarak migration dosyalarını projeme aktardım:

php artisan vendor:publish --tag=passport-migrations
php artisan vendor:publish --tag=spark-migrations
php artisan vendor:publish --tag=telescope-migrations

Global Laravel installer’ımı da güncellemem gerekiyordu (yeni projeler için):

# Resmi dokümanda önerilen
composer global require laravel/installer:^5.6

# Benim önerim son sürümü kullanmanız yönünde
composer global require laravel/installer:^*

2. Uygulama Yapısındaki Değişiklikler

Laravel 11, yeni projelerde varsayılan olarak daha sade bir uygulama yapısı sunuyor; daha az sayıda servis sağlayıcı, middleware ve konfigürasyon dosyası bulunuyor. Yine de, mevcut Laravel 10 projemi yeniden yapılandırmaya (tüm yapıyı v11’e benzetmeye) çalışmadan, Laravel 11’e geçiş yapabildiğimi görmek beni gerçekten rahatlattı. Çünkü bu yükseltme sürecinde, resmi dökümandan edindiğim bilgiler ışığında, eski yapıyı korurken yeni özellikleri de projeme dahil edebiliyordum.

3. Kimlik Doğrulama (Authentication) Yenilikleri

Laravel 11, kullanıcı parolalarını otomatik olarak yeniden hash’leyebiliyor; yani hash algoritmamın “work factor”’ı güncellendiğinde, kullanıcı parolalarının yeniden oluşturulması sağlanıyor. Ancak, projemizde parolanın saklandığı sütun adı password dışında bir isimdeyse, modelime şu şekilde bir özellik eklememiz gerektiğini öğrendim:

protected $authPasswordName = 'custom_password_field';

Tabii, eğer bu davranışı kapatmak isterseniz config/hashing.php dosyasında:

'rehash_on_login' => false,

şeklinde ayarlamayı da unutmamanız gerekiyor. Ayrıca, UserProvider ve Authenticatable sözleşmelerine eklenen yeni metotları (örneğin, rehashPasswordIfRequired ve getAuthPasswordName) kendi implementasyonlarıma ekleyerek, süreci tamamladım. Böylece, kimlik doğrulama ile ilgili hiçbir aksaklık yaşamadım.

4. Veritabanı Güncellemeleri

Veritabanı tarafında da pek çok ince detay dikkatimi çekti. Projemde, örneğin members tablosunda oluşturduğum points sütununu ilk etapta şöyle tanımlamıştım:

Schema::create('members', function (Blueprint $table) {
    $table->integer('points')->unsigned()->default(10)->comment('Üyelerin puanları');
});

Daha sonra bu sütunu nullable yapmak istediğimde, Laravel 10’da önceki özellikler otomatik korunurken, Laravel 11’de tüm özellikleri yeniden belirtmem gerekti. Ben de şu şekilde bir güncelleme yaptım:

Schema::table('members', function (Blueprint $table) {
    $table->integer('points')
          ->unsigned()
          ->default(10)
          ->comment('Üyelerin puanları (opsiyonel)')
          ->nullable()
          ->change();
});

Değiştirme change yöntemi sütunun dizinlerini değiştirmez. Bu nedenle, sütunu değiştirirken bir dizini açıkça eklemek veya bırakmak için dizin değiştiricileri kullanabilirsiniz:

// Bir dizin ekleyin...
$table->uuid('id')->primary()->change();

// Bir dizin kaldırın...
$table->char('postal_code', 10)->unique(false)->change();

Bu arada, eğer migration’larınızı güncellemekte zorlanıyorsanız, migration’ları squash edip tek bir schema dosyası oluşturmak da iyi bir yöntem. Ben bu yöntemi tercih ettim:

php artisan schema:dump

Ayrıca, floating-point türlerinde de küçük değişiklikler vardı. Double ve float sütunlarını artık farklı şekilde tanımlamak gerekiyor. Örneğin:

$table->double('price_value');
$table->float('price_value', precision: 66);

5. Doctrine DBAL’ın Kaldırılması

Laravel 11, artık Doctrine DBAL’a bağlı değil. Ben de projemde önceden eklediğim doctrine/dbal paketini kaldırarak, Laravel’in native schema metotlarını kullanmaya başladım. Artık:

Schema::getTables();
Schema::getViews();

gibi metotlar ile işlerimi hallediyorum. Bu benim için fazlasıyla temiz ve hızlı bir geçiş sağladı.

6. Tarih İşlemleri ve Carbon 3

Laravel’in tarih işlemlerinde Carbon 3 desteği, önemli yenilikler getiriyor. Carbon 3 ile diffIn* metotları artık ondalıklı sayı döndürebiliyor ve negatif değerler verebiliyor. Bu değişiklikleri kendi kodlarıma entegre ederken, Carbon’un changelog ve dokümantasyonunu dikkatlice inceledim. Böylece, tarih hesaplamalarında hiçbir aksaklık yaşamadan projemi güncelledim.

7. Mail ve Diğer Küçük Güncellemeler

Illuminate\Contracts\Mail\Mailer sözleşmesi yeni bir sendNow yöntemi eklendi. Uygulamanız veya paketiniz bu sözleşmeyi manuel olarak uyguluyorsa, uygulamanıza yeni sendNow yöntemini eklemelisiniz:

public function sendNow($mailable, array $data = [], $callback = null);

Ayrıca, servis sağlayıcılar artık config/app.php yerine yeni bootstrap/providers.php dosyasında yönetiliyor. Kendi paketlerimi geliştirirken, servis sağlayıcımı eklemek için şu metodu kullandım:

use Illuminate\Support\ServiceProvider;
ServiceProvider::addProviderToBootstrapFile(MyCustomProvider::class);

Eski yapı ile yenisi arasında da farklılıklar, değişiklikler bulunmakta… Örneğin:

// Eski: bootstrap/app.php (v10.x)
$app = new Illuminate\Foundation\Application(
    $_ENV['APP_BASE_PATH'] ?? dirname(__DIR__)
);

$app->singleton(
    Illuminate\Contracts\Http\Kernel::class,
    App\Http\Kernel::class
);

$app->singleton(
    Illuminate\Contracts\Console\Kernel::class,
    App\Console\Kernel::class
);

$app->singleton(
    Illuminate\Contracts\Debug\ExceptionHandler::class,
    App\Exceptions\Handler::class
);

return $app;

---

// Yeni: bootstrap/app.php (v11.x)
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

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();


// bootstrap/providers.php (v11.x)
return [
    App\Providers\AppServiceProvider::class,
    // App\Providers\CustomServiceProvider::class,
    // ...
];
  • Bu, değişen dosyalardan sadece birkaçı... Ayrıca, .env ve artisan gibi dosyaların içeriğinin v11'e uygun olduğundan ve app/Http/Kernel.php dosyasının silindiğinden emin olmanız da fayda var... Daha fazla bilgi için resmi dokümana göz atın!

8. Kuyruklar, Rate Limiting ve Paket Güncellemeleri

Laravel 11, kuyruk işlemlerinde “after commit” davranışını daha doğru şekilde uyguluyor ve rate limiting’i saniye bazında yapabiliyor. Projemde bu alanlarda da bazı ayarlamalar yapmam gerekti… Ayrıca, Cashier Stripe, Spark Stripe, Passport, Sanctum ve Telescope gibi paketlerin artık eski sürümleri desteklenmiyor. Ben de sırasıyla:

  • Cashier Stripe: ^15.0

  • Spark Stripe: ^5.0

  • Passport: ^12.0 (Ayrıca, password grant tipi için AppServiceProvider’ımda Passport::enablePasswordGrant(); çağırdım.)

  • Sanctum: ^4.0

  • Telescope: ^5.0

gibi güncellemeleri yaparak, her paketin migration dosyalarını vendor publish komutları ile projeme ekledim…

Ayrıca, bütün işlemler sonunda composer’ı dump etmeyi, cache’i temizlemeyi ve migrate’i fresh’lemeyi unutmayın!

composer dump-autoload ; php artisan optimize:clear ; php artisan migrate:fresh

BONUS: Laravel Shift’in "Can I Upgrade Laravel Yet?" Aracı

Upgrade sürecinde en büyük korkulardan biri, bağımlılık karmaşası’na girmekti. İşte tam bu noktada, Laravel Shift’in Can I Upgrade Laravel Yet? aracını keşfettim. Bu araç sayesinde, projemdeki tüm bağımlılıkların en güncel Laravel sürümüyle uyumlu olup olmadığını hızlıca kontrol edebildim. Packagist’teki paket isimlerini analiz eden bu araç, hangi paketlerin yeni sürümle uyumlu olduğunu bana bildiriyor. Böylece, hangi alanlarda ekstra dikkat etmem gerektiğini önceden öğrenmiş oldum. Bu bonus özellik, benim upgrade sürecimde adeta bir rehber görevi gördü… composer.json dosyamdaki bağımlılıkları buraya yükleyerek (json formatında require ve require-dev’i) desteklenenleri geliştirme sürecinden önce ss’te gördüğünüz üzere anında görebildim:

Yani Özetle

24 Şubat’ta Laravel v12 çıkacak (bu konu hakkındaki yazım için buraya tıkla). Bu fırsatı değerlendirerek artık projelerimi Laravel 10’da bırakmamaya karar verdim. Laravel 11’e geçiş sürecimde, resmi dokümana bağlı kalarak adım adım ilerledim ve kodlarımı titizlikle güncelledim.

Laravel 12’ye yükseltmeden önce, eğer elimizde daha eski bir Laravel sürümü (örneğin Laravel 9) varsa, doğrudan en son sürüme geçmek yerine, önce Laravel 10’a, ardından Laravel 11’e ve son olarak Laravel 12’ye yükseltmek daha sağlıklı bir yöntem, aksi durumda proje yüksek ihtimalle elinizde patlayacaktır!

Bu yazıda, ortam ve bağımlılık güncellemelerinden veritabanı migration’larına, kimlik doğrulama yeniliklerinden kuyruk ve rate limiting ayarlarına kadar birçok detayı, kendi deneyimlerimle harmanlayarak paylaşamaya çalıştım...

Eğer siz de Laravel 10’dan Laravel 11’e geçiş yapmayı düşünüyorsanız, adımları dikkatlice uygulamanızı ve her adımda test ederek ilerlemenizi tavsiye ediyorum. Laravel Shift gibi araçlardan yararlanmak, süreçte karşılaşabileceğiniz sorunları önceden görmenize yardımcı olabilir. Daha fazlası için Laravel’in resmi dökümanına buraya tıklayarak bi göz atabilirsiniz… Umarım bu yazı, sizin için de faydalı olur :)

Yazımı beğendiyseniz paylaşmayı ve düşüncelerinizi yorumlarda belirtmeyi unutmayın! Ayrıca; eksik, hatalı veya yanlış bir bilgi olması halinde yorumlarda (mümkünse bilginin kaynağıyla beraber) belirttiğiniz takdirde ilgili düzenlemeyi yaparım...

Bunun gibi daha fazla paylaşım için takipte kalın:

0
Subscribe to my newsletter

Read articles from Erhan ÜRGÜN directly inside your inbox. Subscribe to the newsletter, and don't miss out.

laravel upgradeLaravelLaravel 10laravel 11upgradePHP

Written by

Erhan ÜRGÜN
Erhan ÜRGÜN

Laravel | AdonisJS | Back-End Developer