obitel-forks / php-textile

Textile markup language parser for PHP

PHP-Textile

Downloads | Textile reference | Live editor | Packagist

PHP-Textile is a modern Textile markup language parser for PHP. Textile is a humane web text generator that takes lightweight, readable, plaintext-like markup language and converts it into well formed HTML.

Installing

Using Composer

The recommended way to install PHP-Textile is via Composer package manager. Navigate to your project directory, and run the command:

$ composer require "netcarver/textile 3.5.*"

If you haven’t yet used Composer, you will then want to include the autoloader file generated by Composer in your project:

require './vendor/autoload.php';

Manually

You can also install PHP-Textile library manually. The library supports any PSR-0 style autoloaders, but you can also include the source files in your project manually. Download the repository, and include the source files:

require 'path/to/src/Netcarver/Textile/Parser.php';
require 'path/to/src/Netcarver/Textile/DataBag.php';
require 'path/to/src/Netcarver/Textile/Tag.php';

Or point your PSR-0 autoloader to the PHP-Textile installation location.

Usage

Textile parser can be accessed through the Netcarver\Textile\Parser class. The class is highly configurable, and actual parsing happens with the parse method:

$parser = new \Netcarver\Textile\Parser();
echo $parser->parse('h1. Hello World!');

Parsing untrusted input

If you are using PHP-Textile to format user-supplied input, blog comments for instance, remember to enable restricted parser mode:

$parser = new \Netcarver\Textile\Parser();
echo $parser
    ->setRestricted(true)
    ->parse('!bad/image/not/allowed.svg!');

In restricted mode PHP-Textile doesn’t allow more powerful formatting options such as inline style, and removes any raw HTML.

Parsing single-line fields

If you are using PHP-Textile as a field-level formatter to parse just inline spans and glyphs, use the
setBlockTags() method to disable block tags:

$parser = new \Netcarving\Textile\Parser();
echo $parser
    ->setBlockTags(false)
    ->parse('Hello *strong* world!');

The above outputs:

Hello <strong>strong</strong> world!

Doctypes

Currently, PHP-Textile can target either XHTML or HTML5 output with XHTML being the default for backward compatibility. The targeted doctype can be changed through the setDocumentType() method:

$parser = new \Netcarver\Textile\Parser();
echo $parser
    ->setDocumentType('html5')
    ->parse('HTML(HyperText Markup Language)");

In HTML5 mode, you’ll get abbr instead of acronym and if you use alignment markers on your images you’ll have extra classes placed on them instead of XHTML’s align attribute.

Setting alternate glyphs

Textile’s typographic substitutions can be overridden with the setSymbol method. If you need to setup Textile to do non-standard substitutions, call setSymbol before you parse the input with textileThis or textileRestricted.

$parser = new \Netcarver\Textile\Parser();
$parser
    ->setSymbol('half', '1⁄2')
    ->parse('Hello [1/2] World!');

The symbol names you can pass to setSymbol() can be found here.

Prefixing relative image paths

Setting a image path prefix might be useful if your application only allows users to reference images from a certain location like, say, an images directory. The prefix can be set with the setRelativeImagePrefix() method:

$parser = new \Netcarver\Textile\Parser();
$parser
    ->setRelativeImagePrefix('user/uploads')
    ->parse('Hello World!');

Getting in contact

The PHP-Textile project welcomes constructive input and bug reports from users. Please open an issue on the repository for a comment, feature request or bug.