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.5.*"

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 @textileThis@ and @textileRestricted@ methods:

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

h3. Parsing untrusted input

If you are using PHP-Textile to format user-supplied input, blog comments for instance, use the @textileRestricted()@ method:

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

The method doesn't allow more powerful formatting options such as inline style, and removes any raw HTML.

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 through the constructor:

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

h2. Getting in contact

The PHP-Textile project welcomes constructive input and bug reports from users. You can contact us in several ways:

* "Open an issue":https://github.com/textile/php-textile/issues on the repository for a feature request or bug.
* If you are on IRC, feel free to drop into *#textile* on *freenode.net* ("webchat":http://webchat.freenode.net/?channels=#textile.)
* Use the generic "contact form":http://sitemonks.com/.
