Tracy'ye Başlarken
******************

<div class=perex>

Tracy kütüphanesi, PHP programcısının günlük olarak kullandığı yararlı bir yardımcıdır. Size şu konularda yardımcı olur:

- hataları hızla tespit etme ve düzeltme
- hataları günlüğe kaydetme
- değişkenleri yazdırma
- betiklerin ve veritabanı sorgularının süresini ölçme
- bellek gereksinimlerini izleme

</div>


PHP, geliştiricilere önemli ölçüde özgürlük verdiği için tespit edilmesi zor hatalar oluşturmak için mükemmel bir dildir. Bu nedenle hata ayıklama aracı Tracy daha da değerlidir. PHP için teşhis araçları arasında mutlak zirveyi temsil eder.

Bugün Tracy ile ilk kez karşılaşıyorsanız, hayatınızın Tracy'den öncesi ve sonrası olarak ikiye ayrılacağına inanın. Daha iyi kısma hoş geldiniz!


Kurulum
=======

Tracy'yi kurmanın en iyi yolu [en son paketi indirmek](https://github.com/nette/tracy/releases) veya Composer kullanmaktır:

```shell
composer require tracy/tracy
```

Ayrıca tüm paketi [tracy.phar |https://github.com/nette/tracy/releases] dosyası olarak da indirebilirsiniz.


Kullanım
========

Tracy'yi programın başlangıcında, herhangi bir çıktı gönderilmeden önce mümkün olan en kısa sürede `Tracy\Debugger::enable()` metodunu çağırarak etkinleştiririz:

```php
use Tracy\Debugger;

require 'vendor/autoload.php'; // veya tracy.phar

Debugger::enable();
```

Sayfada fark edeceğiniz ilk şey, sağ alt köşedeki Tracy Bar'dır. Görmüyorsanız, Tracy'nin üretim modunda çalıştığı anlamına gelebilir. Tracy, güvenlik nedenleriyle yalnızca localhost'ta görünür. Çalışıp çalışmadığını test etmek için, `Debugger::enable(Debugger::Development)` parametresini kullanarak geçici olarak geliştirme moduna geçirebilirsiniz.


Tracy Bar
=========

Tracy Bar, sayfanın sağ alt köşesinde görüntülenen kayan bir paneldir. Fare ile hareket ettirebiliriz ve sayfa yeniden yüklendikten sonra konumunu hatırlar.

[* tracy-bar.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

Tracy Bar'a başka yararlı paneller eklenebilir. Birçoğunu [eklentilerde |https://componette.org] bulabilir veya hatta [kendiniz yazabilirsiniz |extensions].

Tracy Bar'ı görüntülemek istemiyorsanız, şunu ayarlayın:

```php
Debugger::$showBar = false;
```


Hataların ve İstisnaların Görselleştirilmesi
============================================

PHP'nin hataları nasıl bildirdiğini kesinlikle iyi biliyorsunuz: sayfanın kaynak koduna şöyle bir şey yazar:

/--pre .{font-size: 90%}
<b>Parse error</b>:  syntax error, unexpected '}' in <b>HomePresenter.php</b> on line <b>15</b>
\--

veya yakalanmamış bir istisna durumunda:

/--pre .{font-size: 90%}
<b>Fatal error</b>:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/Forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/Presentation/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presentation\Sign\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in <b>/sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php</b> on line <b>100</b><br />
\--

Böyle bir çıktıda gezinmek pek kolay değildir. Tracy'yi açarsak, hata veya istisna tamamen farklı bir biçimde görüntülenir:

[* tracy-exception.webp .{url:-} *]

Hata mesajı kelimenin tam anlamıyla bağırıyor. Hatanın meydana geldiği vurgulanmış satırla birlikte kaynak kodunun bir bölümünü ve *Call to undefined method Nette\Http\User::isLogedIn()* bilgisini görüyoruz, bu da hatanın ne olduğunu açıkça açıklıyor. Ayrıca tüm sayfa canlıdır, daha fazla ayrıntıya tıklayabiliriz. [Deneyin |https://nette.github.io/tracy/tracy-exception.html].

Ve biliyor musunuz? Bu şekilde ölümcül hataları bile yakalar ve görüntüler. Herhangi bir eklenti yüklemeye gerek kalmadan.

[* tracy-error.webp .{url:-} *]

Değişken adındaki bir yazım hatası veya var olmayan bir dosyayı açma girişimi gibi hatalar, E_NOTICE veya E_WARNING seviyesinde mesajlar üretir. Bunlar sayfa grafiğinde kolayca gözden kaçabilir, hatta hiç görünmeyebilir (sayfa koduna bakmadıkça).

[* tracy-notice2.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

Veya hatalarla aynı şekilde görüntülenebilirler:

```php
Debugger::$strictMode = true; // tüm hataları göster
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // kullanımdan kaldırma bildirimleri dışındaki tüm hatalar
```

[* tracy-notice.webp .{url:-} *]

Not: Tracy etkinleştirildikten sonra hata raporlama seviyesini E_ALL olarak değiştirir. Bu değeri değiştirmek isterseniz, `enable()` çağrısından sonra yapın.


Geliştirme vs Üretim Modu
=========================

Gördüğünüz gibi, Tracy oldukça konuşkan, bu geliştirme ortamında takdir edilebilir, ancak üretim sunucusunda tam bir felakete neden olur. Orada hiçbir hata ayıklama bilgisi yazdırılmamalıdır. Bu nedenle Tracy **ortamın otomatik tespiti** özelliğine sahiptir ve örnek canlı bir sunucuda çalıştırılırsa, hata görüntülenmek yerine günlüğe kaydedilir ve ziyaretçi yalnızca kullanıcı dostu bir mesaj görür:

[* tracy-error2.webp .{url:-} *]

Üretim modu, [dump() |dumper] kullanarak gönderdiğimiz tüm hata ayıklama bilgilerinin ve tabii ki PHP tarafından üretilen tüm hata mesajlarının görüntülenmesini engeller. Bu nedenle, kodda bazı `dump($obj)` unutmuşsanız endişelenmenize gerek yok, üretim sunucusunda hiçbir şey yazdırılmaz.

Modun otomatik tespiti nasıl çalışır? Uygulama localhost'ta (yani IP adresi `127.0.0.1` veya `::1`) çalıştırıldığında ve bir proxy mevcut olmadığında (yani HTTP başlığı olmadığında) mod geliştirme modudur. Aksi takdirde üretim modunda çalışır.

Geliştirme modunu diğer durumlarda da etkinleştirmek istersek, örneğin belirli bir IP adresinden erişen programcılar için, bunu `enable()` metodunun parametresi olarak belirtiriz:

```php
Debugger::enable('23.75.345.200'); // IP adresleri dizisi de belirtilebilir
```

IP adresini bir çerezle birleştirmenizi kesinlikle öneririz. `tracy-debug` çerezine gizli bir belirteç, örneğin `secret1234` kaydederiz ve bu şekilde geliştirme modunu yalnızca belirli bir IP adresinden erişen ve çerezde belirtilen belirtece sahip olan programcılar için etkinleştiririz:

```php
Debugger::enable('secret1234@23.75.345.200');
```

Geliştirme/üretim modunu ayrıca `Debugger::Development` veya `Debugger::Production` sabitini `enable()` metodunun parametresi olarak kullanarak doğrudan ayarlayabiliriz.

.[note]
Nette Framework kullanıyorsanız, [onun için modu nasıl ayarlayacağınıza |application:bootstrapping#Geliştirme vs Üretim Modu] bakın ve bu daha sonra Tracy için de kullanılacaktır.


Hata Günlüklemesi
=================

Üretim modunda, Tracy tüm hataları ve yakalanan istisnaları otomatik olarak bir metin günlüğüne kaydeder. Günlüklemenin gerçekleşebilmesi için, günlükleme dizinine mutlak yolu `$logDirectory` değişkenine ayarlamamız veya `enable()` metodunun ikinci parametresi olarak iletmemiz gerekir:

```php
Debugger::$logDirectory = __DIR__ . '/log';
```

Hata günlüklemesi son derece yararlıdır. Uygulamanızın tüm kullanıcılarının aslında ücretsiz olarak hata bulmada mükemmel bir iş çıkaran beta testçileri olduğunu hayal edin ve onların değerli raporlarını fark edilmeden çöp kutusuna atarak aptallık yapmış olursunuz.

Kendi mesajımızı veya yakaladığınız bir istisnayı günlüğe kaydetmemiz gerekirse, bunun için `log()` metodunu kullanırız:

```php
Debugger::log('Beklenmedik bir hata oluştu'); // metin mesajı

try {
	kritikOperasyon();
} catch (Exception $e) {
	Debugger::log($e); // istisna da günlüğe kaydedilebilir
	// veya
	Debugger::log($e, Debugger::ERROR); // e-posta bildirimi de gönderir
}
```

Tracy'nin `E_NOTICE` veya `E_WARNING` gibi PHP hatalarını ayrıntılı bilgilerle (HTML raporu) günlüğe kaydetmesini istiyorsanız, `Debugger::$logSeverity` ayarlayın:

```php
Debugger::$logSeverity = E_NOTICE | E_WARNING;
```

Gerçek bir profesyonel için hata günlüğü önemli bir bilgi kaynağıdır ve her yeni hatadan hemen haberdar olmak ister. Tracy bu konuda ona yardımcı olur, çünkü günlükteki yeni bir kayıt hakkında e-posta ile bilgi verebilir. E-postaların nereye gönderileceğini `$email` değişkeni ile belirleriz:

```php
Debugger::$email = 'admin@example.com';
```

Tüm Nette Framework'ü kullanıyorsanız, bunu ve diğer ayarları [yapılandırma dosyasında |nette:configuring] ayarlayabilirsiniz.

Ancak e-posta gelen kutunuzu doldurmamak için her zaman **yalnızca bir mesaj** gönderir ve `email-sent` adlı bir dosya oluşturur. Geliştirici, e-posta bildirimini aldıktan sonra günlüğü kontrol eder, uygulamayı düzeltir ve izleme dosyasını siler, böylece e-posta gönderimi yeniden etkinleştirilir.


Düzenleyicide Açma
==================

Hata sayfası görüntülendiğinde, dosya adlarına tıklayabilirsiniz ve bunlar düzenleyicinizde ilgili satırda imleçle açılır. Ayrıca dosyalar oluşturabilir (eylem `create file`) veya içlerindeki hataları düzeltebilirsiniz (eylem `fix it`). Bunun çalışması için [tarayıcıyı ve sistemi yapılandırmanız |open-files-in-ide] yeterlidir.


Desteklenen PHP Sürümleri
=========================

| Tracy     | PHP ile uyumlu
|-----------|-------------------
| Tracy 2.10 – 3.0 | PHP 8.0 – 8.4
| Tracy 2.9 | PHP 7.2 – 8.2
| Tracy 2.8 | PHP 7.2 – 8.1
| Tracy 2.6 – 2.7 | PHP 7.1 – 8.0
| Tracy 2.5 | PHP 5.4 – 7.4
| Tracy 2.4 | PHP 5.4 – 7.2

Son yama sürümü için geçerlidir.


Portlar
=======

Bu, diğer frameworkler ve CMS'ler için resmi olmayan portların bir listesidir:

- [Drupal 7](https://www.drupal.org/project/traced)
- Laravel framework: [recca0120/laravel-tracy](https://github.com/recca0120/laravel-tracy), [whipsterCZ/laravel-tracy](https://github.com/whipsterCZ/laravel-tracy)
- [OpenCart](https://github.com/BurdaPraha/oc_tracy)
- [ProcessWire CMS/CMF](https://github.com/adrianbj/TracyDebugger)
- [Slim Framework](https://github.com/runcmf/runtracy)
- Symfony framework: [kutny/tracy-bundle](https://github.com/kutny/tracy-bundle), [VasekPurchart/Tracy-Blue-Screen-Bundle](https://github.com/VasekPurchart/Tracy-Blue-Screen-Bundle)
- [Wordpress](https://github.com/ktstudio/WP-Tracy)