tracy: improved info about modes

Author: dg

tracy/bg/guide.texy

@@ -15,6 +15,7 @@
 
 
 PHP е идеален език за генериране на фини грешки, тъй като предоставя на програмистите голяма гъвкавост. Поради това Tracy\Debugger е по-ценен. Това е най-добрият инструмент сред диагностичните.
+
 Ако срещнете Трейси за първи път, повярвайте ми, животът ви ще се раздели на този преди Трейси и този с нея. Добре дошли в добрата част!
 
 
@@ -113,20 +114,45 @@ Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // всич
 За да открием печатните грешки при присвояване на обект, използваме [признака Nette\SmartObject |utils:smartobject].
 
 
-Производствен режим и регистриране на грешки .[#toc-production-mode-and-error-logging]
-======================================================================================
+Разработване срещу производствен режим .[#toc-development-vs-production-mode]
+=============================================================================
 
-Както виждате, Трейси е доста красноречива. Това може да бъде оценено в среда за разработка, но в производствен сървър ще доведе до катастрофа. Там не може да се регистрира информация за отстраняване на грешки. Ето защо Tracy разполага с функция за автоматично откриване на средата и регистриране. Вместо да се покаже, Tracy съхранява информацията в лог файл и показва на посетителя разбираемо за потребителя съобщение за грешка на сървъра:
+Както можете да видите, Трейси е доста разговорлив, което може да се оцени в среда за разработка, докато на производствен сървър това би довело до катастрофа. Това е така, защото там не трябва да се показва информация за отстраняване на грешки. Поради това Tracy има **автоматично откриване на средата** и ако примерът се изпълнява на реален сървър, грешката ще се регистрира, вместо да се показва, а посетителят ще вижда само удобно за потребителя съобщение:
 
 [* tracy-error2.webp .{url:-} *]
 
-Изходът в производствен режим потиска цялата информация за отстраняване на грешки, която се изпраща чрез [dump( |dumper]), и, разбира се, всички съобщения за грешки, генерирани от PHP. По този начин, дори да забравите `dump($obj)` в изходния си код, няма да се налага да се притеснявате за това в производствения си сървър. Нищо няма да се вижда.
+Производственият режим потиска показването на цялата информация за отстраняване на грешки, изпратена с помощта на [dump( |dumper]), и разбира се, на всички съобщения за грешки, генерирани от PHP. Така че, ако сте забравили някои `dump($obj)` в кода, не трябва да се притеснявате, нищо няма да бъде показано на производствения сървър.
+
+Как работи автоматичното откриване на режими? Режимът е за разработка, ако приложението работи на localhost (т.е. IP адрес `127.0.0.1` или `::1`) и няма прокси (т.е. HTTP заглавието му). В противен случай то се изпълнява в производствен режим.
+
+Ако искате да активирате режим на разработка в други случаи, например за разработчици, които осъществяват достъп от определен IP адрес, можете да го зададете като параметър на метода `enable()`:
+
+```php
+Debugger::enable('23.75.345.200'); // можете също така да предоставите масив от IP адреси
+```
+
+Определено препоръчваме да комбинирате IP адреса с бисквитка. Съхранявайте таен токен, например `secret1234`, в бисквитката `tracy-debug` и по този начин активирайте режима за разработка само за разработчици, осъществяващи достъп от определен IP адрес, които имат споменатия токен в бисквитката:
+
+```php
+Debugger::enable('secret1234@23.75.345.200');
+```
+
+Можете също така директно да зададете режима на разработка/производство, като използвате константите `Debugger::Development` или `Debugger::Production` като параметър на метода `enable()`.
+
+.[note]
+Ако използвате Nette Framework, погледнете как да [зададете режима за него |application:bootstrap#Development vs Production Mode] и след това той ще се използва и за Tracy.
+
 
-Режимът на извеждане се определя от първия параметър `Debugger::enable()`. Можете да посочите константа `Debugger::Production`, или `Debugger::Development`. Друга възможност е да зададете режим на разработка да се активира, когато приложението е достъпно от определен IP адрес с определена стойност на "бисквитка" `tracy-debug`. Това се прави с помощта на синтаксиса `cookie-value@ip-address`.
+Регистриране на грешки .[#toc-error-logging]
+============================================
 
-Ако не е зададена, се използва стойността по подразбиране `Debugger::Detect`. В този случай системата идентифицира сървъра чрез IP адрес. Производствен режим се избира, ако достъпът до приложението се осъществява чрез публичен IP адрес. Резултатите от локалния IP адрес са в режим на разработка. В повечето случаи не е необходимо да задавате режима. Режимът се разпознава правилно, когато приложението работи на локалния сървър или в производствен режим.
+В производствен режим Tracy автоматично записва всички грешки и уловени изключения в текстов дневник. Задаваме пътя до него по следния начин:
+
+```php
+Debugger::$logDirectory = __DIR__ . '/log';
+```
 
-В производствен режим Tracy автоматично записва всички грешки и изключения в текстов дневник. Освен ако не посочите друго, тя ще се съхранява в log/error.log. Този дневник за грешки е изключително полезен. Представете си, че всички потребители на вашето приложение са всъщност бета Tester. Те вършат безплатно най-съвременната работа по откриване на грешки и би било глупаво да изхвърлите дискретно ценните им доклади в кошчето за боклук.
+Регистрирането на грешки е изключително полезно. Представете си, че всички потребители на вашето приложение всъщност са бета тестери, които безплатно вършат първокласна работа по откриването на грешки, и би било глупаво да изхвърлите техните ценни доклади незабелязано в кошчето за боклук.
 
 Ако трябва да регистрирате собствени съобщения или прихванати изключения, използвайте метода `log()`:
 
@@ -142,13 +168,7 @@ try {
 }
 ```
 
-Директорията за регистриране на грешки може да бъде зададена като втори параметър на метода enable():
-
-```php
-Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');
-```
-
-Ако искате Tracy да регистрира PHP грешки като `E_NOTICE` или `E_WARNING` с подробна информация (HTML отчет), задайте `Debugger::$logSeverity`:
+If you want Tracy to log PHP errors like `E_NOTICE` or `E_WARNING` with detailed information (HTML report), set `Debugger::$logSeverity`:
 
 ```php
 Debugger::$logSeverity = E_NOTICE | E_WARNING;

tracy/cs/guide.texy

@@ -114,20 +114,45 @@ Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // všechny
 Abychom odhalili i překlepy při přiřazení do proměnné objektu, použijeme [traitu Nette\SmartObject |utils:smartobject].
 
 
-Produkční režim a logování chyb
-===============================
+Vývojářský vs produkční režim
+=============================
 
-Jak vidíte, Laděnka je poměrně výřečná, což lze ocenit ve vývojovém prostředí, zatímco na produkčním serveru by to způsobilo hotové neštěstí. Tam se totiž žádné ladící informace vypsat nesmí. Laděnka proto disponuje autodetekcí prostředí a pokud příklad spustíme na ostrém serveru, chyba se místo zobrazení zaloguje a návštěvník uvidí jen uživatelsky srozumitelnou hlášku:
+Jak vidíte, Laděnka je poměrně výřečná, což lze ocenit ve vývojovém prostředí, zatímco na produkčním serveru by to způsobilo hotové neštěstí. Tam se totiž žádné ladící informace vypsat nesmí. Laděnka proto disponuje **autodetekcí prostředí** a pokud příklad spustíme na ostrém serveru, chyba se místo zobrazení zaloguje a návštěvník uvidí jen uživatelsky srozumitelnou hlášku:
 
 [* tracy-error2.webp .{url:-} *]
 
 Produkční režim potlačí zobrazování všech ladících informacích, které posíláme ven pomocí [dump() |dumper], a samozřejmě také všech chybových zpráv, které generuje PHP. Pokud jste tedy v kódu zapomněli nějaké `dump($obj)`, nemusíte se obávat, na produkčním serveru se nic nevypíše.
 
-K nastavování režimu se používá první parametr metody `Debugger::enable()`. Režim lze napevno nastavit konstantou `Debugger::Production` nebo `Debugger::Development`. Další možnost je, že bude vývojový režim zapnutý při přístupu z dané IP adresy s danou hodnotou `tracy-debug` cookie. Používá se syntaxe `hodnota-cookie@ip-adresa`.
+Jak funguje autodetekce režimu? Režim je vývojářský tehdy, pokud je aplikace spuštěna na localhostu (tj. IP adresa `127.0.0.1` nebo `::1`) a není přitomna proxy (tj. její HTTP hlavička). Jinak běží v produkčním režimu.
 
-Pokud jej neuvedeme, má výchozí hodnotu `Debugger::Detect` a v takovém případě se detekuje režim podle IP adresy serveru - je-li dostupný přes veřejnou IP adresu, běží v produkčním režimu, je-li na lokální, tak ve vývojářském. V drtivé většině případů tak není potřeba režim nastavovat a správně se rozezná podle toho, jestli aplikaci spouštíme na svém lokálním serveru nebo v ostrém provozu.
+Pokud chceme vývojářský režim povolit i v dalších případech, například programátorům přistupujícím z konkrétní IP adresy, uvedeme ji jako parametr metody `enable()`:
 
-V produkčním režimu Laděnka automaticky všechny chyby a zachycené výjimky zaznamenává do textového logu. Pokud neurčíme jinak, půjde o soubor `log/error.log`. Logování chyb je přitom nesmírně užitečné. Představte si, že všichni uživatelé vaší aplikace jsou vlastně betatesteři, kteří zdarma odvádějí špičkovou práci v hledání chyb a vy byste udělali hloupost, kdybyste jejich cenné reporty zahodili bez povšimnutí do odpadkového koše.
+```php
+Debugger::enable('23.75.345.200'); // lze uvést i pole IP adres
+```
+
+Rozhodně doporučujeme kombinovat IP adresu s cookie. Do cookie `tracy-debug` uložíme tajný token, např. `secret1234`, a tímto způsobem aktivujeme vývojářský režim jen pro programátory přistupující z konkrétní IP adresy, kteří mají v cookie zmíněný token:
+
+```php
+Debugger::enable('secret1234@23.75.345.200');
+```
+
+Vývojářský/produkční režim můžeme také přímo nastavit použitím konstanty `Debugger::Development` nebo `Debugger::Production` jako parametru metody `enable()`.
+
+.[note]
+Pokud používát Nette Framework, podívejte se, jak [nastavit režim pro něj |application:bootstrap#Vývojářský vs produkční režim] a ten se následně použije i pro Tracy.
+
+
+Logování chyb
+=============
+
+V produkčním režimu Laděnka automaticky všechny chyby a zachycené výjimky zaznamenává do textového logu. Cestu k němu nastavíme tímto způsobem:
+
+```php
+Debugger::$logDirectory = __DIR__ . '/log';
+```
+
+Logování chyb je přitom nesmírně užitečné. Představte si, že všichni uživatelé vaší aplikace jsou vlastně betatesteři, kteří zdarma odvádějí špičkovou práci v hledání chyb a vy byste udělali hloupost, kdybyste jejich cenné reporty zahodili bez povšimnutí do odpadkového koše.
 
 Pokud potřebujeme zalogovat vlastní zprávu nebo vámi zachycenou výjimku, použijeme k tomu metodu `log()`:
 
@@ -143,12 +168,6 @@ try {
 }
 ```
 
-Jiný adresář pro logování chyb lze nastavit druhým parametrem metody enable():
-
-```php
-Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');
-```
-
 Pokud chcete, aby Tracy logovala PHP chyby jako `E_NOTICE` nebo `E_WARNING` s podrobnými informacemi (HTML report), nastavte `Debugger::$logSeverity`:
 
 ```php