Texy PHP Text-to-HTML Engine

Texy is a markup-to-HTML converter. The documentation is organized into two main sections: Reference, which covers using and extending the library, and Internals, which explains the underlying conversion pipeline.

To use Texy, you should consult the following guides:

• Syntax: For the complete reference of the Texy markup language.
• Configuration: For all configuration options, including Texy properties, generator settings, and security (safe mode).
• Extending: For instructions on adding custom handlers (renderers, transformation passes, or directives) and custom syntax (line or block syntax).

Texy follows a semantic/presentation split for configuration. You configure the engine through three main areas:

1. The Texy class: Controls which syntaxes are active (e.g., images, emoticons).
2. Modules: Semantic configuration (e.g., heading levels, typography locale).
3. The HTML generator ($texy->htmlOutput): Presentation and output formatting (e.g., image roots, line wrapping, HTML tag whitelists).

Note: Accessing pre-4.0 property locations (like $texy->imageModule->root) is deprecated and will trigger E_USER_DEPRECATED.

$texy = new Texy\Texy;
$texy->allowed['emoticon'] = true;             // Texy: syntax + security
$texy->typographyModule->locale = 'en';        // module: semantic configuration
$texy->htmlOutput->imageRoot = '/images/';  // generator: presentation
$texy->htmlOutput->lineWrap = 120;       // output formatting

Typography (locale-aware quotes, dashes, non-breaking spaces) and long-word hyphenation are implemented as AST transformations via Texy\TextRunPass, not as string post-processing. This ensures that every output format (HTML, Text, etc.) receives the same typographic treatment.

Mechanism: For every block-level inline container, Texy builds a "text image" by joining TextNode contents with special marker characters (\x17, \x16, \x15) that represent markup boundaries and protected text (like code or URLs). Regex transformers run over this image, treating the markers as a transparent alphabet. This allows the transformation to be split back into the original text nodes unambiguously.

Configuration: Control these features using the $allowed array:

• $allowed['typography']
• $allowed['longwords']

Security is handled via policies exposed on the Texy object. These policies drive the sanitization pass, which modifies the AST to protect every output format (not just HTML).

• Texy\UrlPolicy: Used for filtering URL schemes.
• Texy\HtmlPolicy: Accessed via $texy->htmlPolicy. It manages whitelists for:
  • Tags ($allowedTags)
  • Classes ($allowedClasses)
  • Styles ($allowedStyles)
  • Passthrough tag validation (e.g., ensuring <a> has an href and a safe scheme).

When a tag is rejected by the policy, the HtmlSanitizePass reconstructs the rejected tag as visible TextNodes, ensuring the content is safe but still readable.

Note: The HtmlPolicy is used both during the transform phase (as the authoritative decision) and by the renderer as defense-in-depth.

When extending Texy, follow these guidelines to ensure compatibility and stability:

• Refusal: Return null if your pattern matches but shouldn't be applied. This allows other syntaxes to attempt a match.
• Node Types: Prefer existing node types (e.g., LinkNode) to get automatic rendering in all output formats. If you must create a new Node subclass, implement getChildren() and provide a renderer handler.
• Namespacing: Use prefixed names (e.g., myapp/alert) to avoid collisions and allow users to disable your syntax via $texy->allowed.
• Modifiers: Support Texy modifiers by adding Texy\Patterns::Modifier . '?' to your regex and using Texy\Modifier::parse($matches[n]).
• Metadata: Fill in the Texy\Range object where practical to support editor tooling and source position tracking.

Transform passes allow you to mutate the Abstract Syntax Tree (AST) after parsing but before rendering. You register a pass using Texy::addPass().

Key behaviors:

• The pass receives a DocumentNode representing the entire parsed document.
• You can use NodeHelpers for simple mutations or NodeTraverser for structural changes.
• All registered passes run in the order they were registered.
• Important: Passes registered by modules always run before consumer-added passes. If you need to ensure a specific order of operations, manually call parse(), perform your AST manipulations, and then call renderHtml().

Modifiers are semantic parts of an AST node and are applied during the rendering phase via Output\Html\ElementDecorator. The application process respects the htmlPolicy configuration to ensure safe output:

1. Attributes: Only attributes allowed by the $htmlPolicy->allowedTags configuration are copied.
2. Title: Applied and typographically corrected.
3. Classes and ID: Filtered by $texy->htmlPolicy->allowedClasses. If a whitelist is used, only listed classes are applied. An ID is only applied if the whitelist contains '#' . $id.
4. Styles: Filtered by $texy->htmlPolicy->allowedStyles.
5. Alignment: Applied either as a CSS class (defined in $htmlOutput->alignClasses) or as inline text-align / vertical-align styles.

Modifiers can be applied to almost every Texy construct to add classes, IDs, or inline styles.

The modifier syntax follows this pattern: .(title)[class #id]{style: value; attr: value}<>^

Example usage:

• .(class) for a class
• [#id] for an ID
• {style: color: red;} for inline styles

Note: The actual allowed classes and styles are restricted by the $htmlPolicy->allowedClasses and $htmlPolicy->allowedStyles configurations.