82 lines
4.1 KiB
Plaintext
82 lines
4.1 KiB
Plaintext
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⁄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/.
|