macOS’ta Laravel Kurulumu: Eksiksiz Türkçe Rehber

macOS’ta Laravel kurulumu yapmak aslında çok zor değil; önemli olan hangi aracı neden kurduğunu bilmek ve her adımı terminalden doğrulamaktır. Laravel projesi açmak için PHP, Composer, Laravel Installer, Node.js, Git, bir editör ve çoğu zaman bir veritabanı aracına ihtiyaç duyarız.

Bu rehberde macOS üzerinde Laravel kurulumunu eksiksiz anlatıyorum. Ana yöntem olarak Laravel Herd kullanacağız. Çünkü Herd, macOS’ta PHP, Composer, Laravel CLI, Node/NPM ve lokal geliştirme ortamını çok pratik hale getirir. Yine de Homebrew, Valet, Docker/Sail ve manuel alternatifleri de açıklayacağım.

Kurulum Öncesi Gerekenler

• macOS 12 veya üzeri: Laravel Herd için güncel macOS gerekir.
• Terminal: macOS’un kendi Terminal uygulaması yeterlidir. iTerm2 de kullanabilirsin.
• İnternet bağlantısı: Composer ve npm paketleri indirilecek.
• Bir kod editörü: VS Code, PhpStorm veya başka editör olabilir.

1. Terminali Aç ve Sistemini Kontrol Et

Önce Terminal uygulamasını aç. macOS sürümünü görmek için:

sw_vers

İşlemci mimarisini görmek için:

uname -m

`arm64` görüyorsan Apple Silicon, `x86_64` görüyorsan Intel Mac kullanıyorsun. Kurulum araçları genelde ikisini de destekler; ama Homebrew path’i Apple Silicon’da farklı olabilir.

2. En Kolay Yol: Laravel Herd Kurulumu

macOS’ta Laravel’e başlamanın en rahat yolu Laravel Herd kurmaktır. Herd; PHP, Composer, Laravel CLI, Nginx, Node/NPM ve `.test` domain desteğini tek uygulama içinde sunar.

Kurulum için şu adrese git:

https://herd.laravel.com

macOS sürümünü indir, `.dmg` dosyasını aç ve Herd uygulamasını Applications klasörüne taşı. Sonra Herd’i aç ve ilk kurulum adımlarını tamamla.

Kurulumdan sonra yeni bir Terminal aç ve kontrol et:

php -v
composer -V
laravel --version
node -v
npm -v

Bu komutlar sürüm döndürüyorsa macOS Laravel geliştirme ortamının ana parçası hazır demektir.

3. Composer ve Laravel Installer

Herd Composer’ı hazır getirebilir; yine de Laravel Installer’ı global kurmak iyi olur:

composer global require laravel/installer

Sonra kontrol et:

laravel --version

Eğer `laravel: command not found` hatası alırsan Composer global bin path’i terminalde tanınmıyor olabilir. Şunu çalıştır:

composer global config bin-dir --absolute

Çıkan dizini `~/.zshrc` dosyana eklemen gerekebilir:

nano ~/.zshrc

Örnek path satırı:

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

Sonra terminal ayarını yenile:

source ~/.zshrc

4. İlk Laravel Projesini Oluştur

Projeleri tutacağın klasörü oluştur:

mkdir -p ~/Sites
cd ~/Sites

Yeni Laravel projesi oluştur:

laravel new macos-blog

Installer sana starter kit, test framework ve veritabanı seçimi sorabilir. İlk deneme için sade ilerleyebilir veya authentication istiyorsan Livewire/React/Vue starter kit seçebilirsin. Veritabanı için SQLite başlangıçta en kolay yoldur.

Projeye gir:

cd macos-blog

Migration çalıştır:

php artisan migrate

Frontend paketlerini kur:

npm install

Geliştirme için bir terminalde Vite:

npm run dev

Başka terminalde Laravel sunucusu:

php artisan serve

Tarayıcıda aç:

http://127.0.0.1:8000

5. Herd ile .test Domain Kullanımı

Herd’in güzel tarafı projeleri `.test` domain ile çalıştırabilmesidir. Eğer `~/Herd` veya Herd’in park ettiği klasörde proje oluşturursan şu tarz adresler kullanabilirsin:

http://macos-blog.test

Bu sayede her proje için port hatırlamak zorunda kalmazsın. Herd uygulamasında “Sites” veya “Parked Paths” bölümünden hangi klasörlerin otomatik servis edildiğini görebilirsin.

6. VS Code Kurulumu

Kod editörü olarak VS Code kullanmak istersen şu adresten indir:

https://code.visualstudio.com/

Kurulumdan sonra VS Code içinde Command Palette aç ve “Shell Command: Install 'code' command in PATH” seçeneğini çalıştır. Böylece terminalden şu komutla proje açabilirsin:

code .

Laravel için önerilen VS Code eklentileri:

• PHP Intelephense
• Laravel Extra Intellisense
• Laravel Blade Snippets
• DotENV
• Tailwind CSS IntelliSense

7. Git Kurulumu

macOS’ta Git bazen Xcode Command Line Tools ile gelir. Kontrol et:

git --version

Git yoksa macOS kurulum penceresi açabilir. Alternatif olarak Homebrew ile de kurabilirsin:

brew install git

İlk ayarları yap:

git config --global user.name "Ad Soyad"
git config --global user.email "mail@example.com"

8. Homebrew Alternatifi

Herd yerine manuel paket yönetmek istersen Homebrew kullanabilirsin. Homebrew kurulumu için:

https://brew.sh

Apple Silicon Mac’lerde Homebrew genelde `/opt/homebrew` altına kurulur. Kontrol:

brew --version

PHP, Composer, Node ve MySQL kurmak istersen:

brew install php composer node mysql

Fakat yeni başlayan biri için Herd daha az sorun çıkarır. Homebrew daha çok sistemi elle yönetmek isteyenler için mantıklıdır.

9. Veritabanı Seçimi

Laravel 12 ile ilk projede SQLite kullanmak çok pratik. `.env` içinde şu ayar yeterli olur:

DB_CONNECTION=sqlite

MySQL kullanmak istiyorsan Herd Pro, DBngin, TablePlus, DBeaver veya Homebrew MySQL seçeneklerinden birini kullanabilirsin. MySQL `.env` örneği:

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

Ayar değiştirince config temizle:

php artisan config:clear

10. Storage Link ve İlk Kontroller

Dosya/resim yükleme yapacaksan public storage link oluştur:

php artisan storage:link

Proje durumunu kontrol etmek için:

php artisan about
php artisan route:list
php artisan migrate:status
php artisan test
npm run build

Bu komutlar temiz dönüyorsa proje geliştirmeye hazırdır.

11. Laravel Sail ve Docker Alternatifi

Docker tabanlı ortam istiyorsan Laravel Sail kullanabilirsin. Docker Desktop kurulduktan sonra:

php artisan sail:install

Sonra:

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

Sail ekipli projelerde herkesin aynı servislerle çalışmasını sağlar. Ama ilk Laravel öğrenme aşamasında Herd daha kolaydır.

12. Sık Hatalar ve Çözümleri

laravel komutu bulunamadı: Laravel Installer kurulmamış olabilir veya Composer global bin path’i eksiktir. `composer global require laravel/installer` ve `composer global config bin-dir --absolute` komutlarını kontrol et.

php sürümü yanlış: Birden fazla PHP kurulu olabilir. `which php` komutu hangi PHP’nin çalıştığını gösterir.

npm run dev hata veriyor: Önce `npm install` çalıştır. Node sürümün eskiyse Herd veya Node.js LTS ile güncelle.

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

SQLSTATE hatası: `.env` veritabanı ayarlarını kontrol et, sonra `php artisan config:clear` çalıştır.

.test domain açılmıyor: Herd açık mı, proje parked path içinde mi, site Herd panelinde görünüyor mu kontrol et.

13. Önerilen Kurulum Sırası

1. macOS sürümünü kontrol et.
2. Laravel Herd kur.
3. `php`, `composer`, `laravel`, `node`, `npm` komutlarını kontrol et.
4. VS Code veya PhpStorm kur.
5. Git ayarlarını yap.
6. `~/Sites` veya `~/Herd` altında ilk Laravel projesini oluştur.
7. SQLite ile migration çalıştır.
8. `npm install`, `npm run dev`, `php artisan serve` ile projeyi aç.
9. İhtiyaç varsa MySQL/PostgreSQL, Docker/Sail veya Valet ekle.

Hızlı Komut Özeti

php -v
composer -V
laravel --version
node -v
npm -v
git --version

mkdir -p ~/Sites
cd ~/Sites
laravel new macos-blog
cd macos-blog
php artisan migrate
npm install
npm run dev
php artisan serve

Sonuç

macOS’ta Laravel kurulumu için en rahat başlangıç Laravel Herd kullanmaktır. Herd sayesinde PHP, Composer, Laravel CLI, Node/NPM ve lokal site yönetimi daha az uğraştırır. İlk proje için SQLite seçip hızlıca ayağa kalkabilir, sonra ihtiyaç oldukça MySQL, PostgreSQL, Docker/Sail veya Homebrew gibi araçları ekleyebilirsin.

Benim önerim sade: macOS + Laravel Herd + VS Code veya PhpStorm + Git + SQLite ile başla. Proje büyüdükçe veritabanı, queue, Redis, mail, storage ve deployment tarafını adım adım ekle. Böyle kurulan ortam hem öğrenme hem gerçek proje geliştirme için daha temiz ilerler.

Kaynak notu: Bu yazı Laravel 12 resmi kurulum yaklaşımı ve Laravel Herd macOS akışı temel alınarak hazırlanmıştır.