Configuration

A complete guide to configuring Texy. Learn how to control all modules, set up security, and customize Texy to your needs.

Texy is configured using public properties of the main Texy\Texy class and its modules. Each module is responsible for processing a specific part of the syntax (images, links, headings…).

Basic approach:

$texy = new Texy\Texy;

// Configuration of the main class
$texy->allowedTags = Texy\Texy::NONE;

// Configuration of a module
$texy->imageModule->root = '/images/';

Texy\Texy Class

The main class contains global settings and properties affecting the entire processing.

Allowed Syntax ($allowed)

The $allowed array controls which parts of Texy syntax are active:

// Default: all syntax features allowed (except emoticons)
$texy->allowed['image'] = true;
$texy->allowed['emoticon'] = false;

// Disable images
$texy->allowed['image'] = false;

// Disable HTML tags in input
$texy->allowed['html/tag'] = false;
$texy->allowed['html/comment'] = false;

// Disable various types of links
$texy->allowed['link/reference'] = false;
$texy->allowed['link/email'] = false;
$texy->allowed['link/url'] = false;

Complete list of syntax features:

Key	Default	Description
`image`	`true`	Images `[* img.jpg *]`
`figure`	`true`	Images with caption
`link/reference`	`true`	References `[ref]`
`link/email`	`true`	Email addresses
`link/url`	`true`	Automatic URLs
`link/definition`	`true`	Reference definitions
`heading/underlined`	`true`	Underlined headings
`heading/surrounded`	`true`	Surrounded headings
`horizline`	`true`	Horizontal lines
`blockquote`	`true`	Quotes
`list`	`true`	Lists
`list/definition`	`true`	Definition lists
`table`	`true`	Tables
`phrase/strong`	`true`	Bold text `text`
`phrase/em`	`true`	Italic `//text//`
`phrase/em-alt`	`true`	Italic `text`
`phrase/code`	`true`	Code `text`
`phrase/ins`	`false`	Inserted text `++text++`
`phrase/del`	`false`	Deleted text `--text--`
`phrase/sup`	`false`	Superscript `^^text^^`
`phrase/sub`	`false`	Subscript `__text__`
`html/tag`	`true`	HTML tags in input
`html/comment`	`true`	HTML comments
`emoticon`	`false`	Emoticons `:-)`, `:-(`
`blocks`	`true`	Blocks `/-- \--`
`typography`	`true`	Typographic adjustments
`longwords`	`true`	Breaking long words

Allowed HTML Tags ($allowedTags)

Controls which HTML tags are allowed in output (and input):

// Default: all valid HTML5 tags allowed
$texy->allowedTags = Texy\Texy::ALL;

// Disable all HTML tags
$texy->allowedTags = Texy\Texy::NONE;

// Allow only specific tags
$texy->allowedTags = [
	'strong' => [],  // <strong> without attributes
	'a' => ['href', 'title'],  // <a> with attributes
	'img' => Texy\Texy::ALL,  // <img> with any attributes
];

Formats:

Texy::ALL – all tags allowed
Texy::NONE – no tags allowed
Array – allowed tags as keys, allowed attributes as values

Allowed CSS Classes ($allowedClasses)

Controls which CSS classes and IDs can be used:

// Default: all classes and IDs allowed
$texy->allowedClasses = Texy\Texy::ALL;

// Disable classes and IDs
$texy->allowedClasses = Texy\Texy::NONE;

// Allow specific classes and IDs
$texy->allowedClasses = [
	'highlight',
	'important',
	'#main',  // IDs start with #
	'#sidebar',
];

Usage:

Text with class .[highlight]

Text with ID .{toc: main}

Allowed CSS Styles ($allowedStyles)

Controls which inline CSS properties can be used:

// Default: all styles allowed
$texy->allowedStyles = Texy\Texy::ALL;

// Disable inline styles
$texy->allowedStyles = Texy\Texy::NONE;

// Allow specific CSS properties
$texy->allowedStyles = [
	'color',
	'background-color',
	'font-size',
];

Usage:

Text with color .{color: red}

CSS Classes for Alignment ($alignClasses)

As an alternative to inline styles style="text-align:left", you can use CSS classes:

// Default: empty array (uses inline styles)
$texy->alignClasses = [
	'left' => null,
	'right' => null,
	'center' => null,
	'justify' => null,
	'top' => null,
	'middle' => null,
	'bottom' => null,
];

// Set classes
$texy->alignClasses['left'] = 'text-left';
$texy->alignClasses['right'] = 'text-right';
$texy->alignClasses['center'] = 'text-center';

Usage:

Text aligned to the left .

Text aligned to the right .>

With alignClasses set, it generates <p class="text-left"> instead of <p style="text-align:left">.

Additional Properties

// Merge lines into paragraphs (default: true)
$texy->mergeLines = true;

// Tab width (default: 8)
$texy->tabWidth = 8;

// Obfuscate emails from bots (default: true)
$texy->obfuscateEmail = true;

// Remove soft hyphens (default: true)
$texy->removeSoftHyphens = true;

// Element for non-textual paragraphs (default: 'div')
$texy->nontextParagraph = 'div';

Modules

Each module processes a specific part of the syntax. Modules are accessible as public properties of the Texy\Texy class.

HeadingModule

Processes headings (both underlined and surrounded).

// Top heading level (default: 1)
$texy->headingModule->top = 1;  // <h1>

// Generate automatic IDs (default: false)
$texy->headingModule->generateID = true;

// Prefix for generated IDs (default: 'toc-')
$texy->headingModule->idPrefix = 'section-';

// More characters = higher heading? (default: true)
$texy->headingModule->moreMeansHigher = true;

// Balancing mode (default: DYNAMIC)
$texy->headingModule->balancing = Texy\Modules\HeadingModule::DYNAMIC;

After processing:

// First heading (for <title>)
echo $texy->headingModule->title;

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

PhraseModule

Processes inline formatting (bold, italic, links within text…).

// HTML tags for individual phrases (default: see below)
$texy->phraseModule->tags = [
	'phrase/strong' => 'strong',
	'phrase/em' => 'em',
	'phrase/code' => 'code',
	// ... more
];

// Allow links in phrases (default: true)
$texy->phraseModule->linksAllowed = true;

LinkModule

Processes links, references, and URLs.

// Root path for links (default: '')
$texy->linkModule->root = '/articles/';

// CSS class for image links (default: null)
$texy->linkModule->imageClass = 'image-link';

// Always add rel="nofollow" (default: false)
$texy->linkModule->forceNoFollow = false;

// Shorten URLs to a more readable form (default: true)
$texy->linkModule->shorten = true;

References:

// Add a reference
$link = new Texy\Link('https://example.com');
$link->modifier->title = 'Example page';
$link->label = 'Example';
$texy->linkModule->addReference('example', $link);

Usage:

Link to [example]

ImageModule

Processes images.

// Root path for images (default: 'images/')
$texy->imageModule->root = '/assets/images/';

// Root path for linked images (default: 'images/')
$texy->imageModule->linkedRoot = '/assets/images/full/';

// Physical path on disk (to determine dimensions)
$texy->imageModule->fileRoot = __DIR__ . '/public/images/';

// CSS class for floating images (default: null)
$texy->imageModule->leftClass = 'float-left';
$texy->imageModule->rightClass = 'float-right';

// Default alternative text (default: '')
$texy->imageModule->defaultAlt = 'Image';

References:

// Add a reference
$image = new Texy\Image;
$image->URL = 'photo.jpg';
$image->modifier->title = 'Photo';
$texy->imageModule->addReference('photo', $image);

FigureModule

Processes images with captions.

// HTML element (default: 'div')
$texy->figureModule->tagName = 'figure';

// CSS class (default: 'figure')
$texy->figureModule->class = 'photo-figure';

// Classes for floating images (default: null)
$texy->figureModule->leftClass = 'figure-left';
$texy->figureModule->rightClass = 'figure-right';

// Offset for width calculation (default: 10)
$texy->figureModule->widthDelta = 20;

// Require caption (default: true)
$texy->figureModule->requireCaption = true;

ListModule

Processes bulleted, numbered, and definition lists.

// Patterns for list bullets (default: see source code)
$texy->listModule->bullets = [
	'*' => ['\*[\ \t]', 0, ''],
	'-' => ['[\x{2013}-](?![>-])', 0, ''],
	// ... more
];

TableModule

Processes tables.

// CSS classes for rows (default: null)
$texy->tableModule->oddClass = 'odd';
$texy->tableModule->evenClass = 'even';

Note: oddClass and evenClass are deprecated.

HorizLineModule

Processes horizontal lines.

// CSS classes by type (default: null)
$texy->horizLineModule->classes = [
	'-' => 'hr-line',
	'*' => 'hr-star',
];

TypographyModule

Processes typographic adjustments.

// Locale (default: 'cs')
$texy->typographyModule->locale = 'en';

Supported locales:

cs – Czech quotes „text" and ‚text'
en – English quotes “text” and ‘text’
fr – French quotes «text» and ‹text›
de – German quotes „text" and ‚text'
pl – Polish quotes „text" and ‚text'

LongWordsModule

Breaks long words using .

// Maximum word length (default: 20)
$texy->longWordsModule->wordLimit = 25;

EmoticonModule

Replaces emoticons with images or Unicode characters.

// CSS class (default: null)
$texy->emoticonModule->class = 'emoji';

// Path to images (default: null = uses imageModule->root)
$texy->emoticonModule->root = '/images/smilies/';
$texy->emoticonModule->fileRoot = __DIR__ . '/public/smilies/';

// Emoticon definitions (default: basic set)
$texy->emoticonModule->icons = [
	':-)' => '🙂',
	':-(' => '☹',
	';-)' => '😉',
	// ... or paths to images
	':cool:' => 'cool.gif',
];

HtmlModule

Processes HTML tags and comments in the input text.

// Display HTML comments in output (default: true)
$texy->htmlModule->passComment = true;

HtmlOutputModule

Formats the output HTML.

// Format output with indentation (default: true)
$texy->htmlOutputModule->indent = true;

// Base indentation level (default: 0)
$texy->htmlOutputModule->baseIndent = 0;

// Maximum line width (default: 80)
$texy->htmlOutputModule->lineWrap = 100;

// Preserve whitespace in these elements (default: list shown)
$texy->htmlOutputModule->preserveSpaces = [
	'textarea', 'pre', 'script', 'code',
];

ScriptModule

Processes {{macro}} calls.

// Argument separator (default: ',')
$texy->scriptModule->separator = ';';

Texy\Configurator Class

Ready-made configuration sets for common use cases.

safeMode() – Safe Mode

Configuration for processing untrusted content from users.

Texy\Configurator::safeMode($texy);

What it does:

Disables classes and IDs ($allowedClasses = NONE)
Disables inline styles ($allowedStyles = NONE)
Allows only safe HTML tags:

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

Filters URL schemes (only http:, https:, ftp:, mailto:)
Disables images
Disables reference definitions
Disables HTML comments
Adds rel="nofollow" to all links

disableLinks() – Disable Links

Disables all types of links.

Texy\Configurator::disableLinks($texy);

What it does:

Disables all types of links (link/reference, link/email, link/url, link/definition)
Disables links in phrases (phraseModule->linksAllowed = false)
Removes <a> from allowed tags

disableImages() – Disable Images

Disables all types of images.

Texy\Configurator::disableImages($texy);

What it does:

Disables images (image, figure, image/definition)
Removes <img>, <object>, <embed>, <applet> from allowed tags

Security

Texy is designed with security in mind. It automatically protects against common attacks.

Protection Against XSS

Cross-Site Scripting (XSS) is an attack where an attacker injects malicious JavaScript into a page.

Examples of attacks that Texy will block:

Attack attempt: <script>alert('XSS')</script>

Attack attempt: <img src=x onerror="alert('XSS')">

Attack attempt: "click":javascript:alert('XSS')

Attack attempt: [* image.jpg onload="alert('XSS')" *]

Texy automatically:

Validates HTML – removes disallowed tags and attributes
Filters URLs – allows only safe schemes (http:, https:, mailto:, ftp:)
Escapes content – properly escapes text in attributes
Sanitizes attributes – removes event handlers (onclick, onerror, …)

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

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

// Output: empty (script tag removed)

URL Validation

Texy checks URLs in all links and images:

$texy = new Texy\Texy;

// Set allowed schemes (default in safeMode)
$texy->urlSchemeFilters[Texy\Texy::FILTER_ANCHOR] =
	'#https?:|ftp:|mailto:#Ai';
$texy->urlSchemeFilters[Texy\Texy::FILTER_IMAGE] =
	'#https?:#Ai';

Examples of blocked URLs:

"attack":javascript:alert('XSS')  // blocked
"attack":data:text/html,<script>  // blocked
[* javascript:alert() *]  // blocked

Filtering HTML Tags

Control via $allowedTags:

$texy = new Texy\Texy;

// Allow only safe tags
$texy->allowedTags = [
	'p' => [],
	'strong' => [],
	'em' => [],
	'a' => ['href', 'title'],  // only these attributes
];

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

// Output: <p>Text alert()</p>
// (script tag removed)

Practical Example

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

	// Safe mode
	Texy\Configurator::safeMode($texy);

	// Additional restrictions
	$texy->allowed['link/url'] = false;  // disable auto-links
	$texy->allowed['html/tag'] = false;  // disable HTML

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

// Usage
$comment = $_POST['comment'];
$html = processComment($comment);
echo $html;  // safe output

Best Practices

Always use safeMode() for user content
Validate input before passing to Texy (length, format)
Limit HTML tags as needed
Check output – even though Texy is safe, double-checking never hurts
Log suspicious attempts – can help you identify attackers

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

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