PHP'de Namespace, Composer ve Otomatik Yükleme (PSR-4)

Küçük bir projede sınıflar tek tek dahil edilebilir. Dosya sayısı arttıkça bu yöntem iki sorun üretir: hangi dosyanın nerede dahil edildiği takip edilemez hale gelir ve farklı kütüphanelerdeki aynı adlı sınıflar çakışır. Ad alanları ikinci sorunu, otomatik yükleme birincisini çözer.

Bu bölümde ad alanı tanımı, PSR-4 eşlemesi, Composer ile bağımlılık yönetimi ve sürüm aralıklarının anlamı ele alınıyor.

Ad alanı tanımlamak

Ad alanı, sınıf adının önüne eklenen bir öneki tanımlar. Dosyanın en üstünde bir kez bildirilir ve o dosyadaki tüm tanımları kapsar.

namespace Uygulama\Siparis;

use Uygulama\Odeme\OdemeSaglayici;
use Uygulama\Odeme\Hata\YetersizBakiye as BakiyeHatasi;   // takma ad

final class SiparisServisi
{
    public function __construct(private readonly OdemeSaglayici $odeme) {}
}

Ad alanı içindeyken genel ad alanındaki fonksiyon ve sınıflara erişmek için başa ters eğik çizgi konur. PHP fonksiyonlarda önce geçerli ad alanına, sonra genel ad alanına bakar; sınıflarda ise bu geri dönüş yoktur, bu yüzden use bildirimi ya da tam ad gerekir.

namespace Uygulama\Metin;

function strlen(string $s): int { return 0; }   // aynı adda yerel fonksiyon

echo strlen('abc');    // 0  - yerel fonksiyon çağrılır
echo \strlen('abc');   // 3  - genel ad alanındaki fonksiyon

$tarih = new \DateTimeImmutable();   // sınıflarda tam ad ya da use gerekir

PSR-4 ve otomatik yükleme

PSR-4, ad alanı ile dizin yapısı arasında bire bir eşleme kurar. Bir sınıf ilk kez kullanıldığında yükleyici, ad alanından dosya yolunu hesaplar ve dosyayı dahil eder. Böylece dahil etme satırları tamamen ortadan kalkar.

{
  "name": "bugrahan/ornek",
  "require": {
    "php": ">=8.4"
  },
  "autoload": {
    "psr-4": {
      "Uygulama\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Uygulama\\Test\\": "tests/"
    }
  }
}

Bu eşlemede Uygulama\Siparis\SiparisServisi sınıfı src/Siparis/SiparisServisi.php dosyasında aranır. Dosya adı sınıf adıyla birebir aynı olmalıdır; büyük küçük harf farkı Linux sunucularda hataya yol açar, geliştirme makinesinde ise fark edilmeyebilir.

require __DIR__ . '/vendor/autoload.php';   // tek dahil etme satırı

$servis = new Uygulama\Siparis\SiparisServisi($saglayici);

Fonksiyon ve sabit içe aktarımı

use bildirimi yalnızca sınıflar için değil, fonksiyon ve sabitler için de kullanılır. Aynı ad alanından birden fazla tanım alınacaksa gruplu yazım tercih edilir; böylece dosya başındaki bildirim listesi kısalır.

use function Uygulama\Metin\{slug, kisalt};
use const Uygulama\Ayar\AZAMI_BOYUT;
use Uygulama\Siparis\{SiparisServisi, Model\Siparis};

echo slug('Kaz Dağları');

İçe aktarım bildirimleri yalnızca bulundukları dosyayı etkiler ve çalışma zamanında bir maliyet oluşturmaz; derleme aşamasında ad çözümlemesi yapılır.

Otomatik yükleme nasıl çalışır

Otomatik yükleme, tanımsız bir sınıfa ilk kez erişildiğinde çalışan bir geri çağırma düzenidir. Composer bu düzeni hazır kurar, ancak temeli birkaç satırla gösterilebilecek kadar basittir.

spl_autoload_register(static function (string $sinif): void {
    $onEk = 'Uygulama\\';
    $kok = __DIR__ . '/src/';

    if (!str_starts_with($sinif, $onEk)) {
        return;                       // bu yükleyicinin sorumluluğunda değil
    }

    $gorece = substr($sinif, strlen($onEk));
    $yol = $kok . str_replace('\\', '/', $gorece) . '.php';

    if (is_file($yol)) {
        require $yol;
    }
});

Birden fazla yükleyici kayıtlı olabilir ve sınıf bulunana kadar sırayla denenir. Bu yüzden her yükleyici, sorumlu olmadığı ad alanlarında sessizce geri dönmelidir. Kendi yükleyicisini yazmak öğrenme amacıyla yararlıdır; üretimde Composer tarafından üretilen yükleyici tercih edilir.

Composer ile bağımlılık yönetimi

Composer, projenin ihtiyaç duyduğu paketleri ve bunların ihtiyaç duyduğu diğer paketleri çözerek kurar. Kurulan sürümler kilit dosyasına yazılır ve tüm ortamlarda aynı sürümlerin kullanılması sağlanır.

composer require monolog/monolog          # paket ekler
composer require --dev phpunit/phpunit    # yalnızca geliştirme ortamı
composer install                          # kilit dosyasındaki sürümleri kurar
composer update monolog/monolog           # yalnızca belirtilen paketi yükseltir
composer audit                            # bilinen güvenlik açıklarını listeler

Üretim sunucusunda install komutu kullanılır, update kullanılmaz. Aradaki fark önemlidir: birincisi kilit dosyasındaki sürümleri kurar, ikincisi ise sürüm aralığına uyan en yeni sürümlere yükseltir ve kilit dosyasını değiştirir. Kilit dosyası sürüm denetimine dahil edilmelidir.

composer install --no-dev --optimize-autoloader   # üretim kurulumu

Paketleri değerlendirirken bakım durumu, son sürüm tarihi ve açık sorun sayısı incelenmelidir. Küçük bir işi yapan bir paket için onlarca alt bağımlılık getiren bir kütüphane kurmak, ilerideki yükseltmeleri güçleştirir. Birkaç satırla çözülebilecek işler için bağımlılık eklenmemesi genel bir ölçüttür.

Üretimde geliştirme bağımlılıkları kurulmaz ve yükleyici sınıf eşlemesi önceden üretilir. İkinci seçenek, her sınıf araması için dosya sistemine gidilmesini engellediği için istek süresini ölçülebilir biçimde düşürür.

Sürüm aralıkları

Sürüm numarası üç bölümden oluşur: ana, ikincil ve yama. Anlamsal sürümleme kuralına göre yalnızca ana sürüm değiştiğinde geriye dönük uyumluluk bozulur. Aralık işaretleri bu kurala dayanır.

• ^2.3: 2.3 ve üzeri, 3.0 altı. En yaygın kullanılan aralıktır.
• ~2.3: 2.3 ve üzeri, 2.4 altı. Yalnızca yama sürümlerine izin verir.
• 2.3.*: yama sürümlerini serbest bırakır, ikincil sürümü sabitler.
• 2.3.1: tam sabitleme. Yalnızca sorunlu paketlerde tercih edilir.

Bağımlılıkların düzenli yükseltilmesi, birikmiş yükseltmeleri tek seferde yapmaktan çok daha ucuzdur. Ana sürüm atlamalarında değişiklik notlarının okunması ve testlerin çalıştırılması gerekir.

Kendi kodunu paket gibi düzenlemek

Ad alanı yapısı, uygulamanın modüllerini de ayırmak için kullanılır. Her modülün kendi ad alanı olması, bağımlılık yönünün gözle görülür hale gelmesini sağlar: sipariş modülü ödeme modülünü kullanabilir, tersi olmamalıdır.

src/
  Siparis/
    SiparisServisi.php
    Model/Siparis.php
    Depo/SiparisDeposu.php
  Odeme/
    OdemeSaglayici.php
    SanalPos.php
  Ortak/
    Saat.php

Bu ayrım ileride bir modülün ayrı bir pakete ya da ayrı bir servise taşınmasını da kolaylaştırır. Sınırların kod düzeyinde belirgin olması, taşıma kararı verildiğinde işin büyük bölümünün zaten yapılmış olması anlamına gelir.

Kontrol listesi

• Tüm sınıflar PSR-4 eşlemesine uygun dizin ve dosya adlarında.
• Dosya adlarında büyük küçük harf, sınıf adıyla birebir aynı.
• composer.lock sürüm denetimine dahil.
• Üretim kurulumunda --no-dev ve yükleyici iyileştirmesi kullanılıyor.
• Geliştirme araçları require-dev altında tanımlı.
• Bağımlılıklar düzenli olarak composer audit ile denetleniyor.
• Modüller arası bağımlılık yönü tek taraflı.

İlgili yazılar

• Framework mü saf PHP mi: bağımlılık kararı
• Modüler yapı ile servis ayrımı arasındaki karar
• Arayüzlerle bağımlılık yönünü belirlemek

PHP eğitim serisi

Bu yazı, temel sözdiziminden üretim ortamına kadar ilerleyen 25 bölümlük serinin bir parçası. Bölümler sırayla okunacak biçimde hazırlandı, ancak her biri tek başına da kullanılabilir.

Temeller

1. Kurulum ve temel sözdizimi
2. Döngüler ve akış kontrolü
3. Diziler
4. Fonksiyonlar
5. String fonksiyonları
6. Süper globaller
7. Form işleme
8. Dosya işlemleri

Dilin ayrıntıları

9. Tip sistemi ve strict_types
10. Hata ve istisna yönetimi
11. Düzenli ifadeler
12. Tarih ve saat işlemleri

Nesne yönelimli PHP

13. Sınıf ve nesne
14. Kalıtım, arayüz ve trait
15. Statik üyeler, sabitler ve enum
16. Namespace, Composer ve autoload (bu yazı)

Veri ve güvenlik

17. PDO ile veritabanı işlemleri
18. Oturum yönetimi ve kimlik doğrulama
19. Güvenli çıktı ve XSS
20. JSON ile veri değişimi

Dış dünya ve üretim

21. cURL ile dış API çağırma
22. Kendi REST API'ni yazmak
23. PHPUnit ile birim test
24. Hata ayıklama ve performans ölçümü
25. Üretime alma ve güvenlik