Laravel cPanel Kurulumu: Paylaşımlı Hostinge SSH'siz Laravel Yükleme Rehberi

Laravel'i cPanel'li bir web hosting hesabına yüklemek, WordPress kurmaktan farklıdır: Laravel'de web'e açılması gereken tek klasör public'tir, proje Composer paketleriyle birlikte gelir ve .env dosyası herkese açık klasörde durmamalıdır. Paylaşımlı hostingte buna bir de sınır eklenir: çoğu sağlayıcıda SSH ve Composer yoktur, güvenlik için exec, proc_open ve symlink gibi PHP işlevleri kapalıdır. Bu rehberde Laravel cPanel kurulumunu bu koşulları baştan hesaba katarak, SSH olmadan adım adım anlatıyoruz: klasör düzeni, index.php düzenlemesi, PHP sürümü, veritabanı, .env güvenliği, storage:link yerine kullanılacak yöntem, cron ile zamanlanmış görevler ve kuyruk.

cPanel ekran görüntüleri AnkSOFT web hosting altyapısındaki gerçek bir cPanel 134 hesabından alınmıştır; kullanıcı adı, alan adı ve IP adresleri maskelenmiştir. Laravel tarafındaki tüm adımlar gerçek bir Laravel 13.39 projesiyle, paylaşımlı hostingteki kapalı PHP işlevleri aynen uygulanarak denenmiştir.

---

Başlamadan Önce: Paylaşımlı Hostingte Neler Farklı?

AnkSOFT web hosting hesaplarında Laravel için durum şöyledir:

Projeniz sürekli çalışan bir kuyruk işçisi (Horizon, Reverb, Octane), Redis ile yoğun önbellek ya da komut satırı erişimi gerektiriyorsa doğru ortam VDS'tir; bunun için Laravel VDS kurulumu rehberimize bakın.

---

Doğru Klasör Düzeni: Laravel Kodu public_html Dışında

Paylaşımlı hostingte en sık yapılan hata, Laravel projesinin tamamını public_html içine yükleyip adresin sonuna /public eklemek ya da .htaccess ile public klasörüne yönlendirmektir. Bu durumda .env, storage/logs/laravel.log ve composer.json gibi dosyalar web klasörünün içinde kalır; tek bir yapılandırma hatası veritabanı parolanızı ve APP_KEY'i açığa çıkarır.

Doğru düzen şudur:

/home/kullanici/
├── laravel/           ← projenin tamamı (app, bootstrap, config, routes, storage, vendor, .env)
└── public_html/       ← yalnızca Laravel'in public klasörünün İÇERİĞİ
    ├── index.php      ← yolları ../laravel/ olarak düzenlenmiş
    ├── .htaccess
    ├── favicon.ico, robots.txt
    ├── build/         ← npm run build çıktısı
    └── storage/       ← yüklenen dosyalar (aşağıda anlatılıyor)

Böylece web sunucusu yalnızca public_html'i görür; .env ve kaynak kodunuz tarayıcıdan hiçbir şekilde istenemez.

---

Adım 1: PHP Sürümünü Seçin

cPanel ana sayfasında Yazılım bölümündeki MultiPHP Yöneticisi'ni açın. Kullanacağınız diğer araçlar da aynı sayfadadır: Dosya Yöneticisi, Database Wizard ve Gelişmiş bölümündeki Cron İşleri.

1. Alan adınızın yanındaki kutuyu işaretleyin.
2. Sağdaki PHP Sürümü listesinden PHP 8.4 (ea-php84) veya PHP 8.3 (ea-php83) seçin.
3. Uygula'ya tıklayın.

Hangi sürümü seçmelisiniz? Projeyi bilgisayarınızda hangi PHP sürümüyle kurduysanız onu. Bu ayrıntı önemlidir: Composer paket sürümlerini çalıştığı PHP'ye göre seçer. Testimizde PHP 8.4 ile oluşturulan Laravel 13 projesi, PHP 8.4.1 isteyen bileşenlerle kilitlendi; aynı dosyalar PHP 8.3 seçili bir sitede yalnızca şu yazıyla açıldı:

Composer detected issues in your platform:

Your Composer dependencies require a PHP version ">= 8.4.1".

Sitede PHP 8.3 kullanmak zorundaysanız projenizde bir kez şunu çalıştırın; Composer bileşenleri PHP 8.3 ile uyumlu sürümlere indirir:

composer config platform.php 8.3.0
composer update

---

Adım 2: Projeyi Bilgisayarınızda Yayına Hazırlayın

Sunucuda Composer olmadığı için vendor klasörünü yerelde, yalnızca canlıda gereken paketlerle hazırlarsınız. Proje klasörünüzde:

composer install --no-dev --optimize-autoloader
npm ci
npm run build

• --no-dev, PHPUnit, Faker gibi yalnızca geliştirmede kullanılan paketleri çıkarır. Testimizde 33 paket kaldırıldı, vendor klasörü 46,8 MB'tan 27 MB'a indi.
• --optimize-autoloader, sınıf haritasını önceden oluşturur ve her istekte dosya aramayı azaltır.
• npm run build, CSS ve JavaScript dosyalarını public/build klasörüne derler. Bu adımı atlarsanız site "Vite manifest not found" hatası verir.

Ardından iki zip dosyası hazırlayın:

1. laravel.zip: Projenin tamamı, public klasörü, node_modules ve .env hariç. .env'i sunucuda ayrıca oluşturacaksınız.
2. public.zip: public klasörünün içindekiler (index.php, .htaccess, build/, favicon.ico, robots.txt).

Yerelde php artisan optimize veya config:cache çalıştırdıysanız bootstrap/cache klasöründeki config.php, routes-*.php, events.php dosyalarını zip'e koymayın. Bu dosyalar bilgisayarınızdaki tam dosya yollarını içerir ve sunucuda 500 hatasına neden olur. bootstrap/cache klasörünün kendisi (boş haliyle) yüklenmelidir.

---

Adım 3: Dosyaları Yükleyin

cPanel Dosya Yöneticisi'ni açın. Sol üstteki ev simgesi sizi /home/kullanici klasörüne götürür; public_html de burada durur.

1. Ev klasöründeyken + Klasör ile laravel adlı bir klasör oluşturun.
2. laravel klasörüne girin, Yükle ile laravel.zip dosyasını yükleyin, dosyayı seçip Çıkar ile açın.
3. public_html klasörüne girin, varsayılan index.html gibi dosyaları silin, public.zip dosyasını yükleyip Çıkar ile açın.
4. Zip dosyalarını silin.

Dosya Yöneticisi'nde nokta ile başlayan dosyaları (.htaccess, .env) göremiyorsanız sağ üstteki Ayarlar'dan Gizli Dosyaları Göster seçeneğini açın.

---

Adım 4: public_html/index.php Dosyasını Düzenleyin

public_html/index.php dosyası projeyi ../vendor ve ../bootstrap yollarında arar. Proje artık bir üst klasördeki laravel klasöründe olduğu için üç satırı değiştirin. Dosyayı seçip Düzenle'ye tıklayın:

if (file_exists($maintenance = __DIR__.'/../laravel/storage/framework/maintenance.php')) {
    require $maintenance;
}

require __DIR__.'/../laravel/vendor/autoload.php';

$app = require_once __DIR__.'/../laravel/bootstrap/app.php';

.htaccess dosyasına dokunmayın. Laravel'in public/.htaccess dosyası LiteSpeed ve Apache'de aynı şekilde çalışır; bütün istekleri index.php'ye yönlendirir.

Ek alan adı veya alt alan adı kullanıyorsanız: Bu sunucularda ek alan adlarının kök dizini public_html içinde olmak zorundadır (örneğin public_html/ikincisite). O durumda public içeriğini public_html/ikincisite klasörüne, projeyi /home/kullanici/ikincisite-laravel klasörüne koyun ve yolları __DIR__.'/../../ikincisite-laravel/...' biçiminde iki üst klasöre göre yazın.

---

Adım 5: public Klasörünü ve Dosya Diskini Tanıtın (storage:link Yerine)

Laravel, yüklenen dosyaları (profil fotoğrafı, ürün görseli) storage/app/public klasörüne kaydeder ve php artisan storage:link ile public/storage adresine bir sembolik bağlantı kurar. Paylaşımlı hostingte bu komut çalışmaz; symlink ve exec kapalı olduğu için şu hatayı verir:

In Filesystem.php line 368:
  Call to undefined function Illuminate\Filesystem\exec()

Bağlantıya hiç ihtiyaç duymayan yöntem, Laravel'e web klasörünün public_html olduğunu söylemek ve dosyaları doğrudan oraya kaydetmektir. İki dosyada birer değişiklik yeterlidir:

1. laravel/bootstrap/app.php: En sondaki ->create(); satırını şöyle değiştirin:

    })->create()
    ->usePublicPath(dirname(__DIR__, 2).'/public_html');

2. laravel/config/filesystems.php: public diskindeki root satırını değiştirin:

'public' => [
    'driver' => 'local',
    'root' => public_path('storage'),
    'url' => rtrim(env('APP_URL', 'http://localhost'), '/').'/storage',
    'visibility' => 'public',
],

Bu ayarla Storage::disk('public')->put(...) dosyaları public_html/storage içine yazar, Storage::url(...) doğru adresi üretir. Test ortamımızda dosya public_html/storage/avatarlar/ altına kaydedildi ve /storage/avatarlar/... adresinden açıldı. usePublicPath ayarı bootstrap/app.php içinde olduğu için hem web isteklerinde hem cron ile çalışan Artisan komutlarında geçerlidir. Ek alan adında dirname(__DIR__, 2).'/public_html/ikincisite' yazın.

---

Adım 6: Veritabanını Oluşturun ve .env Dosyasını Hazırlayın

cPanel'de Database Wizard'ı açın: bir veritabanı (örneğin laravel), bir kullanıcı ve güçlü bir parola oluşturun, kullanıcıya ALL PRIVILEGES verin. cPanel adların başına hesap kullanıcı adınızı ekler; gerçek adlar kullanici_laravel biçiminde olur.

Dosya Yöneticisi'nde laravel klasöründe + Dosya ile .env adlı bir dosya oluşturun ve yerel .env dosyanızı temel alarak şu değerlerle doldurun:

APP_NAME="Ornek Proje"
APP_ENV=production
APP_KEY=base64:yerelde-urettiginiz-anahtar
APP_DEBUG=false
APP_URL=https://alanadiniz.com
APP_LOCALE=tr

LOG_CHANNEL=daily
LOG_LEVEL=error

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=kullanici_laravel
DB_USERNAME=kullanici_dbkullanici
DB_PASSWORD=sihirbazda-urettiginiz-parola

SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

MAIL_MAILER=smtp
MAIL_SCHEME=smtps
MAIL_HOST=mail.alanadiniz.com
MAIL_PORT=465
MAIL_USERNAME=bildirim@alanadiniz.com
MAIL_PASSWORD=e-posta-hesabinin-parolasi
MAIL_FROM_ADDRESS="bildirim@alanadiniz.com"
MAIL_FROM_NAME="${APP_NAME}"

Satır satır dikkat edilecekler:

• APP_KEY: Sunucuda php artisan key:generate çalıştıramayacağınız için anahtarı bilgisayarınızda php artisan key:generate --show ile üretip buraya yapıştırın. Yayına aldıktan sonra değiştirmeyin.
• APP_DEBUG=false: Yayında true bırakmak, hata anında veritabanı adını, dosya yollarını ve SQL sorgularını ziyaretçiye gösterir.
• LOG_CHANNEL=daily: Günlüğü her gün ayrı dosyaya yazar ve eski dosyaları siler; tek laravel.log dosyasının disk kotanızı doldurmasını önler.
• MAIL_MAILER=smtp: Sunucuda PHP mail() işlevi kapalıdır; Laravel e-postaları cPanel'de açacağınız bir e-posta hesabı üzerinden SMTP ile gönderir. Hesap açma ve SMTP bilgileri için cPanel e-posta kurulumu rehberimize bakın.
• SESSION/CACHE/QUEUE database: Laravel 13'ün varsayılanlarıdır ve ek bir servis gerektirmez; tablolar ilk migration ile kurulur.

Son olarak .env dosyasını seçip İzinler'den 600 yapın; dosyayı yalnızca hesabınız okuyabilsin. .env zaten public_html dışında olduğu için tarayıcıdan erişilemez.

---

Adım 7: Migration'ları SSH Olmadan Çalıştırın

Tabloları kurmanın iki yolu vardır:

Yol 1: Tek seferlik cron işi (önerilen). cPanel Cron İşleri sayfasında, dakika dahil tüm alanlara * yazıp komut olarak şunu ekleyin:

/usr/local/bin/ea-php84 /home/kullanici/laravel/artisan migrate --force >> /home/kullanici/laravel/storage/logs/cron.log 2>&1

Bir dakika bekleyin, Dosya Yöneticisi'nde storage/logs/cron.log dosyasını açıp DONE satırlarını görün, ardından cron işini silin. ea-php84 yerine MultiPHP Yöneticisi'nde seçtiğiniz sürümü yazın (ea-php83, ea-php85). Aynı yöntemle bir kez php artisan optimize da çalıştırabilirsiniz; .env'i her değiştirdiğinizde optimize:clear ve ardından optimize gerekir.

Yol 2: phpMyAdmin. Yerel veritabanınızı SQL olarak dışa aktarıp phpMyAdmin'de İçe Aktar ile yükleyin. Yerelde SQLite kullandıysanız bu yol uygun değildir.

---

Adım 8: Zamanlanmış Görevler (schedule:run) için Cron

Laravel'in zamanlayıcısı tek bir cron satırıyla çalışır ve her dakika çağrılmalıdır. Cron İşleri sayfasında Dakika, Saat, Gün, Ay ve Hafta İçi alanlarının beşine de * yazın; Komut alanına:

/usr/local/bin/ea-php84 /home/kullanici/laravel/artisan schedule:run >> /dev/null 2>&1

Paylaşımlı hostingte kritik ayrıntı: Laravel, routes/console.php içinde Schedule::command(...) ve Schedule::exec(...) ile tanımlanan görevleri ayrı bir süreç başlatarak çalıştırır ve bunun için PHP'nin proc_open işlevine ihtiyaç duyar. Bu işlev kapalı olduğu için bu tür görevler çalışmaz; üstelik schedule:run ekrana yine "DONE" yazar, hata yalnızca günlükte görünür:

local.ERROR: The Process class relies on proc_open, which is not available on your PHP installation.

Aynı süreç içinde çalışan Schedule::call(...) ve Schedule::job(...) görevleri ise sorunsuz çalışır. Paylaşımlı hostingte zamanlanmış görevlerinizi bu iki biçimde yazın:

use App\Jobs\RaporHazirla;
use Illuminate\Support\Facades\Schedule;

Schedule::job(new RaporHazirla)->dailyAt('03:00');
Schedule::call(fn () => \App\Models\Oturum::eskileriSil())->everyFifteenMinutes()->name('oturum-temizligi');

Bir Artisan komutunu mutlaka zamanlamanız gerekiyorsa onu schedule:run yerine kendi cron satırıyla çalıştırın (örneğin /usr/local/bin/ea-php84 /home/kullanici/laravel/artisan sitemap:olustur).

---

Adım 9: Kuyruk (Queue) İşleri

E-posta gönderme gibi işleri dispatch() ile kuyruğa atıyorsanız bir işçinin bu işleri alması gerekir. Paylaşımlı hostingte sürekli açık kalan süreç (Supervisor) çalıştıramazsınız; bunun yerine her dakika başlayıp kuyruk boşalınca kapanan bir işçi kullanın:

/usr/local/bin/ea-php84 /home/kullanici/laravel/artisan queue:work --stop-when-empty --max-time=50 >> /dev/null 2>&1

• --stop-when-empty: Bekleyen iş kalmayınca işçi kapanır, kaynak tüketmez.
• --max-time=50: İşçi en fazla 50 saniye çalışır; bir sonraki dakikanın işçisiyle üst üste binmez.

queue:work ayrı süreç açmadığı için kapalı PHP işlevlerinden etkilenmez. Paylaşımlı hostinge özgü kısıtlarla yaptığımız testte iki iş sırayla işlendi ve işçi "Queue empty" ile kapandı.

Çok az kuyruk işi olan küçük projelerde .env içinde QUEUE_CONNECTION=sync yazarak işlerin istek sırasında hemen çalışmasını da sağlayabilirsiniz; bu durumda cron işçisine gerek kalmaz ama işi tetikleyen sayfa iş bitene kadar bekler.

---

Adım 10: Siteyi Kontrol Edin

1. https://alanadiniz.com adresini açın. Karşılama sayfası veya kendi ana sayfanız görünmeli.
2. https://alanadiniz.com/up adresi Laravel'in sağlık denetimidir; uygulama hatasız açılıyorsa 200 döner.
3. https://alanadiniz.com/.env ve https://alanadiniz.com/laravel/.env adresleri 404 vermeli. Bu düzende .env web klasöründe olmadığı için bulunamaz.
4. SSL sertifikanızın etkin olduğundan emin olun; cPanel SSL kurulumu rehberimiz AutoSSL ve HTTPS yönlendirmesini anlatır.

Sayfa "500 Server Error" gösteriyorsa ilk bakılacak yer laravel/storage/logs klasörüdür. Olası nedenler ve çözümleri Laravel 500 hatası rehberimizde adım adım var.

---

Güncelleme Nasıl Yapılır?

Kodunuzu değiştirdiğinizde:

1. Yerelde composer install --no-dev --optimize-autoloader ve npm run build çalıştırın.
2. Değişen dosyaları (app, routes, resources, config, database, gerekirse vendor ve public_html/build) yükleyin. .env ve storage klasörünün üzerine yazmayın.
3. Yeni migration varsa Adım 7'deki tek seferlik cron ile migrate --force çalıştırın.
4. optimize kullanıyorsanız tek seferlik cron ile optimize:clear ve optimize çalıştırın.

Yüklemeden önce cPanel Yedekleme Sihirbazı ile dosyaların ve veritabanının yedeğini alın. Hizmet sözleşmesi gereği verilerinizin yedeklenmesi sizin sorumluluğunuzdadır.

---

En Sık Hatalar

1. Ana sayfa açılıyor, diğer sayfalar 404. public_html/.htaccess yüklenmemiştir. Gizli dosyaları gösterip kontrol edin.
2. "Composer detected issues in your platform". Sitede seçili PHP sürümü, vendor klasörünü hazırladığınız sürümden düşüktür. MultiPHP Yöneticisi'nden aynı sürümü seçin ya da composer config platform.php ile yeniden hazırlayın.
3. "Failed opening required .../vendor/autoload.php". index.php içindeki yollar yanlıştır ya da vendor klasörü yüklenmemiştir.
4. "No application encryption key has been specified". .env içinde APP_KEY boştur veya .env yanlış klasördedir (laravel/.env olmalı).
5. Yüklenen görseller 404. storage:link ile kurulmuş bir bağlantıya güveniyorsunuzdur; Adım 5'teki ayarı yapın.
6. E-postalar gitmiyor. MAIL_MAILER hâlâ log veya sendmail'dir; SMTP ayarlarını yapın.
7. Zamanlanmış görev çalışmıyor ama hata da yok. Görev Schedule::command ile tanımlıdır; günlükte proc_open hatasını arayın ve görevi Schedule::job veya ayrı bir cron satırına taşıyın.

---

Özet

1. Projenin tamamını /home/kullanici/laravel, public klasörünün içeriğini public_html içine koyun ve index.php'deki üç yolu düzenleyin.
2. MultiPHP Yöneticisi'nde, vendor klasörünü hazırladığınız PHP sürümünü seçin (Laravel 13 için en az 8.3).
3. composer install --no-dev --optimize-autoloader ve npm run build işlemlerini bilgisayarınızda yapın.
4. storage:link yerine usePublicPath ve public_path('storage') ayarını kullanın.
5. .env'de APP_ENV=production, APP_DEBUG=false, SMTP ve veritabanı bilgilerini yazın, izni 600 yapın.
6. Migration için tek seferlik cron, zamanlayıcı için her dakika schedule:run, kuyruk için queue:work --stop-when-empty kullanın; zamanlanmış görevleri Schedule::job veya Schedule::call ile yazın.

Laravel projeniz için PHP 8.3, 8.4 ve 8.5 seçilebilen, LiteSpeed Enterprise ve NVMe SSD kullanan cPanel'li web hosting paketlerimizi inceleyebilirsiniz. Birden fazla müşteri projesini yöneten ajanslar için bayi (reseller) hosting, Supervisor ile kesintisiz kuyruk, Redis veya root erişimi gereken projeler için VDS sunucu daha uygundur. Kurulumda takıldığınız adımı hata ekranının görüntüsüyle birlikte destek talebi açarak iletebilirsiniz.

---

Kaynaklar

• Laravel Deployment: sunucu gereksinimleri, dizin izinleri, optimize ve debug modu
• Laravel Installation: Directory Configuration: uygulamanın web dizininin kökünden sunulması
• Laravel Task Scheduling: schedule:run cron satırı, Schedule::job ve Schedule::call
• Laravel Queues: queue:work, --stop-when-empty, --max-time
• Laravel File Storage: public disk ve storage:link
• Composer: config.platform: hedef PHP sürümüne göre paket seçimi
• cPanel MultiPHP Manager ve cPanel Cron Jobs belgeleri