h1. PHP-Textile

"Downloads":https://github.com/textile/php-textile/releases | "Textile reference":http://txstyle.org/article/43/a-short-introduction | "Live editor":http://txstyle.org/ | "Packagist":https://packagist.org/packages/netcarver/textile

!https://travis-ci.org/textile/php-textile.png?branch=master!:https://travis-ci.org/textile/php-textile !https://coveralls.io/repos/textile/php-textile/badge.png?branch=master!:https://coveralls.io/r/textile/php-textile?branch=master

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.

h2. Installing

h3. Using Composer

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

bc. $ composer require "netcarver/textile 3.6.*"

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

bc. require './vendor/autoload.php';

h3. 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":https://github.com/textile/php-textile/releases the repository, and include the source files:

bc. 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.

h2. 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:

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

h3. Parsing untrusted input

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

bc. $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.

h3. 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:

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

The above outputs:

bc. Hello <strong>strong</strong> world!

h3. 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 via constructor injection:

bc. $parser = new \Netcarver\Textile\Parser('html5');
echo $parser
    ->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.

h3. 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@.

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

The symbol names you can pass to @setSymbol()@ can be found "here":https://github.com/textile/php-textile/blob/582fb7e2af83bb043fe6dd3846220796c814f999/classTextile.php#L468.

h3. 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:

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

h2. Getting in contact

The PHP-Textile project welcomes constructive input and bug reports from users. Please "open an issue":https://github.com/textile/php-textile/issues on the repository for a comment, feature request or bug.
