Upgrade ke versi mayor Laravel adalah pekerjaan teknis yang menyentuh banyak lapisan: dependency Composer, kode aplikasi, package pihak ketiga, pipeline CI/CD, database migration, queue worker, cache, sampai prosedur rollback. Pada aplikasi yang sudah aktif dipakai pengguna, target utamanya bukan hanya berhasil upgrade, tetapi juga meminimalkan downtime, mengurangi risiko regresi, dan menjaga jalur rollback tetap aman.

Artikel ini menyusun playbook upgrade ke Laravel 12 untuk tim kecil maupun produk aktif. Fokusnya adalah pendekatan praktis yang bisa diterapkan bertahap, bukan migrasi besar yang memaksa semua perubahan masuk sekaligus.

1. Prinsip dasar upgrade mayor Laravel

Sebelum masuk ke langkah teknis, ada tiga prinsip penting:

  • Upgrade framework adalah perubahan terkontrol, bukan update massal semua package tanpa analisis.
  • Pisahkan perubahan kompatibilitas dari refactor bisnis. Jangan sekaligus mengubah arsitektur, naming, dan fitur baru saat upgrade framework.
  • Rollback harus disiapkan sebelum deploy. Kalau rollback baru dipikirkan setelah error, biasanya sudah terlambat.

Pada banyak kasus, downtime berlebihan bukan disebabkan Composer itu sendiri, melainkan oleh migration yang mengunci tabel terlalu lama, queue worker yang menjalankan kode lama terhadap payload baru, cache yang stale, atau package yang ternyata belum kompatibel.

2. Checklist pra-upgrade

2.1 Inventarisasi versi dan dependency

Mulailah dengan memetakan kondisi aktual proyek:

  • Versi Laravel saat ini
  • Versi PHP pada development, staging, dan production
  • Daftar package Composer utama dan package internal perusahaan
  • Integrasi eksternal: Redis, Horizon, Octane, Sentry, Passport/Sanctum, Scout, Telescope, package admin panel, dan sebagainya
  • Daftar job queue yang kritikal, cron scheduler, dan command operasional

Gunakan perintah berikut untuk audit awal:

composer show -D
composer outdated
php artisan --version
php -v

Kenapa ini penting? Karena upgrade Laravel mayor hampir selalu terkait dengan batasan versi PHP dan kompatibilitas package. Package yang tertinggal sering menjadi sumber hambatan utama.

2.2 Baca upgrade guide resmi dan catat breaking change

Jangan mulai dari trial and error di codebase. Baca upgrade guide resmi Laravel untuk jalur versi Anda ke Laravel 12. Kalau proyek Anda tertinggal beberapa versi mayor, lakukan review bertahap atas tiap lompatan versi, karena breaking change bisa menumpuk.

Saat membaca dokumentasi, buat daftar perubahan yang dikategorikan menjadi:

  • Harus diubah sebelum aplikasi bisa jalan
  • Berpotensi memicu bug perilaku
  • Opsional, tetapi disarankan untuk dirapikan

Contoh item yang biasanya perlu dicek:

  • Perubahan kontrak atau return type pada framework
  • Perubahan perilaku validation, middleware, routing, atau exception handling
  • Perubahan package resmi Laravel yang dipakai aplikasi
  • Perubahan konfigurasi default pada cache, queue, mail, logging, atau filesystem

Kesalahan umum: hanya memperbarui laravel/framework di composer.json tanpa membaca panduan resmi. Akibatnya aplikasi mungkin bisa boot, tetapi perilaku runtime berubah diam-diam.

2.3 Pastikan test suite dan health check layak dipakai

Kalau proyek belum punya pengujian yang memadai, upgrade tetap bisa dilakukan, tetapi risikonya lebih tinggi. Minimal siapkan:

  • Test untuk endpoint kritikal
  • Test login, otorisasi, dan alur pembayaran/transaksi bila ada
  • Smoke test untuk halaman utama, API utama, dan background job penting
  • Health check endpoint untuk deployment verification

Contoh perintah yang sebaiknya sudah masuk ke CI:

php artisan test
php artisan route:list
php artisan config:clear
php artisan cache:clear

2.4 Buat branch strategy yang jelas

Untuk tim kecil, branch strategy sederhana lebih mudah dijaga. Contoh yang cukup aman:

  • main: kode production
  • develop: integrasi harian bila tim memang memakai branch ini
  • upgrade/laravel-12: cabang utama upgrade
  • upgrade/laravel-12-fixes: cabang kecil untuk isu dependency atau refactor kompatibilitas

Kalau tim Anda memakai trunk-based development, cukup gunakan satu branch fitur besar, tetapi lindungi dengan CI wajib dan review ketat.

Saran praktis: selama proses upgrade, hindari menumpuk fitur baru di branch yang sama. Semakin banyak perubahan non-upgrade, semakin sulit membedakan bug framework dengan bug fitur.

3. Audit Composer dan identifikasi dependency bermasalah

3.1 Review composer.json secara eksplisit

Lihat dependency utama satu per satu, terutama package yang mengikat versi Laravel atau komponen Symfony.

{
  "require": {
    "php": "^8.2",
    "laravel/framework": "^12.0",
    "laravel/sanctum": "^4.0",
    "laravel/horizon": "^5.0"
  }
}

Versi di atas hanya contoh pola. Anda harus menyesuaikan dengan requirement resmi Laravel 12 dan kompatibilitas package yang benar pada saat eksekusi upgrade.

Yang perlu diperiksa:

  • Package yang belum merilis dukungan untuk Laravel 12
  • Package yang sudah tidak terawat
  • Package yang bisa diganti dengan fitur native Laravel
  • Package dev tools yang mungkin menghambat resolusi Composer

3.2 Gunakan composer why-not untuk mengetahui blocker

Saat Composer menolak update, jangan langsung menebak-nebak. Pakai:

composer why-not laravel/framework 12.0
composer prohibits laravel/framework 12.0

Perintah ini membantu menemukan package mana yang menahan versi framework.

3.3 Upgrade dependency secara bertahap

Pendekatan yang lebih aman:

  1. Perbarui package pihak ketiga agar kompatibel lebih dulu
  2. Hapus package usang yang tidak diperlukan
  3. Naikkan versi Laravel
  4. Baru setelah itu rapikan config, deprecation, dan refactor minor

Perintah yang sering dipakai:

composer update vendor/package-name --with-all-dependencies
composer update --with-all-dependencies

Trade-off: update seluruh dependency sekaligus bisa lebih cepat, tetapi radius perubahan jauh lebih besar. Untuk produk aktif, lebih aman memperkecil permukaan perubahan.

4. Menangani breaking change di kode aplikasi

4.1 Fokus pada area yang paling sensitif

Area yang paling sering terkena dampak saat upgrade mayor:

  • Custom middleware
  • Exception handler
  • Service provider
  • Auth flow dan policy/gate
  • Validation custom rule
  • Testing utilities
  • Queue job serialization

Lakukan pencarian pada codebase untuk komponen-komponen tersebut dan bandingkan dengan dokumentasi versi baru.

4.2 Jangan buru-buru menyamakan semua skeleton file

Banyak tim langsung menyalin file dari instalasi Laravel baru, misalnya file konfigurasi, bootstrap, atau exception handling. Ini kadang membantu, tetapi juga berbahaya karena bisa menimpa pengaturan lokal yang penting.

Pendekatan yang lebih aman adalah diff terarah:

  • Buat proyek Laravel 12 kosong
  • Bandingkan file konfigurasi dan bootstrap dengan proyek existing
  • Ambil hanya perubahan yang memang relevan

4.3 Uji regresi pada perilaku, bukan hanya status code

Respons 200 bukan berarti aman. Periksa juga:

  • Format JSON tetap sama
  • Header auth/cors tidak berubah tidak sengaja
  • Eager loading dan pagination tetap konsisten
  • Job queue masih diproses dengan benar
  • Email, event, dan notification tetap terpicu sesuai alur

5. Strategi database migration yang aman

Downtime paling sering datang dari migration yang berat. Upgrade framework sendiri jarang mengharuskan perubahan skema besar, tetapi deployment upgrade sering dibarengi cleanup schema. Ini yang harus dikendalikan.

5.1 Gunakan prinsip expand-and-contract

Untuk perubahan skema yang berisiko, hindari migration destruktif langsung. Gunakan pola:

  1. Expand: tambahkan kolom/tabel/index baru yang kompatibel dengan kode lama dan baru
  2. Deploy aplikasi yang bisa membaca/menulis keduanya bila perlu
  3. Backfill data di background
  4. Contract: hapus kolom lama pada rilis terpisah setelah aman

Ini penting untuk produk aktif karena rollback menjadi jauh lebih realistis.

5.2 Hindari migration berat saat jam sibuk

Contoh operasi yang perlu perhatian khusus:

  • Menambah index pada tabel besar
  • Mengubah tipe kolom besar
  • Rename kolom/tabel pada sistem dengan trafik tinggi
  • Backfill jutaan baris dalam satu transaksi panjang

Kalau database mendukung online DDL atau operasi non-blocking, manfaatkan. Kalau tidak, jadwalkan migration berat di maintenance window kecil atau pecah menjadi job bertahap.

5.3 Pisahkan migrate dari deploy aplikasi bila perlu

Pada aplikasi aktif, pendekatan aman biasanya:

  1. Deploy kode yang kompatibel dengan schema lama dan baru
  2. Jalankan migration aman
  3. Aktifkan perilaku baru via feature flag/config

Dengan begitu, kalau migration terlambat atau tertunda, aplikasi masih tetap jalan.

6. Queue worker, scheduler, cache, dan proses background

6.1 Queue worker harus direstart terkontrol

Worker queue adalah proses panjang yang dapat menyimpan kode lama di memori. Setelah deploy Laravel 12, worker harus diminta memuat kode baru.

php artisan queue:restart

Jika menggunakan Supervisor atau systemd, pastikan proses benar-benar respawn. Jika menggunakan Horizon, ikuti prosedur restart yang sesuai dengan deployment Anda.

Masalah umum: job yang dibuat oleh kode baru tetapi diproses worker lama, atau sebaliknya. Ini sering memunculkan error serialisasi, class not found, atau payload tidak cocok.

6.2 Scheduler perlu diverifikasi setelah deploy

Pastikan schedule:run atau mekanisme scheduler lain tetap berjalan normal. Verifikasi command kritikal seperti sinkronisasi data, cleanup, billing, dan notifikasi.

Buat daftar command penting dan lakukan uji manual di staging sebelum rilis.

6.3 Cache harus dikelola hati-hati

Laravel sering menggunakan cache untuk config, route, view, dan data aplikasi. Saat upgrade:

  • Bersihkan cache lama yang bisa menyebabkan perilaku inkonsisten
  • Bangun ulang cache setelah kode baru siap
  • Perhatikan kompatibilitas format cache aplikasi jika struktur object berubah
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

Untuk cache data aplikasi di Redis atau Memcached, gunakan namespace/key versioning jika struktur data berubah. Ini lebih aman daripada menghapus seluruh cache pada sistem yang sibuk.

7. Deployment bertahap untuk meminimalkan downtime

7.1 Gunakan staging yang semirip mungkin dengan production

Jangan hanya menguji di laptop. Staging sebaiknya mendekati production dalam hal:

  • Versi PHP dan ekstensi
  • Driver database, Redis, dan queue
  • Konfigurasi web server/process manager
  • Volume data yang cukup representatif

Kalau memungkinkan, jalankan snapshot data yang sudah dianonimkan untuk menguji migration dan query berat.

7.2 Terapkan deployment bertahap

Untuk produk aktif, deployment yang aman biasanya menggunakan salah satu pola berikut:

  • Rolling deploy: update instance satu per satu
  • Blue-green: siapkan environment baru, lalu alihkan trafik setelah verifikasi
  • Canary: kirim sebagian kecil trafik ke versi baru lebih dulu

Untuk tim kecil, rolling deploy sering paling realistis. Untuk sistem yang sangat kritikal, blue-green memberi rollback tercepat dengan trade-off biaya infrastruktur lebih tinggi.

7.3 Urutan deploy yang disarankan

  1. Freeze merge non-kritis sementara
  2. Deploy ke staging dan jalankan test + smoke test
  3. Tag release dan siapkan catatan perubahan
  4. Backup database dan validasi snapshot
  5. Deploy kode aplikasi
  6. Jalankan migration aman
  7. Refresh cache yang diperlukan
  8. Restart queue worker/Horizon
  9. Verifikasi health check, error log, queue backlog, dan scheduler
  10. Naikkan trafik penuh bila memakai canary/blue-green

8. Teknik rollback yang realistis

Rollback bukan hanya git revert. Pada aplikasi aktif, rollback harus mempertimbangkan kompatibilitas kode, schema, dan job queue.

8.1 Siapkan rollback pada tiga lapisan

  • Kode: kembali ke release sebelumnya
  • Infrastruktur: alihkan trafik ke environment lama jika memakai blue-green
  • Data: hanya rollback migration jika aman dan sudah dianalisis

Migration yang sudah menghapus kolom atau mengubah data secara destruktif sering tidak bisa di-rollback dengan aman pada sistem live. Karena itu, pola expand-and-contract lebih disarankan daripada perubahan destruktif sekali jalan.

8.2 Feature flag lebih aman daripada rollback penuh

Jika perubahan perilaku aplikasi dibungkus feature flag, Anda bisa mematikan fitur baru tanpa harus membatalkan seluruh upgrade framework. Ini sangat membantu ketika inti framework stabil, tetapi ada satu alur bisnis yang bermasalah.

8.3 Langkah saat error terjadi setelah deploy

  1. Hentikan rollout lebih lanjut
  2. Lihat log aplikasi, queue failed jobs, dan metrics error rate
  3. Putuskan apakah masalah bisa diatasi cepat dengan config/flag
  4. Jika tidak, rollback kode atau alihkan trafik ke release sebelumnya
  5. Restart worker agar memuat kode yang sesuai dengan release rollback
  6. Evaluasi apakah data yang ditulis versi baru tetap kompatibel

Tips penting: simpan artefak build dan lock file dari release sebelumnya. Rollback akan jauh lebih cepat jika Anda tidak perlu membangun ulang dari nol.

9. Checklist pasca-upgrade

9.1 Verifikasi teknis

  • Aplikasi berhasil boot tanpa warning fatal
  • Health check lulus
  • Endpoint utama lolos smoke test
  • Queue berjalan normal dan backlog tidak meningkat abnormal
  • Scheduler tetap mengeksekusi task penting
  • Log error, latency, dan penggunaan resource dalam batas normal
  • Cache/config/route sudah konsisten

9.2 Verifikasi bisnis

  • Login dan registrasi berjalan
  • Checkout/pembayaran/transaksi penting tetap normal
  • Webhook masuk dan diproses dengan benar
  • Email/notifikasi masih terkirim
  • Panel admin dan reporting utama masih bisa dipakai

9.3 Tindak lanjut setelah stabil

  • Hapus workaround sementara yang tidak lagi diperlukan
  • Rapikan deprecation dan konfigurasi lama
  • Update dokumentasi operasional dan onboarding tim
  • Catat temuan untuk upgrade mayor berikutnya

10. Ringkasan playbook yang bisa langsung dipakai

Jika diringkas, alur upgrade Laravel 12 yang aman untuk aplikasi existing adalah sebagai berikut:

  1. Audit versi PHP, Laravel, dan semua dependency Composer
  2. Baca upgrade guide resmi dan daftar breaking change yang relevan
  3. Pastikan test suite, smoke test, dan health check tersedia
  4. Buat branch upgrade khusus dan batasi perubahan non-esensial
  5. Upgrade package penghambat terlebih dahulu, lalu framework
  6. Perbaiki area sensitif: middleware, provider, auth, exception, queue, testing
  7. Gunakan migration aman dengan pola expand-and-contract
  8. Deploy bertahap lewat staging, rolling/blue-green/canary sesuai kemampuan tim
  9. Restart worker, verifikasi scheduler, dan kelola cache dengan benar
  10. Siapkan rollback kode, infrastruktur, dan strategi data sebelum rilis

Upgrade yang baik bukan yang paling cepat selesai, tetapi yang terukur, bisa diverifikasi, dan mudah dipulihkan ketika terjadi masalah. Dengan pendekatan ini, tim kecil pun tetap bisa memigrasikan proyek ke Laravel 12 tanpa downtime yang berlebihan dan tanpa mempertaruhkan stabilitas produk aktif.