Nette Documentation Preview

syntax 
Zaczynając od Tracy
*******************

<div class=perex>

Biblioteka Tracy, która została udomowiona pod nazwą *Laddy*, to przydatny na co dzień pomocnik programisty PHP. To ci pomoże:

- szybkie wykrywanie i naprawianie błędów
- błędy w dzienniku
- wyciągnąć zmienne
- mierzyć czas wykonywania skryptów i zapytań do bazy danych
- monitorować wymagania dotyczące pamięci

</div>


PHP jest językiem z wyboru do siekania trudnych do wykrycia błędów, ponieważ daje programistom dużą swobodę. Jeszcze cenniejsze jest narzędzie do debugowania Tracy. Wśród narzędzi diagnostycznych PHP to absolutna czołówka.

Jeśli dziś po raz pierwszy spotykasz się z Biedronką, to lepiej uwierz, że Twoje życie zacznie się dzielić na to przed Biedronką i to z Biedronką. Witamy w dobrej części!


Instalacja .[#toc-installation-and-requirements]
================================================

Najlepszym sposobem na zainstalowanie Tracy jest [pobranie najnowszego pakietu](https://github.com/nette/tracy/releases), lub użyty Composer:

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

Możesz również pobrać cały pakiet jako plik [tracy.phar |https://github.com/nette/tracy/releases].


Zastosowanie .[#toc-usage]
==========================

Tracy aktywuje się poprzez wywołanie metody `TracyDebugger::enable()' jak najszybciej na początku programu, przed wysłaniem jakiegokolwiek wyjścia:

```php
use Tracy\Debugger;

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

Debugger::enable();
```

Pierwszą rzeczą, którą zauważysz na stronie, jest pasek Tracy w prawym dolnym rogu. Jeśli go nie widzisz, może to oznaczać, że Tracy działa w trybie produkcyjnym.
Dzieje się tak, ponieważ Tracy jest widoczny tylko na localhost ze względów bezpieczeństwa. Aby przetestować, czy działa, możesz tymczasowo przełączyć go w tryb deweloperski za pomocą parametru `Debugger::enable(Debugger::Development)`.


Tracy Bar .[#toc-tracy-bar]
===========================

Tracy Bar to pływający pasek, który pojawia się w prawym dolnym rogu strony. Można go przesuwać za pomocą myszy i będzie pamiętał swoją pozycję po ponownym załadowaniu strony.

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

Do Tracy Bar można dodać inne przydatne panele. Wiele z nich można znaleźć w [dodatkach |https://componette.org], a nawet [napisać własne |extensions].

Jeśli nie chcesz wyświetlać paska Tracy Bar, ustaw:

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


Wizualizacja błędów i wyjątków .[#toc-visualization-of-errors-and-exceptions]
=============================================================================

Wiesz, jak PHP zgłasza błędy: drukuje coś takiego w kodzie źródłowym strony:

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

lub gdy wyjątek nie zostanie złapany:

/--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/UI/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\UI\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 />
\--

Poruszanie się po takim zestawieniu nie jest łatwe. Jeśli włączysz *Label*, błąd lub wyjątek zostanie wyświetlony w innej formie:

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

Komunikat o błędzie dosłownie krzyczy. Widzimy fragment kodu źródłowego z podświetloną linią, w której wystąpił błąd, a informacja *Call to undefined method `Nette\Security\User::isLoggedIn()` jasno wyjaśnia, na czym polega błąd. Co więcej, cała strona jest na żywo, możemy przeklikać się do większej ilości szczegółów. [Spróbuj |https://nette.github.io/tracy/tracy-exception.html].

I wiesz co? Pozwoli to na wychwycenie i wyświetlenie nawet fatalnych błędów. Bez konieczności instalowania jakichkolwiek rozszerzeń.

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

Błędy takie jak literówka w nazwie zmiennej lub próba otwarcia nieistniejącego pliku generują komunikat poziomu E_NOTICE lub E_WARNING. Można je łatwo przeoczyć w grafice strony, a może nawet w ogóle nie być widoczne (chyba, że patrząc na kod strony).

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

Mogą też być wyświetlane tak jak błędy:

```php
Debugger::$strictMode = true; // pokaż wszystkie błędy
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // wszystkie błędy z wyjątkiem powiadomień deprecate.
```

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

Uwaga: Tracy po aktywacji zmienia poziom raportowania błędów na E_ALL. Jeśli chcesz to zmienić, zrób to po wywołaniu `enable()`.


Tryb deweloperski a produkcyjny .[#toc-development-vs-production-mode]
======================================================================

Jak widać, Tracy jest dość gadatliwy, co można docenić w środowisku deweloperskim, natomiast na serwerze produkcyjnym spowodowałoby to katastrofę. Dzieje się tak dlatego, że nie powinny być tam wyświetlane żadne informacje o debugowaniu. Tracy posiada zatem **automatyczne wykrywanie środowiska** i jeśli przykład zostanie uruchomiony na serwerze produkcyjnym, błąd zostanie zapisany w dzienniku zamiast wyświetlony, a odwiedzający zobaczy jedynie przyjazny dla użytkownika komunikat:

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

Tryb produkcyjny wyłącza wyświetlanie wszystkich informacji o debugowaniu wysyłanych za pomocą [dump() |dumper], a także oczywiście wszystkich komunikatów o błędach generowanych przez PHP. Jeśli więc zapomniałeś o jakimś `dump($obj)` w kodzie, nie musisz się martwić, na serwerze produkcyjnym nic nie zostanie wyświetlone.

Jak działa autodetekcja trybu? Tryb jest rozwojowy, jeśli aplikacja działa na localhost (czyli adres IP `127.0.0.1` lub `::1`) i nie ma proxy (czyli jego nagłówka HTTP). W przeciwnym razie działa w trybie produkcyjnym.

Jeżeli chcesz włączyć tryb development w innych przypadkach, np. dla deweloperów uzyskujących dostęp z określonego adresu IP, możesz go określić jako parametr metody `enable()`:

```php
Debugger::enable('23.75.345.200'); // można również podać tablicę adresów IP
```

Zdecydowanie zalecamy połączenie adresu IP z plikiem cookie. Przechowuj tajny token, np. `secret1234`, w pliku cookie `tracy-debug` i w ten sposób włączaj tryb deweloperski tylko dla deweloperów uzyskujących dostęp z określonego adresu IP, którzy mają wspomniany token w pliku cookie:

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

Możesz również bezpośrednio ustawić tryb deweloperski/produkcyjny za pomocą stałych `Debugger::Development` lub `Debugger::Production` jako parametru metody `enable()`.

.[note]
Jeśli używasz Nette Framework, spójrz na [to |application:bootstrap#Development vs Production Mode], jak [ustawić tryb dla niego |application:bootstrap#Development vs Production Mode], a następnie będzie on również używany dla Tracy.


Rejestrowanie błędów .[#toc-error-logging]
==========================================

W trybie produkcyjnym Tracy automatycznie loguje wszystkie błędy i wyjątki do dziennika tekstowego. Aby logowanie miało miejsce, należy ustawić bezwzględną ścieżkę do katalogu logów w zmiennej `$logDirectory` lub przekazać ją jako drugi parametr metody `enable()`:

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

Rejestrowanie błędów jest niezwykle przydatne. Wyobraź sobie, że wszyscy użytkownicy Twojej aplikacji to tak naprawdę beta testerzy, którzy za darmo wykonują najwyższej klasy pracę polegającą na wyszukiwaniu błędów, a Ty byłbyś głupi, gdybyś wyrzucił ich cenne raporty niepostrzeżenie do kosza na śmieci.

Jeśli musimy zarejestrować niestandardowy raport lub wyjątek złapany przez użytkownika, używamy do tego metody `log()`:

```php
Debugger::log('Wystąpił nieoczekiwany błąd'); // komunikat tekstowy

try {
	kritickaOperace();
} catch (Exception $e) {
	Debugger::log($e); // można również rejestrować wyjątek
	// lub
	Debugger::log($e, Debugger::ERROR); wysyła również powiadomienie e-mail
}
```

Jeśli chcesz, aby Tracy rejestrował błędy PHP jako `E_NOTICE` lub `E_WARNING` ze szczegółowymi informacjami (raport HTML), ustaw `Debugger::$logSeverity`:

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

Dla prawdziwego zawodowca dziennik błędów jest kluczowym źródłem informacji i chce on być natychmiast informowany o każdym nowym błędzie. Ladenka jest w tym względzie bardzo pomocna, gdyż może go informować o nowych wpisach w dzienniku za pomocą poczty elektronicznej. Określamy gdzie mają być wysyłane maile za pomocą zmiennej $email:

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

Jeśli używasz całego Nette Framework, to to i więcej można ustawić w [pliku konfiguracyjnym |nette:configuring].

Jednak aby nie zalać skrzynki mailowej, zawsze wysyła **tylko jedną wiadomość** i tworzy plik `email-sent`. Po otrzymaniu powiadomienia mailowego, deweloper sprawdza log, naprawia aplikację i usuwa plik monitorujący, tym samym ponownie aktywując wysyłanie maili.


Otwieranie w edytorze .[#toc-opening-files-in-the-editor]
=========================================================

Po wyświetleniu strony błędu możesz kliknąć na nazwy plików i otworzą się one w Twoim edytorze z kursorem w odpowiedniej linii. Możesz również tworzyć pliki (akcja `create file`) lub poprawiać w nich błędy (akcja `fix it`). Aby to zadziałało, wystarczy [skonfigurować przeglądarkę i system |open-files-in-ide].


Obsługiwane wersje PHP .[#toc-supported-php-versions]
=====================================================

| Tracy | kompatybilny z PHP
|-----------|-------------------
| Tracy 2.10 – 3.0 | PHP 8.0 – 8.3
| 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

Ważne dla najnowszych wersji poprawek.


Porty .[#toc-ports]
===================

Jest to lista nieoficjalnych portów dla innych frameworków i CMS-ów:

- [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)

Zaczynając od Tracy

Biblioteka Tracy, która została udomowiona pod nazwą Laddy, to przydatny na co dzień pomocnik programisty PHP. To ci pomoże:

  • szybkie wykrywanie i naprawianie błędów
  • błędy w dzienniku
  • wyciągnąć zmienne
  • mierzyć czas wykonywania skryptów i zapytań do bazy danych
  • monitorować wymagania dotyczące pamięci

PHP jest językiem z wyboru do siekania trudnych do wykrycia błędów, ponieważ daje programistom dużą swobodę. Jeszcze cenniejsze jest narzędzie do debugowania Tracy. Wśród narzędzi diagnostycznych PHP to absolutna czołówka.

Jeśli dziś po raz pierwszy spotykasz się z Biedronką, to lepiej uwierz, że Twoje życie zacznie się dzielić na to przed Biedronką i to z Biedronką. Witamy w dobrej części!

Instalacja

Najlepszym sposobem na zainstalowanie Tracy jest pobranie najnowszego pakietu, lub użyty Composer:

composer require tracy/tracy

Możesz również pobrać cały pakiet jako plik tracy.phar.

Zastosowanie

Tracy aktywuje się poprzez wywołanie metody `TracyDebugger::enable()' jak najszybciej na początku programu, przed wysłaniem jakiegokolwiek wyjścia:

use Tracy\Debugger;

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

Debugger::enable();

Pierwszą rzeczą, którą zauważysz na stronie, jest pasek Tracy w prawym dolnym rogu. Jeśli go nie widzisz, może to oznaczać, że Tracy działa w trybie produkcyjnym. Dzieje się tak, ponieważ Tracy jest widoczny tylko na localhost ze względów bezpieczeństwa. Aby przetestować, czy działa, możesz tymczasowo przełączyć go w tryb deweloperski za pomocą parametru Debugger::enable(Debugger::Development).

Tracy Bar

Tracy Bar to pływający pasek, który pojawia się w prawym dolnym rogu strony. Można go przesuwać za pomocą myszy i będzie pamiętał swoją pozycję po ponownym załadowaniu strony.

Do Tracy Bar można dodać inne przydatne panele. Wiele z nich można znaleźć w dodatkach, a nawet napisać własne.

Jeśli nie chcesz wyświetlać paska Tracy Bar, ustaw:

Debugger::$showBar = false;

Wizualizacja błędów i wyjątków

Wiesz, jak PHP zgłasza błędy: drukuje coś takiego w kodzie źródłowym strony:

Parse error:  syntax error, unexpected '}' in HomePresenter.php on line 15

lub gdy wyjątek nie zostanie złapany:

Fatal error:  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/UI/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\UI\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 /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100

Poruszanie się po takim zestawieniu nie jest łatwe. Jeśli włączysz Label, błąd lub wyjątek zostanie wyświetlony w innej formie:

Komunikat o błędzie dosłownie krzyczy. Widzimy fragment kodu źródłowego z podświetloną linią, w której wystąpił błąd, a informacja *Call to undefined method Nette\Security\User::isLoggedIn() jasno wyjaśnia, na czym polega błąd. Co więcej, cała strona jest na żywo, możemy przeklikać się do większej ilości szczegółów. Spróbuj.

I wiesz co? Pozwoli to na wychwycenie i wyświetlenie nawet fatalnych błędów. Bez konieczności instalowania jakichkolwiek rozszerzeń.

Błędy takie jak literówka w nazwie zmiennej lub próba otwarcia nieistniejącego pliku generują komunikat poziomu E_NOTICE lub E_WARNING. Można je łatwo przeoczyć w grafice strony, a może nawet w ogóle nie być widoczne (chyba, że patrząc na kod strony).

Mogą też być wyświetlane tak jak błędy:

Debugger::$strictMode = true; // pokaż wszystkie błędy
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // wszystkie błędy z wyjątkiem powiadomień deprecate.

Uwaga: Tracy po aktywacji zmienia poziom raportowania błędów na E_ALL. Jeśli chcesz to zmienić, zrób to po wywołaniu enable().

Tryb deweloperski a produkcyjny

Jak widać, Tracy jest dość gadatliwy, co można docenić w środowisku deweloperskim, natomiast na serwerze produkcyjnym spowodowałoby to katastrofę. Dzieje się tak dlatego, że nie powinny być tam wyświetlane żadne informacje o debugowaniu. Tracy posiada zatem automatyczne wykrywanie środowiska i jeśli przykład zostanie uruchomiony na serwerze produkcyjnym, błąd zostanie zapisany w dzienniku zamiast wyświetlony, a odwiedzający zobaczy jedynie przyjazny dla użytkownika komunikat:

Tryb produkcyjny wyłącza wyświetlanie wszystkich informacji o debugowaniu wysyłanych za pomocą dump(), a także oczywiście wszystkich komunikatów o błędach generowanych przez PHP. Jeśli więc zapomniałeś o jakimś dump($obj) w kodzie, nie musisz się martwić, na serwerze produkcyjnym nic nie zostanie wyświetlone.

Jak działa autodetekcja trybu? Tryb jest rozwojowy, jeśli aplikacja działa na localhost (czyli adres IP 127.0.0.1 lub ::1) i nie ma proxy (czyli jego nagłówka HTTP). W przeciwnym razie działa w trybie produkcyjnym.

Jeżeli chcesz włączyć tryb development w innych przypadkach, np. dla deweloperów uzyskujących dostęp z określonego adresu IP, możesz go określić jako parametr metody enable():

Debugger::enable('23.75.345.200'); // można również podać tablicę adresów IP

Zdecydowanie zalecamy połączenie adresu IP z plikiem cookie. Przechowuj tajny token, np. secret1234, w pliku cookie tracy-debug i w ten sposób włączaj tryb deweloperski tylko dla deweloperów uzyskujących dostęp z określonego adresu IP, którzy mają wspomniany token w pliku cookie:

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

Możesz również bezpośrednio ustawić tryb deweloperski/produkcyjny za pomocą stałych Debugger::Development lub Debugger::Production jako parametru metody enable().

Jeśli używasz Nette Framework, spójrz na to, jak ustawić tryb dla niego, a następnie będzie on również używany dla Tracy.

Rejestrowanie błędów

W trybie produkcyjnym Tracy automatycznie loguje wszystkie błędy i wyjątki do dziennika tekstowego. Aby logowanie miało miejsce, należy ustawić bezwzględną ścieżkę do katalogu logów w zmiennej $logDirectory lub przekazać ją jako drugi parametr metody enable():

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

Rejestrowanie błędów jest niezwykle przydatne. Wyobraź sobie, że wszyscy użytkownicy Twojej aplikacji to tak naprawdę beta testerzy, którzy za darmo wykonują najwyższej klasy pracę polegającą na wyszukiwaniu błędów, a Ty byłbyś głupi, gdybyś wyrzucił ich cenne raporty niepostrzeżenie do kosza na śmieci.

Jeśli musimy zarejestrować niestandardowy raport lub wyjątek złapany przez użytkownika, używamy do tego metody log():

Debugger::log('Wystąpił nieoczekiwany błąd'); // komunikat tekstowy

try {
	kritickaOperace();
} catch (Exception $e) {
	Debugger::log($e); // można również rejestrować wyjątek
	// lub
	Debugger::log($e, Debugger::ERROR); wysyła również powiadomienie e-mail
}

Jeśli chcesz, aby Tracy rejestrował błędy PHP jako E_NOTICE lub E_WARNING ze szczegółowymi informacjami (raport HTML), ustaw Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Dla prawdziwego zawodowca dziennik błędów jest kluczowym źródłem informacji i chce on być natychmiast informowany o każdym nowym błędzie. Ladenka jest w tym względzie bardzo pomocna, gdyż może go informować o nowych wpisach w dzienniku za pomocą poczty elektronicznej. Określamy gdzie mają być wysyłane maile za pomocą zmiennej $email:

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

Jeśli używasz całego Nette Framework, to to i więcej można ustawić w pliku konfiguracyjnym.

Jednak aby nie zalać skrzynki mailowej, zawsze wysyła tylko jedną wiadomość i tworzy plik email-sent. Po otrzymaniu powiadomienia mailowego, deweloper sprawdza log, naprawia aplikację i usuwa plik monitorujący, tym samym ponownie aktywując wysyłanie maili.

Otwieranie w edytorze

Po wyświetleniu strony błędu możesz kliknąć na nazwy plików i otworzą się one w Twoim edytorze z kursorem w odpowiedniej linii. Możesz również tworzyć pliki (akcja create file) lub poprawiać w nich błędy (akcja fix it). Aby to zadziałało, wystarczy skonfigurować przeglądarkę i system.

Obsługiwane wersje PHP

Tracy kompatybilny z PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.3
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

Ważne dla najnowszych wersji poprawek.

Porty

Jest to lista nieoficjalnych portów dla innych frameworków i CMS-ów: