Laravel 12 Kurulumu: Sıfırdan Eksiksiz Türkçe Rehber

Laravel 12 kurulumu doğru yapıldığında proje daha ilk günden temiz, giriş/kayıt sistemi hazır, veritabanı bağlı ve geliştirmeye uygun olur. Bu rehberde terminalde hangi komutu yazacağını, komuttan sonra ne beklemen gerektiğini ve authentication akışını nasıl kontrol edeceğini adım adım anlatıyorum.

Laravel'i kurmak sadece `laravel new` yazmak değildir. PHP, Composer, Laravel Installer, Node/NPM, `.env`, migration, Vite, starter kit, login/register sayfaları, kullanıcı tablosu ve ilk testler birlikte düşünülmelidir. Aşağıdaki akış, sıfırdan Laravel 12 projesi açıp kullanıcı kayıt/giriş işlemlerini çalışır halde görmek isteyenler içindir.

0. Bu Rehberde Ne Kuracağız?

Örnek proje adımız `blog-panel` olsun. Sen kendi proje adına göre değiştirebilirsin. Hedefimiz şu:

• Laravel 12 projesi oluşturmak.
• Veritabanını hazırlamak.
• Starter kit ile authentication ekranlarını kurmak.
• Register, login, logout ve dashboard akışını test etmek.
• Terminalde kontrol komutlarıyla kurulumun temiz olduğunu görmek.

1. Gerekli Araçları Kontrol Et

Önce terminali aç. macOS'ta Terminal veya iTerm, Windows'ta PowerShell kullanabilirsin. Şu komutları tek tek yaz:

php -v
composer -V
node -v
npm -v

Terminalde buna benzer sürüm çıktıları görmelisin:

PHP 8.x.x
Composer version 2.x.x
v22.x.x
10.x.x

Komutlardan biri bulunamıyorsa önce o aracı kurmalısın. macOS ve Windows için en kolay yol Laravel Herd kullanmaktır. Herd; PHP, Composer, Laravel CLI ve yerel Nginx ortamını hazır getirir. Docker tercih ediyorsan ileride Sail bölümünü kullanabilirsin.

2. Laravel Installer Kurulumu

Composer hazırsa Laravel Installer'ı global olarak kur:

composer global require laravel/installer

Kurulumdan sonra terminali kapatıp tekrar aç. Sonra kontrol et:

laravel --version

Eğer terminal `laravel: command not found` diyorsa Composer global bin dizini PATH içinde değildir. macOS veya Linux'ta şu komutla Composer global dizinini görebilirsin:

composer global config bin-dir --absolute

Çıkan dizini shell profil dosyana eklemen gerekir. Örneğin zsh kullanıyorsan:

nano ~/.zshrc

Dosyanın sonuna kendi bilgisayarındaki gerçek dizine göre şuna benzer bir satır ekle:

export PATH="$HOME/.composer/vendor/bin:$PATH"

Sonra terminal ayarını yenile:

source ~/.zshrc
laravel --version

3. Laravel 12 Projesini Oluştur

Projelerini tuttuğun klasöre git. Örneğin `Sites` klasörü:

cd ~/Sites

Şimdi yeni Laravel 12 projesini oluştur:

laravel new blog-panel

Laravel Installer sana birkaç soru sorabilir. Authentication kurmak istediğimiz için starter kit seçimini boş geçmeyeceğiz. Başlangıç için en sade seçenek genellikle Livewire starter kit'tir; Blade'e yakın kalır, React/Vue SPA mantığına girmeden auth ekranlarını hızlı verir.

Which starter kit would you like to install?
  none
  react
  vue
  livewire

Seçim: livewire

Veritabanı sorulursa ilk kurulum için SQLite seçebilirsin. MySQL kullanacaksan aşağıdaki MySQL bölümüne göre `.env` ayarlarsın.

Which database will your application use?
  sqlite
  mysql
  pgsql

Seçim: sqlite

Kurulum bitince proje klasörüne gir:

cd blog-panel

4. Starter Kit Seçimini Anlayalım

Laravel 12 starter kit'leri authentication altyapısını hazır getirir. React, Svelte, Vue ve Livewire seçenekleri login, register, password reset, email verification ve profil ayarları gibi temel akışları Laravel'in auth sistemiyle birlikte kurar. Arka tarafta Fortify, session tabanlı authentication, route'lar ve kullanıcı işlemlerinin önemli kısmını yönetir.

Yeni başlayan biri için pratik önerim:

• Livewire: Laravel ve Blade tarafına yakın kalmak isteyenler için rahat seçim.
• Vue veya React: Inertia tabanlı daha modern SPA hissi isteyenler için uygun.
• WorkOS AuthKit: Google, Microsoft, GitHub, Apple, passkey, magic auth ve SSO gibi daha kurumsal auth ihtiyaçlarında düşünülebilir.

5. .env Dosyasını Kontrol Et

Proje kökünde `.env` dosyasını aç:

nano .env

Başlangıç için şu alanları kontrol et:

APP_NAME="Blog Panel"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000
APP_LOCALE=tr

`APP_KEY` boşsa terminalde şunu yaz:

php artisan key:generate

Başarılı olduğunda terminal buna benzer çıktı verir:

INFO  Application key set successfully.

6. SQLite ile Veritabanı Kurulumu

SQLite seçtiysen çoğu zaman Laravel gerekli dosyayı hazırlar. Yine de kontrol edelim:

ls database

`database.sqlite` yoksa oluştur:

touch database/database.sqlite

`.env` içinde veritabanı ayarı şöyle olmalı:

DB_CONNECTION=sqlite

Şimdi migration çalıştır:

php artisan migrate

Terminalde `users`, `cache`, `jobs` gibi tabloların oluşturulduğunu görmelisin. Authentication için özellikle `users` tablosu önemlidir.

7. MySQL Kullanacaksan

MySQL kullanmak istiyorsan önce veritabanını oluştur. MySQL terminaline girebiliyorsan:

mysql -u root -p

MySQL içinde şunları yaz:

CREATE DATABASE blog_panel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;

Sonra Laravel `.env` dosyasını düzenle:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=blog_panel
DB_USERNAME=root
DB_PASSWORD=

Config cache temizliği yap ve migration çalıştır:

php artisan config:clear
php artisan migrate

8. Frontend Paketlerini Kur

Starter kit seçtiğin için frontend bağımlılıkları önemlidir. Terminalde proje kökündeyken yaz:

npm install

Geliştirme sırasında Vite'ı çalıştırmak için:

npm run dev

Bu terminal açık kalabilir. Başka bir terminal sekmesi açıp Laravel sunucusunu başlatacağız.

9. Laravel Geliştirme Sunucusunu Başlat

Yeni terminal sekmesinde proje klasörüne gir:

cd ~/Sites/blog-panel

Laravel'in pratik geliştirme komutunu kullanabilirsin:

composer run dev

Alternatif olarak sadece Laravel sunucusunu başlatmak istersen:

php artisan serve

Terminalde buna benzer bir çıktı görürsün:

INFO  Server running on [http://127.0.0.1:8000].

Tarayıcıda şu adresi aç:

http://127.0.0.1:8000

10. Authentication Sayfalarını Kontrol Et

Starter kit doğru kurulduysa şu adresler çalışmalıdır:

http://127.0.0.1:8000/register
http://127.0.0.1:8000/login
http://127.0.0.1:8000/dashboard

`/dashboard` sayfasına giriş yapmadan gidersen Laravel seni login sayfasına yönlendirmelidir. Bu iyi işarettir; protected route çalışıyor demektir.

Şimdi `/register` sayfasına gir ve test kullanıcı oluştur:

Name: Test Kullanıcı
Email: test@example.com
Password: password
Confirm Password: password

Kayıt başarılıysa dashboard ekranına yönlenmelisin. Sonra logout yapıp `/login` sayfasından tekrar giriş dene.

11. Kullanıcı Veritabanına Yazıldı mı?

Kayıt işleminin veritabanına düştüğünü terminalden kontrol edebilirsin:

php artisan tinker

Tinker açılınca şunu yaz:

App\Models\User::first();

Test kullanıcının email adresini görüyorsan authentication kayıt akışı çalışıyor demektir. Tinker'dan çıkmak için:

exit

12. Auth Route'larını Listele

Laravel'in hangi auth route'larını oluşturduğunu görmek için:

php artisan route:list

Liste uzun gelirse filtrele:

php artisan route:list --path=login
php artisan route:list --path=register
php artisan route:list --path=dashboard
php artisan route:list --path=password

Login, register, forgot-password ve dashboard route'larını görmen gerekir. Starter kit ve aktif özelliklere göre email verification route'ları da listelenebilir.

13. Protected Route Örneği

Kendi özel sayfanı sadece giriş yapan kullanıcılar görsün istiyorsan `routes/web.php` dosyasına şu örneği ekleyebilirsin:

use Illuminate\Support\Facades\Route;

Route::get('/panel', function () {
    return view('panel');
})->middleware(['auth', 'verified']);

Sonra view dosyasını oluştur:

mkdir -p resources/views
nano resources/views/panel.blade.php

Dosyanın içine basit bir içerik yaz:

<h1>Panel alanı</h1>
<p>Bu sayfayı sadece giriş yapan kullanıcı görür.</p>

Tarayıcıda `/panel` adresine giriş yapmadan gidersen login sayfasına yönlenmelisin. Giriş yaptıktan sonra panel içeriği görünür.

14. Mevcut Kullanıcıyı Kod İçinde Alma

Bir controller, route veya Livewire component içinde giriş yapan kullanıcıya erişmek için:

use Illuminate\Support\Facades\Auth;

$user = Auth::user();

Blade içinde kullanmak istersen:

@auth
    Merhaba, {{ auth()->user()->name }}
@endauth

@guest
    Lütfen giriş yapın.
@endguest

15. Logout Nasıl Çalışır?

Starter kit logout işlemini hazır getirir. Genellikle kullanıcı menüsünde çıkış seçeneği bulunur. Manuel form örneği gerekirse:

<form method="POST" action="{{ route('logout') }}">
    @csrf
    <button type="submit">Çıkış Yap</button>
</form>

Logout işlemi POST isteğiyle yapılmalıdır. Güvenlik için CSRF token gerekir; `@csrf` bunu sağlar.

16. Email Verification Açık mı?

Bazı starter kit kurulumlarında email verification akışı hazır gelir, bazılarında proje tercihine göre aktif etmen gerekir. `app/Models/User.php` dosyasında email doğrulama kullanmak için model `MustVerifyEmail` implement edebilir:

use Illuminate\Contracts\Auth\MustVerifyEmail;

class User extends Authenticatable implements MustVerifyEmail
{
    // ...
}

Protected route üzerinde `verified` middleware kullanırsan doğrulanmamış kullanıcıları doğrulama ekranına yönlendirebilirsin:

Route::get('/dashboard', function () {
    return view('dashboard');
})->middleware(['auth', 'verified']);

17. Şifre Sıfırlama İçin Mail Ayarı

Password reset linklerinin çalışması için mail ayarları gerekir. Lokal geliştirmede log driver ile başlayabilirsin:

MAIL_MAILER=log
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

Şifre sıfırlama formunu test ettiğinde mail içeriği `storage/logs/laravel.log` içine yazılır:

tail -f storage/logs/laravel.log

18. Sail ile Docker Üzerinden Aynı Kurulum

Docker kullanmak istiyorsan proje içinde Sail kurabilirsin:

php artisan sail:install

MySQL, Redis veya Mailpit gibi servisleri seçtikten sonra:

./vendor/bin/sail up -d
./vendor/bin/sail artisan migrate
./vendor/bin/sail npm install
./vendor/bin/sail npm run dev

Sail kullanırken Laravel komutlarını konteyner içinde çalıştırırsın. Örneğin auth route kontrolü:

./vendor/bin/sail artisan route:list --path=login

19. Kurulum Sonrası Temizlik ve Test

Kurulum bittiğinde şu komutları çalıştır:

php artisan about
php artisan migrate:status
php artisan route:list --path=login
php artisan test

Frontend production build almak için:

npm run build

Cache sorunlarında:

php artisan optimize:clear

20. Git ile İlk Commit

Proje çalışıyor, auth sayfaları açılıyor, kayıt/giriş tamam ise ilk temiz commit'i al:

git init
git add .
git commit -m "Install Laravel 12 with authentication"

`.env` dosyasını Git'e ekleme. Laravel `.gitignore` bunu zaten engeller; ama yine de `git status` çıktısını kontrol etmek iyi alışkanlıktır.

git status

21. En Sık Hatalar ve Çözümleri

laravel: command not found Composer global bin dizini PATH içinde değildir. `composer global config bin-dir --absolute` ile dizini bul ve PATH'e ekle.

Vite manifest not found Frontend build çalışmamıştır. Geliştirmede `npm run dev`, production için `npm run build` çalıştır.

SQLSTATE database hatası `.env` veritabanı bilgileri yanlıştır veya veritabanı oluşturulmamıştır. Ayarları düzeltip `php artisan config:clear` çalıştır.

419 Page Expired CSRF token eksik, session ayarı bozuk veya form POST ederken `@csrf` unutulmuştur.

Dashboard login'e yönlendirmiyor Route üzerinde `auth` middleware yoktur veya starter kit kurulumu eksiktir. `php artisan route:list --path=dashboard` ile kontrol et.

Hızlı Özet

composer global require laravel/installer
cd ~/Sites
laravel new blog-panel
cd blog-panel
php artisan key:generate
php artisan migrate
npm install
npm run dev
php artisan serve

Sonra tarayıcıda sırayla şunları kontrol et:

http://127.0.0.1:8000/register
http://127.0.0.1:8000/login
http://127.0.0.1:8000/dashboard

Sonuç

Laravel 12 kurulumunu kusursuz hale getiren şey, sadece proje dosyalarını indirmek değil; terminal kontrollerini yapmak, veritabanını hazırlamak, starter kit ile authentication akışını kurmak, register/login/logout davranışını test etmek ve ilk temiz commit'i almaktır. Bu adımları tamamladığında Laravel 12 projen sadece açılmış değil, gerçekten geliştirmeye hazır hale gelmiş olur.

Kaynak notu: Bu yazı Laravel 12 resmi kurulum, starter kit ve authentication dokümantasyonundaki güncel akışı temel alır; üzerine gerçek projelerde kullandığım terminal kontrol adımlarını ekler.