Download the PHP package paulyg/wikicreole without Composer

=A Parser for Wiki Creole in PHP=

Creole is a standardized specification for wiki markup syntax that attempts to be as universal as possible across all of the different wiki engines out there (WikiMedia, MoinMoin, etc). The 1.0 //stable// version of the specification was released in 2008. You can find out more about Creole, including syntax cheat sheets and the history behind the project at the website http://wikiceole.org.

The intent of this library is provide a general pupose Wiki Creole-to-(X)HTML converter that can be uses in any CMS, wiki, blog, etc software. The library is implemented as a single class. An MIT license allows it's reuse in just about any type of software.

==Motivation== I began using Creole syntax inside of [[http://www.tiddlywiki.com|TiddlyWiki]], a personal wiki written in Javascript. I find the Creole syntax to be the most natural and intuitive wiki syntax out there. I prefer it to Markdown (despite it's popularity these days), maybe just because I am so used it it. I wrote this class/library because I wanted to use Creole markup in a CMS I am (very slowly) writing. At the time the only other general purpose Wiki Creole parser written in PHP was {{{Pear_Text_Wiki}}}. I decided to write my own that used PHP5 class structure and did not depend on PEAR. Later on I found out about the little known {{{ezcDocumentCreoleWiki}}}.

==Requirements==

• PHP 5.2.4 or greater (I use [[http://php.net/manual/en/function.htmlspecialchars.php|htmlspecialchar]]'s fourth $double_encode argument to keep {{{>}}} from turning into {{{>}}}).

• PCRE enabled (it usually is)

  ==Basic Usage= {{{ include 'WikiCreole.php'; $parser = new WikiCreole(array( 'urlBase' => '/wiki/', 'imgBase' => '/media/', ), $list_of_existing_page_slugs ); $html = $parser->parse($wiki_markup); }}}

==Features==

• Parses everything in the Creole 1.0 spec.
• Parses creole //additions// for {{{--strikethrough--}}}, {{{underline}}}, and {{{##monospace##}}}. See discussion below about these tags.
• Automatic prepending of a base URL or path to link or image //slug//. See {{{urlBase}}} and {{{imgBase}}} option keys below.
• Automatic conversion of //slugs// to links to other wiki pages. This removes spaces and other characters not allowed in a URL path.
• Control over markup applied to all link tags, in case you would like to style links internal to and external to your site differently. See the linkFormat* option keys below.
• Macros. Run a user defined function on text inside the macro markup tag {{{<>}}}.

==Setting Options== The class requires an array of options to be passed as the first argument in it's constructor. The options array follows a 'keyname' => 'value' format. There are currently six valid key names.

• {{{urlBase}}}: A URL string that will be prepended to any //wiki links//, link tags where the target is just a page name and is not a full URL with scheme & host name. An empty string will prepend nothing. You can pass a path for absolute path URLs or a scheme + host name + optionally a path for full absolute URLs.
• {{{imgBase}}}: A URL string that will be prepended to any //wiki images//, image tags where the target is just a filename or path & filename, not a full URL with scheme & host name. The same rules for absolute paths & full URLs as {{{urlBase}}} apply.
• {{{linkFormatExternal}}}: Specifies a format to use when creating tags for link tags that have a full URL. This is most usefull if you want to apply a special class to external links so they are formatted differently. The format string will be passed to PHP's sprintf function. The format can use two numbered placeholders: %1$s - The URL, %2$s - The text part of the link. The default format is {{{%2$s}}}. As an alternative you can pass a valid PHP callback (Closures work here if you are on PHP 5.3) and your function will be called with the URL as the first argument and the text as the second.
• {{{linkFormatInternal}}}: Same as {{{linkFormatExternal}}} except this format will be used for all links to other wiki/blog/CMS pages, where just the page title was supplied. The default format is {{{%2$s}}}. You can also pass a PHP callback or Closure here.
• {{{linkFormatMissing}}}: Same as {{{linkFormatInternal}}} except if you supply a list of existing pages and the page in the link tag does not yet exist, this format will be applied. This is especially usefull for specifcally styling pages that are in need of being created. The default format is {{{%2$s}}}. You can also pass a PHP callback or Closure here.
• {{{linkFormatFree}}}: is applied to URLS which appear in a body of text but are not contained in a tag. Unlike the above three formats this one is a format string for preg_replace. There is also only one placeholder, $0, though it can be repeated. The default format is {{{$0}}}. Callback and Closures don't work here yet.
• {{{debug}}}: Off by default. Allows extra information to be printed in case parsing goes wrong. If the parsing of a block level element goes wrong you will get back text with placeholders instead of that block level element. Setting {{{debug}}} to {{{true}}} will print out all of the strings which could not be //remerged// at the end of the HTML string inside a PRE tag. This options is really only useful to developers and hopefully not needed much anymore.