Konfigurace

Kompletní průvodce konfigurací Texy. Naučíte se ovládat všechny moduly, nastavit bezpečnost a přizpůsobit Texy vašim potřebám.

Texy se konfiguruje pomocí public properties hlavní třídy Texy\Texy a jejích modulů. Každý modul je zodpovědný za zpracování konkrétní části syntaxe (obrázky, odkazy, nadpisy…).

Základní přístup:

$texy = new Texy\Texy;

// Konfigurace hlavní třídy
$texy->allowedTags = Texy\Texy::NONE;

// Konfigurace modulu
$texy->imageModule->root = '/images/';

Třída Texy\Texy

Hlavní třída obsahuje globální nastavení a vlastnosti ovlivňující celé zpracování.

Povolené syntaxe ($allowed)

Pole $allowed kontroluje, které části Texy syntaxe jsou aktivní:

// Výchozí: všechny syntaxe povoleny (kromě emotikonů)
$texy->allowed['image'] = true;
$texy->allowed['emoticon'] = false;

// Vypnout obrázky
$texy->allowed['image'] = false;

// Vypnout HTML značky ve vstupu
$texy->allowed['html/tag'] = false;
$texy->allowed['html/comment'] = false;

// Vypnout různé typy odkazů
$texy->allowed['link/reference'] = false;
$texy->allowed['link/email'] = false;
$texy->allowed['link/url'] = false;

Kompletní seznam syntaxí:

Klíč	Výchozí	Popis
`image`	`true`	Obrázky `[* img.jpg *]`
`figure`	`true`	Obrázky s popiskou
`link/reference`	`true`	Reference `[ref]`
`link/email`	`true`	Email adresy
`link/url`	`true`	Automatické URL
`link/definition`	`true`	Definice referencí
`heading/underlined`	`true`	Podtržené nadpisy
`heading/surrounded`	`true`	Ohraničené nadpisy
`horizline`	`true`	Horizontální čáry
`blockquote`	`true`	Citace
`list`	`true`	Seznamy
`list/definition`	`true`	Definiční seznamy
`table`	`true`	Tabulky
`phrase/strong`	`true`	Tučné písmo `text`
`phrase/em`	`true`	Kurzíva `//text//`
`phrase/em-alt`	`true`	Kurzíva `text`
`phrase/code`	`true`	Kód `text`
`phrase/ins`	`false`	Vložený text `++text++`
`phrase/del`	`false`	Smazaný text `--text--`
`phrase/sup`	`false`	Horní index `^^text^^`
`phrase/sub`	`false`	Dolní index `__text__`
`html/tag`	`true`	HTML značky ve vstupu
`html/comment`	`true`	HTML komentáře
`emoticon`	`false`	Emotikony `:-)`, `:-(`
`blocks`	`true`	Bloky `/-- \--`
`typography`	`true`	Typografické úpravy
`longwords`	`true`	Dělení dlouhých slov

Povolené HTML značky ($allowedTags)

Kontroluje, které HTML značky mohou být ve výstupu (a na vstupu):

// Výchozí: všechny validní HTML5 značky povoleny
$texy->allowedTags = Texy\Texy::ALL;

// Zakázat všechny HTML značky
$texy->allowedTags = Texy\Texy::NONE;

// Povolit jen konkrétní značky
$texy->allowedTags = [
	'strong' => [],  // <strong> bez atributů
	'a' => ['href', 'title'],  // <a> s atributy
	'img' => Texy\Texy::ALL,  // <img> s jakýmikoliv atributy
];

Formáty:

Texy::ALL – všechny značky povoleny
Texy::NONE – žádné značky povoleny
Pole – povolené značky jako klíče, povolené atributy jako hodnoty

Povolené CSS třídy ($allowedClasses)

Kontroluje, které CSS třídy a ID mohou být použity:

// Výchozí: všechny třídy a ID povoleny
$texy->allowedClasses = Texy\Texy::ALL;

// Zakázat třídy a ID
$texy->allowedClasses = Texy\Texy::NONE;

// Povolit konkrétní třídy a ID
$texy->allowedClasses = [
	'highlight',
	'important',
	'#main',  // ID začínají #
	'#sidebar',
];

Použití:

Text s třídou .[highlight]

Text s ID .{toc: main}

Povolené CSS styly ($allowedStyles)

Kontroluje, které inline CSS vlastnosti mohou být použity:

// Výchozí: všechny styly povoleny
$texy->allowedStyles = Texy\Texy::ALL;

// Zakázat inline styly
$texy->allowedStyles = Texy\Texy::NONE;

// Povolit konkrétní CSS vlastnosti
$texy->allowedStyles = [
	'color',
	'background-color',
	'font-size',
];

Použití:

Text s barvou .{color: red}

CSS třídy pro zarovnání ($alignClasses)

Místo inline stylů style="text-align:left" můžete použít CSS třídy:

// Výchozí: prázdné pole (použijí se inline styly)
$texy->alignClasses = [
	'left' => null,
	'right' => null,
	'center' => null,
	'justify' => null,
	'top' => null,
	'middle' => null,
	'bottom' => null,
];

// Nastavit třídy
$texy->alignClasses['left'] = 'text-left';
$texy->alignClasses['right'] = 'text-right';
$texy->alignClasses['center'] = 'text-center';

Použití:

Text zarovnaný doleva .

Text zarovnaný doprava .>

S nastaveným alignClasses vygeneruje <p class="text-left"> místo <p style="text-align:left">.

Další vlastnosti

// Spojování řádků do odstavců (výchozí: true)
$texy->mergeLines = true;

// Šířka tabulátoru (výchozí: 8)
$texy->tabWidth = 8;

// Maskování emailů před roboty (výchozí: true)
$texy->obfuscateEmail = true;

// Odstraňování měkkých spojovníků (výchozí: true)
$texy->removeSoftHyphens = true;

// Element pro netextové odstavce (výchozí: 'div')
$texy->nontextParagraph = 'div';

Moduly

Každý modul zpracovává konkrétní část syntaxe. Moduly jsou přístupné jako public properties třídy Texy\Texy.

HeadingModule

Zpracovává nadpisy (podtržené i ohraničené).

// Úroveň nejvyššího nadpisu (výchozí: 1)
$texy->headingModule->top = 1;  // <h1>

// Generovat automatická ID (výchozí: false)
$texy->headingModule->generateID = true;

// Prefix pro generovaná ID (výchozí: 'toc-')
$texy->headingModule->idPrefix = 'section-';

// Více znaků = vyšší nadpis? (výchozí: true)
$texy->headingModule->moreMeansHigher = true;

// Režim vyvažování (výchozí: DYNAMIC)
$texy->headingModule->balancing = Texy\Modules\HeadingModule::DYNAMIC;

Po zpracování:

// První nadpis (pro <title>)
echo $texy->headingModule->title;

// Obsah (Table of Contents)
print_r($texy->headingModule->TOC);

PhraseModule

Zpracovává inline formátování (tučné, kurzíva, odkazy v textu…).

// HTML značky pro jednotlivé fráze (výchozí: viz níže)
$texy->phraseModule->tags = [
	'phrase/strong' => 'strong',
	'phrase/em' => 'em',
	'phrase/code' => 'code',
	// ... další
];

// Povolit odkazy ve frázích (výchozí: true)
$texy->phraseModule->linksAllowed = true;

LinkModule

Zpracovává odkazy, reference a URL.

// Kořenová cesta pro odkazy (výchozí: '')
$texy->linkModule->root = '/articles/';

// CSS třída pro odkazy na obrázky (výchozí: null)
$texy->linkModule->imageClass = 'image-link';

// Vždy přidávat rel="nofollow" (výchozí: false)
$texy->linkModule->forceNoFollow = false;

// Zkracovat URL na čitelnější formu (výchozí: true)
$texy->linkModule->shorten = true;

Reference:

// Přidat referenci
$link = new Texy\Link('https://example.com');
$link->modifier->title = 'Ukázková stránka';
$link->label = 'Příklad';
$texy->linkModule->addReference('example', $link);

Použití:

Odkaz na [example]

ImageModule

Zpracovává obrázky.

// Kořenová cesta pro obrázky (výchozí: 'images/')
$texy->imageModule->root = '/assets/images/';

// Kořenová cesta pro linkované obrázky (výchozí: 'images/')
$texy->imageModule->linkedRoot = '/assets/images/full/';

// Fyzická cesta na disku (pro zjištění rozměrů)
$texy->imageModule->fileRoot = __DIR__ . '/public/images/';

// CSS třída pro plovoucí obrázky (výchozí: null)
$texy->imageModule->leftClass = 'float-left';
$texy->imageModule->rightClass = 'float-right';

// Výchozí alternativní text (výchozí: '')
$texy->imageModule->defaultAlt = 'Obrázek';

Reference:

// Přidat referenci
$image = new Texy\Image;
$image->URL = 'photo.jpg';
$image->modifier->title = 'Fotografie';
$texy->imageModule->addReference('photo', $image);

FigureModule

Zpracovává obrázky s popiskou.

// HTML element (výchozí: 'div')
$texy->figureModule->tagName = 'figure';

// CSS třída (výchozí: 'figure')
$texy->figureModule->class = 'photo-figure';

// Třídy pro plovoucí obrázky (výchozí: null)
$texy->figureModule->leftClass = 'figure-left';
$texy->figureModule->rightClass = 'figure-right';

// Offset pro výpočet šířky (výchozí: 10)
$texy->figureModule->widthDelta = 20;

// Vyžadovat popisku (výchozí: true)
$texy->figureModule->requireCaption = true;

ListModule

Zpracovává odrážkové, číslované a definiční seznamy.

// Definice odrážek a stylu (výchozí: viz zdrojový kód)
$texy->listModule->bullets = [
	'*' => ['\*[\ \t]', 0, ''],
	'-' => ['[\x{2013}-](?![>-])', 0, ''],
	// ... další
];

TableModule

Zpracovává tabulky.

// CSS třídy pro řádky (výchozí: null)
$texy->tableModule->oddClass = 'odd';
$texy->tableModule->evenClass = 'even';

Poznámka: oddClass a evenClass jsou deprecated.

HorizLineModule

Zpracovává horizontální čáry.

// CSS třídy podle typu (výchozí: null)
$texy->horizLineModule->classes = [
	'-' => 'hr-line',
	'*' => 'hr-star',
];

TypographyModule

Zpracovává typografické úpravy.

// Locale (výchozí: 'cs')
$texy->typographyModule->locale = 'en';

Podporované locales:

cs – české uvozovky „text" a ‚text'
en – anglické uvozovky „text“ a ‚text‘
fr – francouzské uvozovky «text» a ‹text›
de – německé uvozovky „text" a ‚text'
pl – polské uvozovky „text" a ‚text'

LongWordsModule

Rozděluje dlouhá slova pomocí .

// Maximální délka slova (výchozí: 20)
$texy->longWordsModule->wordLimit = 25;

EmoticonModule

Nahrazuje emotikony za obrázky nebo Unicode znaky.

// CSS třída (výchozí: null)
$texy->emoticonModule->class = 'emoji';

// Cesta k obrázkům (výchozí: null = použije imageModule->root)
$texy->emoticonModule->root = '/images/smilies/';
$texy->emoticonModule->fileRoot = __DIR__ . '/public/smilies/';

// Definice emotikonů (výchozí: základní sada)
$texy->emoticonModule->icons = [
	':-)' => '🙂',
	':-(' => '☹',
	';-)' => '😉',
	// ... nebo cesty k obrázkům
	':cool:' => 'cool.gif',
];

HtmlModule

Zpracovává HTML značky a komentáře ve vstupním textu.

// Zobrazit HTML komentáře na výstupu (výchozí: true)
$texy->htmlModule->passComment = true;

HtmlOutputModule

Formátuje výstupní HTML.

// Formátovat výstup (odsazení) (výchozí: true)
$texy->htmlOutputModule->indent = true;

// Základní odsazení (výchozí: 0)
$texy->htmlOutputModule->baseIndent = 0;

// Maximální šířka řádku (výchozí: 80)
$texy->htmlOutputModule->lineWrap = 100;

// Zachovat mezery v těchto elementech (výchozí: seznam)
$texy->htmlOutputModule->preserveSpaces = [
	'textarea', 'pre', 'script', 'code',
];

ScriptModule

Zpracovává volání {{makro}}.

// Oddělovač argumentů (výchozí: ',')
$texy->scriptModule->separator = ';';

Třída Texy\Configurator

Předpřipravené konfigurační sety pro časté use-case.

safeMode() – Bezpečný režim

Konfigurace pro zpracování nedůvěryhodného obsahu od uživatelů.

Texy\Configurator::safeMode($texy);

Co dělá:

Zakáže třídy a ID ($allowedClasses = NONE)
Zakáže inline styly ($allowedStyles = NONE)
Povolí jen bezpečné HTML značky:

[
	'a' => ['href', 'title'],
	'abbr' => ['title'],
	'b' => [],
	'br' => [],
	'cite' => [],
	'code' => [],
	'em' => [],
	'i' => [],
	'strong' => [],
	'sub' => [],
	'sup' => [],
	'q' => [],
	'small' => [],
]

Filtruje URL schémata (jen http:, https:, ftp:, mailto:)
Zakáže obrázky
Zakáže definice referencí
Zakáže HTML komentáře
Přidá rel="nofollow" ke všem odkazům

disableLinks() – Vypnout odkazy

Zakáže všechny typy odkazů.

Texy\Configurator::disableLinks($texy);

Co dělá:

Zakáže všechny typy odkazů (link/reference, link/email, link/url, link/definition)
Zakáže odkazy ve frázích (phraseModule->linksAllowed = false)
Odebere <a> z povolených značek

disableImages() – Vypnout obrázky

Zakáže všechny typy obrázků.

Texy\Configurator::disableImages($texy);

Co dělá:

Zakáže obrázky (image, figure, image/definition)
Odebere <img>, <object>, <embed>, <applet> z povolených značek

Bezpečnost

Texy je navrženo s důrazem na bezpečnost. Automaticky chrání před běžnými útoky.

Ochrana proti XSS

Cross-Site Scripting (XSS) je útok, kdy útočník vloží škodlivý JavaScript do stránky.

Příklad útoků, které Texy zablokuje:

Pokus o útok: <script>alert('XSS')</script>

Pokus o útok: <img src=x onerror="alert('XSS')">

Pokus o útok: "klikni":javascript:alert('XSS')

Pokus o útok: [* image.jpg onload="alert('XSS')" *]

Texy automaticky:

Validuje HTML – odstraní nepovolené značky a atributy
Filtruje URL – povolí jen bezpečná schémata (http:, https:, mailto:, ftp:)
Escapuje obsah – správně escapuje text v atributech
Sanitizuje atributy – odstraní event handlery (onclick, onerror, …)

$texy = new Texy\Texy;
Texy\Configurator::safeMode($texy);

$input = '<script>alert("XSS")</script>';
$output = $texy->process($input);

// Výstup: prázdný (script tag odstraněn)

Validace URL

Texy kontroluje URL ve všech odkazech a obrázcích:

$texy = new Texy\Texy;

// Nastavit povolená schémata (výchozí v safeMode)
$texy->urlSchemeFilters[Texy\Texy::FILTER_ANCHOR] =
	'#https?:|ftp:|mailto:#Ai';
$texy->urlSchemeFilters[Texy\Texy::FILTER_IMAGE] =
	'#https?:#Ai';

Příklady blokovaných URL:

"útok":javascript:alert('XSS')  // blokováno
"útok":data:text/html,<script>  // blokováno
[* javascript:alert() *]  // blokováno

Filtrování HTML značek

Kontrola přes $allowedTags:

$texy = new Texy\Texy;

// Povolit jen bezpečné značky
$texy->allowedTags = [
	'p' => [],
	'strong' => [],
	'em' => [],
	'a' => ['href', 'title'],  // jen tyto atributy
];

$input = '<p>Text <script>alert()</script></p>';
$output = $texy->process($input);

// Výstup: <p>Text alert()</p>
// (script tag odstraněn)

Praktický příklad

function processComment(string $userInput): string
{
	$texy = new Texy\Texy;

	// Bezpečný režim
	Texy\Configurator::safeMode($texy);

	// Dodatečná omezení
	$texy->allowed['link/url'] = false;  // zakázat auto-linky
	$texy->allowed['html/tag'] = false;  // zakázat HTML

	// Zpracovat
	return $texy->process($userInput);
}

// Použití
$comment = $_POST['comment'];
$html = processComment($comment);
echo $html;  // bezpečný výstup

Best practices

Vždy použijte safeMode() pro uživatelský obsah
Validujte vstup před předáním Texy (délka, formát)
Limitujte HTML značky podle potřeby
Kontrolujte výstup – i když Texy je bezpečné, double-check nikdy neuškodí
Logujte podezřelé pokusy – může vám pomoci identifikovat útočníky

$texy = new Texy\Texy;
Texy\Configurator::safeMode($texy);

// Logování
$texy->addHandler('htmlTag', function($invocation, $el, $isStart) {
	if ($el->getName() === 'script') {
		error_log('XSS attempt detected!');
	}
	return $invocation->proceed();
});