Laravel Projesini Shared Hosting’de Yayına Alma Rehberi

Laravel ile geliştirdiğiniz bir projeyi VPS yerine paylaşımlı hosting ortamına almak ilk bakışta basit görünür, ancak public klasör yapısı, dosya izinleri, Composer erişimi ve cache yönetimi gibi konular süreci karmaşıklaştırır. Bu rehberde Laravel projesini Hostinger, Natro veya benzeri bir shared hosting paketinde sorunsuz yayına almak için izlenmesi gereken adımları, sık karşılaşılan hataları ve performans optimizasyonlarını teknik detaylarıyla bulacaksınız.

Shared Hosting Laravel İçin Uygun mu?

Laravel resmi olarak shared hosting’i tavsiye etmez çünkü framework public klasörünü kök dizin olarak çalıştırmak için tasarlanmıştır. Paylaşımlı hosting paketlerinde ise tüm sitelerin kök dizini genellikle public_html klasörüdür ve bu klasörün üzerine çıkamazsınız.

Yine de küçük ölçekli projeler, kişisel portföy siteleri, blog uygulamaları veya kullanıcı sayısı az olan kurumsal siteler için shared hosting yeterli olabilir. Karar verirken şu noktalara bakın:

• Aylık ziyaretçi sayısı 30.000 altındaysa shared hosting genelde sorun çıkarmaz.
• SSH erişimi sağlayan paketleri tercih edin. SSH olmadan Composer çalıştırmak veya artisan komutları kullanmak ciddi şekilde zorlaşır.
• PHP sürümünü panel üzerinden değiştirebileceğiniz hosting paketleri seçin.
• Cron job ekleme özelliği olmalı. Aksi halde queue ve scheduler kullanılamaz.

Yayına Almadan Önce Hosting Gereksinimleri

Laravel’in son sürümleri belirli PHP ve eklenti gereksinimlerini zorunlu tutar. Yayına almadan önce hosting kontrol panelinde şu kalemleri doğrulayın.

PHP eklentilerinden biri eksikse “Class 'ZipArchive' not found” veya “Composer detected issues” gibi hatalarla karşılaşabilirsiniz. Eksik eklentileri hosting panelinin PHP yapılandırma sayfasından açabilir, mümkün değilse destek talebi oluşturabilirsiniz.

Dosya Yapısı: Public Klasörü Problemi

Paylaşımlı hostingde Laravel projesini iki farklı şekilde yerleştirebilirsiniz. Her iki yaklaşımın da güvenlik ve bakım açısından farklı sonuçları vardır.

Yöntem 1: Kök Dizinde Proje, Sadece Public public_html Altında

Bu yöntemde Laravel projesinin tamamını public_html dışına, örneğin kullanıcı kök dizinine yerleştirirsiniz. Yalnızca public klasörünün içeriği public_html‘e taşınır. Bu yöntem en güvenli olanıdır çünkü .env, storage ve vendor klasörleri web’e açık değildir.

/home/kullanici/
├── laravel-app/        ← Laravel projesi (web'den erişilemez)
│   ├── app/
│   ├── bootstrap/
│   ├── config/
│   ├── database/
│   ├── routes/
│   ├── storage/
│   ├── vendor/
│   └── .env
└── public_html/        ← Web kök dizini
    ├── index.php       ← Düzenlenecek
    ├── .htaccess
    ├── css/
    ├── js/
    └── img/

Bu yapıyı kurduktan sonra public_html/index.php dosyasını açın ve Laravel autoloader yollarını güncelleyin:

<?php
// public_html/index.php

define('LARAVEL_START', microtime(true));

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

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

$app->handleRequest(Request::capture());

Yöntem 2: Symlink ile public Klasörü

SSH erişiminiz varsa public klasörünü public_html olarak sembolik bağ vermek daha temiz bir çözümdür:

# Önce mevcut public_html'i yedekle ve sil
mv ~/public_html ~/public_html_backup
rm -rf ~/public_html

# Sembolik bağ oluştur
ln -s ~/laravel-app/public ~/public_html

Bu yöntem güncellemelerde dosya kopyalama ihtiyacını azaltır, ancak hosting sağlayıcısı bazen sembolik bağları desteklemez. Symlink desteğini önce küçük bir test ile doğrulayın.

Adım Adım Deployment Süreci

Aşağıdaki adımları sırasıyla uygulayın. Her adımdan sonra panel veya tarayıcı üzerinden çıktıyı kontrol etmek hataları erken yakalamanızı sağlar.

1. Lokalde proje hazırlığı: php artisan optimize:clear komutu ile tüm cache’leri temizleyin. storage/ ve bootstrap/cache/ içindeki gereksiz dosyaları silin.
2. Composer paketlerini production moduna alın: Lokalde composer install --optimize-autoloader --no-dev komutunu çalıştırın. Bu komut dev bağımlılıklarını ayıklar.
3. Dosyaları sıkıştırın: vendor klasörünü dahil edin, node_modules klasörünü ise hariç tutun. node_modules sunucuya hiç yüklenmemeli; gerekirse npm run build ile derlenmiş statik dosyalar yüklenir.
4. FTP veya dosya yöneticisi ile yükleyin: Hosting kontrol panelinin dosya yöneticisi büyük ZIP açma desteği veriyorsa bunu kullanmak FileZilla’dan çok daha hızlıdır.
5. .env dosyasını oluşturun: Sunucuda .env.example‘ı kopyalayıp .env yapın ve canlı veritabanı, mail, app key bilgilerini girin.
6. App key üretin: SSH’tan php artisan key:generate komutunu çalıştırın. SSH yoksa lokalde üretip .env‘e elle yapıştırın.
7. Migration çalıştırın: php artisan migrate --force ile veritabanı tablolarını oluşturun. --force production ortamında onay sormaması için gerekir.
8. Cache’leri ısıtın: php artisan config:cache, php artisan route:cache, php artisan view:cache komutlarını sırayla çalıştırın.

Veritabanı Bağlantısı ve .env Yapılandırması

Shared hosting paketlerinde veritabanı kullanıcı adı genellikle hosting kullanıcı adıyla başlar ve cPanel/Plesk üzerinden ayrı oluşturulur. .env dosyasında veritabanı satırları şu şekilde olmalıdır:

APP_NAME="Site Adı"
APP_ENV=production
APP_KEY=base64:...
APP_DEBUG=false
APP_URL=https://siteadi.com

LOG_CHANNEL=daily
LOG_LEVEL=warning

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=kullanici_dbadi
DB_USERNAME=kullanici_dbkullanici
DB_PASSWORD=guclu_sifre

CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=database

APP_DEBUG production ortamında kesinlikle false olmalıdır. Aksi halde Laravel hata sayfalarında veritabanı şifrenizi ve dosya yollarını ziyaretçilere gösterebilir. Bu, ciddi bir güvenlik açığıdır.

Dosya İzinleri (Permissions)

Laravel’in storage ve bootstrap/cache klasörleri web sunucusu tarafından yazılabilir olmalıdır. Aksi halde “The stream or file could not be opened” hatası alırsınız.

# SSH üzerinden
chmod -R 755 storage bootstrap/cache
chown -R kullanici:kullanici storage bootstrap/cache

Bazı hosting sağlayıcıları 755 yerine 775 ister. Hangi izin gerektiği php artisan storage:link komutu çalıştırıldığında ortaya çıkacaktır. 777 kullanmayın; bu izin herkesin yazma erişimine sahip olduğu anlamına gelir ve güvenlik açığı yaratır.

Performans Optimizasyonu

Shared hosting’de Laravel uygulamasının hızını artırmak için aşağıdaki kontrol listesini sırayla uygulayın:

• Config cache: php artisan config:cache ile config/*.php dosyaları tek bir dosyada birleştirilir.
• Route cache: php artisan route:cache route dosyalarının ayrıştırılma süresini düşürür. Closure içeren route’larda hata verir.
• View cache: php artisan view:cache Blade şablonlarını önceden derler.
• OpCache: Hosting panelinde OpCache modülünü etkinleştirin. PHP performansını ciddi şekilde artırır.
• Composer optimize: composer dump-autoload --optimize classmap’i optimize eder.
• Statik dosya cache: public_html/.htaccess dosyasına tarayıcı cache başlıkları ekleyin.

Yaygın Hatalar ve Çözümleri

500 Internal Server Error

Bu hata genellikle .env dosyasındaki APP_KEY eksikliği veya storage klasörü yazma izninden kaynaklanır. storage/logs/laravel.log dosyasını açıp son satırlara bakın. Log dosyası boşsa geçici olarak APP_DEBUG=true yapıp tarayıcıdan hatayı görebilir, sonra tekrar false‘a alabilirsiniz.

404 Not Found Her Sayfada

Bu sorun çoğunlukla .htaccess dosyasının mod_rewrite kuralının çalışmamasından kaynaklanır. public_html/.htaccess dosyasının içinde Laravel’in standart rewrite bloğu olduğundan emin olun ve hosting üzerinde mod_rewrite’ın aktif olduğunu kontrol edin.

Class Not Found

composer dump-autoload komutunu çalıştırın. SSH yoksa vendor klasörünü silip lokalde tekrar oluşturup yükleyin. Genelde bu hata vendor/composer/autoload_classmap.php dosyasının eksik veya bozuk olmasından kaynaklanır.

419 Page Expired

Bu hata CSRF token sorunudur. SESSION_DRIVER değerini önce file olarak deneyin. storage/framework/sessions klasörünün yazma izinlerini kontrol edin. SESSION_DOMAIN ayarının domain’inizle eşleştiğinden emin olun.

Cron Job ve Scheduler

Laravel’in scheduler özelliğini kullanıyorsanız cron job eklemeniz gerekir. cPanel’de “Cron Jobs” menüsünden şu komutu her dakika çalışacak şekilde ekleyin:

* * * * * cd /home/kullanici/laravel-app && php artisan schedule:run >> /dev/null 2>&1

Bazı hosting paketleri cron job sayısını veya minimum aralığını sınırlar. Plana göre “her dakika” yerine “her 5 dakika” zorunlu olabilir. Queue worker çalıştırmak için ise php artisan queue:work yerine php artisan queue:work --stop-when-empty kullanmak shared hosting’in process limitini aşmayı engeller.

Sonuç

Laravel projesini shared hosting’de yayına almak teknik olarak mümkündür ve doğru yapıldığında küçük-orta ölçekli projeler için ekonomik bir çözümdür. Anahtar noktalar; public klasör yapılandırması, dosya izinleri, .env güvenliği ve önbellek optimizasyonudur. Yayına aldıktan sonra ilk 24-48 saat boyunca storage/logs/laravel.log dosyasını düzenli kontrol etmek olası sorunları erken yakalamanızı sağlar. Trafik beklenenden hızlı arttığında VPS’e geçişi planlayabilir, projeyi büyütürken aynı kod tabanını taşıyabilirsiniz.

Sıkça Sorulan Sorular

Laravel hangi sürüm shared hosting’de daha sorunsuz çalışır?

Laravel 10 ve 11 sürümleri PHP 8.2 desteği nedeniyle pek çok shared hosting paketiyle uyumludur. Laravel 12 için PHP 8.3 önerilir; hosting paketiniz bu sürümü desteklemiyorsa Laravel 11 daha pratik bir tercih olabilir.

Composer SSH erişimi olmadan kullanılabilir mi?

Mümkün ancak zahmetli. Bu durumda vendor klasörünü lokalde oluşturup ZIP olarak sunucuya yüklemeniz gerekir. Her paket güncellemesinde aynı işlemi tekrarlamanız beklenir. Bu nedenle SSH erişimi olan hosting paketleri tercih edilmelidir.

Shared hosting’de Laravel queue çalışır mı?

Çalışır ancak sınırlıdır. QUEUE_CONNECTION=database driver kullanılabilir. queue:work komutu sürekli process gerektirir ve shared hosting’in process limiti nedeniyle kapatılabilir. Çözüm: cron ile her dakika queue:work --stop-when-empty çalıştırmak.

.env dosyasını korumak için ne yapmalıyım?

Mümkünse .env dosyasını public_html dışında, kullanıcı kök dizininde tutun. Eğer dosya public_html içinde kalıyorsa .htaccess‘e <Files .env> Require all denied </Files> bloğu ekleyin ve dosya izinlerini 600 yapın.

Hosting paketim Composer’ı desteklemiyorsa ne yapmalıyım?

İki seçenek var: Birincisi, hosting destek ekibinden SSH ve Composer aktivasyonu istemek. İkincisi, daha geliştirici dostu bir paylaşımlı hosting paketi seçmek. Cloudways gibi managed PaaS çözümleri shared hosting fiyatına yakın bütçeyle Laravel için optimize edilmiş ortam sunar.