attributes.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 9155d793178b5fcd5131b734cd174fecc34c1ae6 Maintainer: nilgun Status: ready -->
 <chapter xml:id="language.attributes" xmlns="http://docbook.org/ns/docbook">
  <title>Öznitelikler</title>
  <sect1 xml:id="language.attributes.overview">
   <title>Özniteliklere giriş</title>
   <?phpdoc print-version-for="attributes"?>

   <para>
    Öznitelikler, koddaki bildirimlerin üzerine yapılandırılmış, makine
    tarafından okunabilir meta veri bilgilerinin eklenmesini sağlar:
    Sınıflar, yöntemler, işlevler, bağımsız değişkenler, özellikler ve sınıf
    sabitleri bir özniteliğin hedefi olabilir. Özniteliklerle tanımlanan
    meta veriler daha sonra <link linkend="book.reflection">Yansıtma
    Arayüzleri</link> kullanılarak çalışma anında incelenebilir.
    Bu nedenle öznitelikler, doğrudan koda gömülmüş bir yapılandırma dili
    olarak düşünülebilir.
   </para>

   <para>
    Özniteliklerle, bir özelliğin kapsamlı gerçeklenimi ile bir
    uygulamadaki somut kullanımı ayrıştırılabilir. Bir bakıma arayüzler,
    gerçeklenimleri ile karşılaştırılabilir. Ancak arayüzlerin ve
    gerçeklenimlerin kodla ilgili olduğu yerlerde öznitelikler, ek bilgi
    ve yapılandırmaya küçük açıklamalar eklemekle ilgilidir. Arayüzler
    sınıflarla gerçeklenebilir, ancak öznitelikler ek olarak yöntemler,
    işlevler, bağımsız değişkenler, özellikler ve sınıf sabitleri üzerinde de
    bildirilebilir. Bu nedenle arayüzlerden daha esnektir.
   </para>

   <para>
    Öznitelik kullanımına basit bir örnek, öznitelikleri kullanmak için isteğe
    bağlı yöntemlere sahip bir arayüzü dönüştürmektir.
    <literal>ActionHandler</literal> arayüzünün bir uygulamadaki bir işlemi
    yerine getirdiğini ve bu arayüzün bazı gerçeklenimlerinin ilklendirilmesi
    gerekirken diğerlerine bunun gerekmediğini varsayalım.
    <literal>ActionHandler</literal> arayüzünü gerçekleyen tüm sınıfların
    <literal>setUp()</literal> yöntemini gerçeklemesi gerekirken, bunu
    yapmak yerine, onun yerini alabilecek bir öznitelik kullanılabilir.
    Bu yaklaşımın tek yararı, öznitelliğin birkaç kez kullanabilmesidir.
   </para>

   <example>
    <title>- Bir arayüzün isteğe bağlı yöntemlerini özniteliklerle gerçeklemek
    </title>
     <programlisting role="php">
<![CDATA[
<?php
interface ActionHandler
{
    public function execute();
}

#[Attribute]
class SetUp {}

class CopyFile implements ActionHandler
{
    public string $fileName;
    public string $targetDirectory;

    #[SetUp]
    public function fileExists()
    {
        if (!file_exists($this->fileName)) {
            throw new RuntimeException("Dosya yok");
        }
    }

    #[SetUp]
    public function targetDirectoryExists()
    {
        if (!file_exists($this->targetDirectory)) {
            mkdir($this->targetDirectory);
        } elseif (!is_dir($this->targetDirectory)) {
            throw new RuntimeException("Hedef dizin $this->targetDirectory bir dizin değil");
        }
    }

    public function execute()
    {
        copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
    }
}

function executeAction(ActionHandler $actionHandler)
{
    $reflection = new ReflectionObject($actionHandler);

    foreach ($reflection->getMethods() as $method) {
        $attributes = $method->getAttributes(SetUp::class);

        if (count($attributes) > 0) {
            $methodName = $method->getName();

            $actionHandler->$methodName();
        }
    }

    $actionHandler->execute();
}

$copyAction = new CopyFile();
$copyAction->fileName = "/tmp/foo.jpg";
$copyAction->targetDirectory = "/home/user";

executeAction($copyAction);
]]>
     </programlisting>
    </example>
  </sect1>

  <sect1 xml:id="language.attributes.syntax">
   <title>Öznitelik Sözdizimi</title>

   <para>
    Öznitelik sözdizimi çeşitli parçalardan oluşur. İlk olarak, öznitelik
    bildirimi her zaman bir #[ ile başlar ve bir ] biter. İçeride, virgüllerle
    ayrılmış bir veya daha fazla öznitelik bulunur. Öznitelik adı,
    <link linkend="language.namespaces.basics">İsim alanlarının kullanımı:
    Temeller</link> bölümünde açıklandığı gibi nitelenmemiş, nitelenmiş
    veya tam nitelenmiş olabilir. Özniteliğin bağımsız değişkenleri isteğe bağlıdır,
    ancak normalde parantez () içine alınır. Özniteliklerin bağımsız değişkenleri
    yalnızca değişmez değerler veya sabit ifadeleri olabilir. Hem konumsal
    hem de isimli bağımsız değişken sözdizimi kullanılabilir.
   </para>

   <para>
    Öznitelik adları ve bağımsız değişkenleri bir sınıfa çözümlenir, eğer
    özniteliğin bir örneği yansıtma arayüzü aracılığıyla istenirse
    bağımsız değişkenler kurucuya iletilir. Her öznitelik için böyle bir
    sınıf kullanılmalıdır.
   </para>

   <example>
    <title>- Öznitelik Sözdizimi</title>

    <programlisting role="php">
<![CDATA[
<?php
// a.php
namespace MyExample;

use Attribute;

#[Attribute]
class MyAttribute
{
    const VALUE = 'value';

    private $value;

    public function __construct($value = null)
    {
        $this->value = $value;
    }
}

// b.php

namespace Another;

use MyExample\MyAttribute;

#[MyAttribute]
#[\MyExample\MyAttribute]
#[MyAttribute(1234)]
#[MyAttribute(value: 1234)]
#[MyAttribute(MyAttribute::VALUE)]
#[MyAttribute(array("key" => "value"))]
#[MyAttribute(100 + 200)]
class Thing
{
}

#[MyAttribute(1234), MyAttribute(5678)]
class AnotherThing
{
}
]]>
    </programlisting>
   </example>
  </sect1>


  <sect1 xml:id="language.attributes.reflection">
   <title>Özniteliklerin Yansıtma Arayüzü ile Okunması</title>

   <para>
    Sınıflar, yöntemler, işlevler, bağımsız değişkenler, özellikler ve sınıf
    sabitlerinden özniteliklere erişmek için kullanılan yansıtma arayüzü, ilgili
    Reflection nesnelerinin her birine <function>getAttributes</function>
    yöntemini sağlar. Bu yöntem, öznitelik adı, bağımsız değişkenler ve temsil
    edilen özniteliğin bir örneğini örneklendirmek için sorgulanabilen
    <classname>ReflectionAttribute</classname> örneklerini içeren bir
    dizi döndürür.
   </para>

   <para>
    Yansıtılan öznitelik temsilinin gerçek örnekten bu şekilde ayrılması,
    programcının eksik öznitelik sınıfları, yanlış yazılmış veya eksik
    bağımsız değişkenlerle ilgili hataları elde etme konusundaki denetimini artırır.
    Öznitelik sınıfının nesneleri, yalnızca
    <function>ReflectionAttribute::newInstance</function> çağrıldıktan sonra
    başlatılırsa bağımsız değişkenlerin doğru eşleşmesi sağlanır, daha önce değil.
   </para>

   <example>
    <title>- Özniteliklerin Yansıtma Arayüzü kullanılarak Okunması</title>

    <programlisting role="php">
<![CDATA[
<?php

#[Attribute]
class MyAttribute
{
    public $value;

    public function __construct($value)
    {
        $this->value = $value;
    }
}

#[MyAttribute(value: 1234)]
class Thing
{
}

function dumpAttributeData($reflection) {
    $attributes = $reflection->getAttributes();

    foreach ($attributes as $attribute) {
       var_dump($attribute->getName());
       var_dump($attribute->getArguments());
       var_dump($attribute->newInstance());
    }
}

dumpAttributeData(new ReflectionClass(Thing::class));
/*
string(11) "MyAttribute"
array(1) {
  ["value"]=>
  int(1234)
}
object(MyAttribute)#3 (1) {
  ["value"]=>
  int(1234)
}
*/

]]>
    </programlisting>
   </example>

   <para>
    Yansıtma örneğindeki tüm öznitelikleri yinelemek yerine, yalnızca belirli
    bir öznitelik sınıfı, sınıfın ismi bağımsız değişken olarak aktarılarak okunabilir.
   </para>

   <example>
    <title>- Yansıtma Arayüzünü kullanarak istenen özniteliklerin okunması</title>

    <programlisting role="php">
<![CDATA[
<?php

function dumpMyAttributeData($reflection) {
    $attributes = $reflection->getAttributes(MyAttribute::class);

    foreach ($attributes as $attribute) {
       var_dump($attribute->getName());
       var_dump($attribute->getArguments());
       var_dump($attribute->newInstance());
    }
}

dumpMyAttributeData(new ReflectionClass(Thing::class));
]]>
     </programlisting>
    </example>
  </sect1>

  <sect1 xml:id="language.attributes.classes">
   <title>Öznitelik Sınıflarının Bildirimi</title>

   <para>
    Zorunlu olmamakla birlikte, her öznitelik için gerçek bir sınıfın
    oluşturulması önerilir. En basit durumda, bir use ifadesiyle küresel isim
    alanından içe aktarılabilen #[Attribute] özniteliğinin bildirimi için
    yalnızca boş bir sınıfa ihtiyaç vardır.
   </para>

  <example>
   <title>- Basit Öznitelik sınıfı</title>

   <programlisting role="php">
<![CDATA[
<?php

namespace Example;

use Attribute;

#[Attribute]
class MyAttribute
{
}
]]>
   </programlisting>
  </example>

  <para>
   Bir özniteliğin atanabileceği bildirim türünü kısıtlamak için, #[Attribute]
   bildirimine ilk bağımsız değişken olarak bir bit maskesi aktarılabilir.
  </para>

  <example>
   <title>- Özniteliklerin kullanılabileceği yerleri kısıtlamak için hedef
    belirtiminin kullanımı</title>

   <programlisting role="php">
<![CDATA[
<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
class MyAttribute
{
}
]]>
    </programlisting>

    <para>
     <classname>MyAttribute</classname> sınıfının başka bir türde
     bildirilmesi, <function>ReflectionAttribute::newInstance</function>
     çağrısı sırasında bir istisna oluşmasına sebep olur.
    </para>
   </example>

   <para>Şu hedefler belirtilebilir:</para>

   <simplelist>
    <member><constant>Attribute::TARGET_CLASS</constant></member>
    <member><constant>Attribute::TARGET_FUNCTION</constant></member>
    <member><constant>Attribute::TARGET_METHOD</constant></member>
    <member><constant>Attribute::TARGET_PROPERTY</constant></member>
    <member><constant>Attribute::TARGET_CLASS_CONSTANT</constant></member>
    <member><constant>Attribute::TARGET_PARAMETER</constant></member>
    <member><constant>Attribute::TARGET_ALL</constant></member>
   </simplelist>

   <para>
    Öntanımlı olarak, bir öznitelik her bildirimde yalnızca bir kere
    kullanılabilir. Özniteliğin bildirimlerde yinelenebilir olması isteniyorsa,
    <literal>#[Attribute]</literal> bildiriminde bit maskesinin bir parçası
    olarak belirtilmelidir.
   </para>

   <example>
    <title>- Özniteliğin bir bildirimle defalarca kullanılabilmesi için
    IS_REPEATABLE kullanımı</title>

    <programlisting role="php">
<![CDATA[
<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
class MyAttribute
{
}
]]>
    </programlisting>

   </example>
  </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->