PHP Dilinde Öznitelikler (Attributes) Kullanımı: Derinlemesine Bir Kılavuz

Pratik Kullanım Örnekleri

Aşağıdaki örnekler, PHP özniteliklerinin nasıl tanımlandığını ve yansıma API'si (Reflection API) kullanılarak nasıl okunduğunu göstermektedir.

Örnek 1: Basit Bir Yönlendirme (Routing) Özniteliği

Bu örnek, bir web uygulamasında yöntemleri belirli URL yollarına bağlamak için kullanılabilecek basit bir #[Route] özniteliği tanımlar ve ardından bu özniteliği yansıma ile okur.

path = $path;
        $this->methods = $methods;
    }
}

class ApiController
{
    #[Route("/api/users", "GET")]
    public function getUsers(): array
    {
        return ['John Doe', 'Jane Smith'];
    }

    #[Route("/api/users/{id}", "GET")]
    public function getUser(int $id): string
    {
        return "User ID: {$id}";
    }
}

// Öznitelikleri yansıma ile okuma
$reflector = new ReflectionClass(ApiController::class);

foreach ($reflector->getMethods() as $method) {
    echo "Metot: " . $method->getName() . "
";
    foreach ($method->getAttributes(Route::class) as $attribute) {
        $route = $attribute->newInstance(); // Öznitelik sınıfının bir örneğini oluşturur
        echo "  Yol: " . $route->path . ", Metotlar: " . implode(", ", $route->methods) . "
";
    }
}

/* Çıktı:
Metot: getUsers
  Yol: /api/users, Metotlar: GET
Metot: getUser
  Yol: /api/users/{id}, Metotlar: GET
*/

Örnek 2: Validasyon (Doğrulama) Özniteliği ve Hedef Kısıtlaması

Bu örnek, bir özelliğin minimum ve maksimum değerler arasında olmasını gerektiren bir #[Range] özniteliği tanımlar ve bu özniteliği yalnızca özelliklere uygulanacak şekilde kısıtlar.

min = $min;
        $this->max = $max;
    }
}

class Product
{
    #[Range(min: 0, max: 100)]
    public int $stock;

    #[Range(min: 1, max: 999)]
    public float $price;

    public function __construct(int $stock, float $price)
    {
        $this->stock = $stock;
        $this->price = $price;
    }
}

// Öznitelikleri yansıma ile okuma
$reflector = new ReflectionClass(Product::class);

foreach ($reflector->getProperties() as $property) {
    echo "Özellik: " . $property->getName() . "
";
    foreach ($property->getAttributes(Range::class) as $attribute) {
        $range = $attribute->newInstance();
        echo "  Min: " . $range->min . ", Max: " . $range->max . "
";
    }
}

/* Çıktı:
Özellik: stock
  Min: 0, Max: 100
Özellik: price
  Min: 1, Max: 999
*/

Örnek 3: Tekrarlanabilir Öznitelikler

Bu örnek, bir sınıfın birden fazla etiketle işaretlenmesine olanak tanıyan tekrarlanabilir bir #[Tag] özniteliği tanımlar.

name = $name;
    }
}

#[Tag("Veritabanı")]
#[Tag("ORM")]
#[Tag("PHP 8")]
class UserRepository
{
    // ...
}

// Öznitelikleri yansıma ile okuma
$reflector = new ReflectionClass(UserRepository::class);

echo "Sınıf: " . $reflector->getName() . "
";
foreach ($reflector->getAttributes(Tag::class) as $attribute) {
    $tag = $attribute->newInstance();
    echo "  Etiket: " . $tag->name . "
";
}

/* Çıktı:
Sınıf: UserRepository
  Etiket: Veritabanı
  Etiket: ORM
  Etiket: PHP 8
*/

İpuçları ve Önemli Notlar

• Performans Avantajı: Öznitelikler, DocBlock yorumlarının aksine, PHP'nin derleme aşamasında işlenir. Bu, çalışma zamanında ek bir ayrıştırma (parsing) yükü oluşturmadıkları anlamına gelir ve performans açısından DocBlock tabanlı çözümlerden daha verimlidir.

  
  

• Kullanım Alanları: Öznitelikler, framework'lerde (örneğin, yönlendirme, ORM eşlemesi), validasyon kuralı tanımlarında, seri hale getirme (serialization) işlemlerinde, kod üretimi (code generation) araçlarında ve IDE entegrasyonlarında yaygın olarak kullanılır.

  
  

• Yansıma API'si (Reflection API): Özniteliklere erişim yalnızca PHP'nin Yansıma API'si aracılığıyla mümkündür. ReflectionClass::getAttributes(), ReflectionMethod::getAttributes() gibi yöntemler, uygulanan öznitelikleri almanızı sağlar.

  
  

• Ad Alanları (Namespaces): Öznitelik sınıflarını kullanırken, tıpkı diğer sınıflarda olduğu gibi ad alanlarını (namespaces) doğru bir şekilde belirtmeli veya use ifadesiyle içe aktarmalısınız.

  
  

• PHP Sürümü: Öznitelikler özelliği sadece PHP 8.0 ve sonraki sürümlerde mevcuttur. Daha önceki PHP sürümlerinde kullanılmaya çalışıldığında ayrıştırma hatasına neden olur.

  
  

• Constructor Bağımsız Değişkenleri: Öznitelik sınıflarının constructor'ları, tip ipuçları (type hints) ile tanımlanan bağımsız değişkenleri kabul edebilir. Bu, özniteliğe geçirilen değerlerin tip güvenliğini sağlar.

  
  

• Sözdizimi Esnekliği: Öznitelikler, tek bir satırda veya birden fazla satıra yayılarak tanımlanabilir, bu da kod okunabilirliğini artırır.

  
  

  softmush.com