CommonMark

Bonfire includes a basic library for converting [CommonMark] (http://spec.commonmark.org/) (and/or [MarkDown] (http://daringfireball.net/projects/markdown/syntax)) documents to HTML.

This library uses a configurable driver to perform the conversion, so the underlying conversion library can be easily updated/replaced as needed.

Using the Library

Using the library is fairly simple. Load the library like any other CodeIgniter library:

$this->load->library('CommonMark');

The library is then accessed like any other CodeIgniter library:

$content = $this->commonmark->convert($content);

You may also pass a configuration array to the library:

$this->load->library('CommonMark', $config);

The driver currently accepts 'driver' and 'defaultDriver' as keys in the configuration array.
Any value passed in this manner must be a string containing the name of a valid driver.

Library Methods

The following public methods are available when using the CommonMark library.

loadDriver($driver)

Load the driver named CommonMark_{$driver} from the /libraries/CommonMark/drivers/ directory (in either the application or bonfire directory) and set the library's current driver to the newly-loaded driver.
This method is primarily used to over-ride the application's configured driver when using the library.

The value of $driver still must be in the library's configured list of valid drivers.

convert($text)

Convert the text (usually from CommonMark format to HTML) and return the converted text.

Configuration

This library is extendable in a manner similar to CodeIgniter's driver system.

In order to use a driver other than the default, you must configure the library to load the driver.
In /application/config/application.php, set the commonmark.driver to the desired driver.
Make sure the driver is also listed in the commonmark.valid_drivers array (the default driver, MarkdownExtended, will always be included in the list of valid drivers by the library itself, so it does not need to be included in the configuration file).

The filename of each driver is prefixed with CommonMark_, but this prefix should not be included in the name used in either commonmark.driver or commonmark.valid_drivers.

Creating a Driver

CommonMark drivers may be included with Bonfire or may be application-specific, so the library will load drivers located in either of the following locations:
- /application/libraries/CommonMark/drivers/
- /bonfire/libraries/CommonMark/drivers/

The default configuration uses the MarkdownExtended driver, which is /bonfire/libraries/CommonMark/drivers/CommonMark_MarkdownExtended.php.

An example implementation is included for Parsedown in /application/libraries/CommonMark/drivers/CommonMark_Parsedown.php (the Parsedown library is included in /application/libraries/Parsedown.php).

The following additional application drivers are included: Markdown, MarkdownExtra, and LeagueCommonMark.
In order to use these drivers, the driver must be added to the valid_drivers array in the application configuration and the associated libraries must be installed:
- Markdown: michelf/php-markdown v1.5.0
- MarkdownExtra: michelf/php-markdown v1.5.0
- LeagueCommonMark: league/commonmark v0.7.2

It is recommended that you use an autoloader (like Composer) when using these libraries (especially league/commonmark).
It should also be noted that league/commonmark currently requires a higher version of PHP than Bonfire itself.

If you choose not to use an autoloader, the drivers will attempt to locate the associated library in the following locations:
- Markdown/MarkdownExtra:
- APPPATH . 'vendor/michelf/php-markdown/Michelf'
- APPPATH . '../vendor/michelf/php-markdown/Michelf'
- APPPATH . 'third_party/michelf/php-markdown/Michelf'
- APPPATH . 'third_party/Michelf'
- LeagueCommonMark:
- APPPATH . 'vendor/league/commonmark/src'
- APPPATH . '../vendor/league/commonmark/src'
- APPPATH . 'third_party/league/commonmark/src'
- APPPATH . 'third_party/league/commonmark'

A driver is simply a class with the CommonMark_ prefix located in one of the driver directories listed above.
The driver must extend CommonMarkDriver (which can be found in bonfire/libraries/CommonMark/CommonMarkDriver.php).
The class must include a protected function named toHtml() which accepts a string as input and returns a string as output:

<?php

class CommonMark_Example extends CommonMarkDriver
{
    protected function toHtml($text)
    {
        // Convert the CommonMark text to HTML
        // ...

        return $text;
    }
}

The code above would be placed into /application/libraries/CommonMark/drivers/CommonMark_Example.php and loaded as the Example driver.

In most cases, you will have to instantiate a library to perform the conversion and pass the argument to the library, then return the converted text.
For a better example of handling that, see any of the drivers mentioned above.

CommonMarkDriver Properties

The CommonMarkDriver is an abstract class, which means it can only be used as a base class and can't be instantiated directly.
While it may be possible to create an extending driver/adapter which does not set at least one of the properties supplied by the CommonMarkDriver, it is usually necessary to set at least the $converterLib property.

All of the properties are internal to the driver/adapter (protected) and should not be made public.

$converter

The $converter property is the instance of the underlying library used by the driver to perform the conversion.
In most cases, this property is set by the CommonMarkDriver's base methods and is only used to access the conversion method in toHtml().
The extending driver/adapter may instantiate the library and set $this->converter in the init() method, but this is uncommon.

$converterLib

This is a string identifying the class to instantiate and load into $this->converter.
In most cases, this would be the name of the class which is normally called with the new keyword.
This can include a namespace.
For example, the CommonMark_Markdown driver defines this property as follows:

protected $converterLib = '\Michelf\Markdown';

When the CommonMarkDriver instantiates the library, it calls new $this->converterLib(), which, in this case, translates to new \Michelf\Markdown().
The result is then assigned to $this->converter for later use in the toHtml() method.

$files

This is an array of file names which must be loaded if the underlying library is to be loaded manually (by calling require_once() for each of the files).

Each file name may include folder names which must be relative to the search path (one of the paths defined in $this->paths), but should not begin with a slash/directory separator.
When attempting to load a library manually, the driver will search through the defined paths for the first file in this array.
If it can't find the first file, it will not attempt to locate other files which may be in the list.

$paths

This is an array of search paths which will be used to locate the underlying library if it is to be loaded manually.

Because these should be absolute paths, it is usually necessary to define this variable in the driver/adapter's __construct() method.
Each path should not end with a trailing slash/directory separator.

CommonMarkDriver Methods

The CommonMarkDriver contains one abstract method, toHtml(), which must be implemented by the driver/adapter which extends CommonMarkDriver.

toHtml($text)

This method must be implemented by the driver/adapter.
It should be declared as a protected method (it may be public, but that is not recommended).

toHtml() is the method which will be called to perform the actual conversion from CommonMark to HTML.
When an application calls $this->commonmark->convert($text), this is the method which eventually receives the text, converts it, and returns it to the application.

In most cases, this method will only contain one line, returning the result of passing $text to the underlying library's conversion method.
For example, CommonMark_LeagueCommonMark uses the following:

protected function toHtml($text)
{
    return $this->converter->convertToHtml($text);
}

init()

This method may be implemented by the driver/adapter.
It should be declared as a protected method (it may be public, but that is not recommended).

init() is a hook point to allow a driver to load the underlying library if it has unusual requirements.
Most drivers should not need to define this method, but if they do, the method should return (boolean) true when the library is loaded successfully or false when it is not.

In most cases, it should be possible to load the library by supplying the class name in the $this->converterLib property and utilizing either Composer to autoload the library or the $this->files and $this->paths properties to define the files needed to load the library and the paths in which the library may be located.
init() is primarily used when $this->load->library() or $this->load->helper() should be used.
For example, CommonMark_MarkdownExtended uses the following:

protected function init()
{
    get_instance()->load->helper('markdown_extended');
    return true;
}

If the library can't be instantiated by calling new $this->converterLib();, it should be instantiated and assigned to $this->converter before returning true.

If init() returns false, the CommonMarkDriver will attempt to locate and instantiate the library as usual.

convert($text)

This method should not be implemented by the driver/adapter.
This is the public method used by the CommonMark library to interface with the CommonMarkDriver.
It checks whether the underlying library has been loaded (attempting to load it if not), then passes $text to the driver/adapter's toHtml() method.

Profiler
Profiler Console 0 Load Time 11.5ms Memory Used 1.07 MB Database 4 Queries vars & Config Files 87

Console

Memory Usage

Benchmarks

1 ms Loading Time: Base Classes
7 ms Controller Execution Time ( Docs / Index )
12 ms Total Execution Time

Queries

0.0002 SELECT GET_LOCK('9d53e7a31fdf4a46768dd081282d9dadf6239584', 300) AS ci_session_lockSpeed: 0.0002 - Possible keys: - Key Used: - Type: - Rows: - Extra: No tables used
0.0018 SELECT `data` FROM `bf_ci3_sessions` WHERE `id` = '9d53e7a31fdf4a46768dd081282d9dadf6239584'Speed: 0.0018 - Possible keys: - Key Used: - Type: - Rows: - Extra: no matching row IN const table
0.0003 SHOW TABLES FROM `remytek`
0.0003 SELECT * FROM `bf_settings`Speed: 0.0003 - Possible keys: - Key Used: - Type: ALL - Rows: 37 - Extra:
0.0025 Total Query Execution Time

Session User Data

__ci_last_regenerate 1542194326
requested_page http://remytek.com/index.php/docs/developer/commonmark
previous_page http://remytek.com/index.php/docs/developer/commonmark

GET DATA

No GET data exists

POST DATA

No POST data exists

URI STRING

docs/developer/commonmark

CLASS/METHOD

docs/index

HTTP HEADERS

HTTP_ACCEPT text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
HTTP_USER_AGENT CCBot/2.0 (https://commoncrawl.org/faq/)
HTTP_CONNECTION Keep-Alive
SERVER_PORT 80
SERVER_NAME remytek.com
REMOTE_ADDR 54.196.190.32
SERVER_SOFTWARE Apache/2.4.18 (Ubuntu)
HTTP_ACCEPT_LANGUAGE
SCRIPT_NAME /index.php
REQUEST_METHOD GET
HTTP_HOST
REMOTE_HOST
CONTENT_TYPE
SERVER_PROTOCOL HTTP/1.1
QUERY_STRING
HTTP_ACCEPT_ENCODING gzip
HTTP_X_FORWARDED_FOR

CONFIG VARIABLES

base_url http://remytek.com/
index_page index.php
uri_protocol AUTO
url_suffix
language english
charset UTF-8
enable_hooks true
subclass_prefix MY_
composer_autoload false
permitted_uri_chars a-z 0-9~%.:_-
allow_get_array true
enable_query_strings false
controller_trigger c
function_trigger m
directory_trigger d
log_threshold 0
log_path /var/www/clients/client2/web2/bonfire/application/logs/
log_file_extension
log_file_permissions 420
log_date_format Y-m-d H:i:s
error_views_path
cache_path /var/www/clients/client2/web2/bonfire/application/cache/
cache_query_string false
encryption_key a9ff89765e5fc8a4ee203140cfff9400
sess_cookie_name bf_session
sess_expiration 7200
sess_time_to_update 300
sess_match_ip false
sess_expire_on_close false
sess_encrypt_cookie false
sess_use_database false
sess_table_name sessions
sess_match_useragent true
sess_driver database
sess_regenerate_destroy false
sess_save_path ci3_sessions
cookie_prefix
cookie_domain
cookie_path /
cookie_secure false
cookie_httponly false
standardize_newlines false
global_xss_filtering false
csrf_protection true
csrf_token_name ci_csrf_token
csrf_cookie_name ci_csrf_token
csrf_expire 7200
csrf_regenerate true
csrf_exclude_uris Array ( )
compress_output false
time_reference utc
rewrite_short_tags false
proxy_ips
bonfire.installed 1
site.default_user_timezone UM8
modules_locations Array ( [/var/www/clients/client2/web2/bonfire/application/modules/] =&gt; ../../application/modules/ [/var/www/clients/client2/web2/bonfire/bonfire/modules/] =&gt; ../../bonfire/modules/ )
site.backup_folder archives/
contexts Array ( [0] =&gt; content [1] =&gt; reports [2] =&gt; settings [3] =&gt; developer )
enable_activity_logging true
sparks_path ../sparks/
template.site_path /var/www/clients/client2/web2/web/
template.theme_paths Array ( [0] =&gt; themes )
template.default_layout index
template.ajax_layout ajax
template.use_mobile_themes false
template.default_theme default/
template.admin_theme admin
template.message_template &lt;div class=&quot;alert alert-{type} alert-dismissable&quot;&gt; &lt;button type=&quot;button&quot; class=&quot;close&quot; data-dismiss=&quot;alert&quot; aria-hidden=&quot;true&quot;&gt;&amp;times;&lt;/button&gt; &lt;div&gt;{message}&lt;/div&gt; &lt;/div&gt;
template.breadcrumb_symbol :
template.parse_views false
assets.directories Array ( [base] =&gt; assets [cache] =&gt; cache [css] =&gt; css [image] =&gt; images [js] =&gt; js [module] =&gt; module )
assets.js_opener $(document).ready(function() {
assets.js_closer });
assets.css_combine false
assets.js_combine false
assets.css_minify true
assets.js_minify true
assets.encrypt_name false
assets.encode false
assets.base_folder assets
assets.asset_folders Array ( [css] =&gt; css [js] =&gt; js [image] =&gt; images )
ui.current_shortcuts Array ( [form_save] =&gt; Array ( [description] =&gt; Save any form in the admin area. [action] =&gt; $(&quot;input[name=save]&quot;).click();return false; ) [create_new] =&gt; Array ( [description] =&gt; Create a new record in the module. [action] =&gt; window.location.href=$(&quot;a#create_new&quot;).attr(&quot;href&quot;); ) [select_all] =&gt; Array ( [description] =&gt; Select all records in an index page. [action] =&gt; $(&quot;table input[type=checkbox]&quot;).click();return false; ) [delete] =&gt; Array ( [description] =&gt; Delete the record(s). [action] =&gt; $(&quot;#delete-me.btn-danger&quot;).click(); ) [module_index] =&gt; Array ( [description] =&gt; Return to the index of the current module. [action] =&gt; window.location.href=$(&quot;a#list&quot;).attr(&quot;href&quot;); ) [goto_content] =&gt; Array ( [description] =&gt; Jump to the Content context. [action] =&gt; window.location.href=$(&quot;#tb_content&quot;).attr(&quot;href&quot;) ) [goto_reports] =&gt; Array ( [description] =&gt; Jump to the Reports context. [action] =&gt; window.location.href=$(&quot;#tb_reports&quot;).attr(&quot;href&quot;) ) [goto_settings] =&gt; Array ( [description] =&gt; Jump to the Settings context. [action] =&gt; window.location.href=$(&quot;#tb_settings&quot;).attr(&quot;href&quot;) ) [goto_developer] =&gt; Array ( [description] =&gt; Jump to the Developer context. [action] =&gt; window.location.href=$(&quot;#tb_developer&quot;).attr(&quot;href&quot;) ) )
emailer.write_to_file false
migrate.auto_core false
migrate.auto_app false
commonmark.valid_drivers Array ( [0] =&gt; Parsedown [1] =&gt; Markdown [2] =&gt; MarkdownExtra [3] =&gt; LeagueCommonMark )
commonmark.driver MarkdownExtended
docs.theme docs
docs.default_group developer
docs.show_dev_docs true
docs.show_app_docs true
docs.toc_file _toc.ini
docs.permitted_environments Array ( [0] =&gt; development [1] =&gt; testing [2] =&gt; production )

Files

application.php
/var/www/clients/client2/web2/bonfire/application/config/application.php
autoload.php
/var/www/clients/client2/web2/bonfire/application/config/autoload.php
config.php
/var/www/clients/client2/web2/bonfire/application/config/config.php
constants.php
/var/www/clients/client2/web2/bonfire/application/config/constants.php
database.php
/var/www/clients/client2/web2/bonfire/application/config/database.php
events.php
/var/www/clients/client2/web2/bonfire/application/config/events.php
hooks.php
/var/www/clients/client2/web2/bonfire/application/config/hooks.php
mimes.php
/var/www/clients/client2/web2/bonfire/application/config/mimes.php
profiler.php
/var/www/clients/client2/web2/bonfire/application/config/profiler.php
routes.php
/var/www/clients/client2/web2/bonfire/application/config/routes.php
Base_Controller.php
/var/www/clients/client2/web2/bonfire/application/core/Base_Controller.php
MY_Model.php
/var/www/clients/client2/web2/bonfire/application/core/MY_Model.php
App_hooks.php
/var/www/clients/client2/web2/bonfire/application/hooks/App_hooks.php
application_lang.php
/var/www/clients/client2/web2/bonfire/application/language/english/application_lang.php
Profiler.php
/var/www/clients/client2/web2/bonfire/application/libraries/Profiler.php
Base.php
/var/www/clients/client2/web2/bonfire/application/third_party/MX/Base.php
Config.php
/var/www/clients/client2/web2/bonfire/application/third_party/MX/Config.php
Controller.php
/var/www/clients/client2/web2/bonfire/application/third_party/MX/Controller.php
Lang.php
/var/www/clients/client2/web2/bonfire/application/third_party/MX/Lang.php
Loader.php
/var/www/clients/client2/web2/bonfire/application/third_party/MX/Loader.php
Benchmark.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Benchmark.php
CodeIgniter.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/CodeIgniter.php
Common.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Common.php
Config.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Config.php
Controller.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Controller.php
Hooks.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Hooks.php
Input.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Input.php
Lang.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Lang.php
Loader.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Loader.php
Log.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Log.php
Model.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Model.php
Output.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Output.php
Router.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Router.php
Security.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Security.php
URI.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/URI.php
Utf8.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/Utf8.php
hash.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/compat/hash.php
mbstring.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/compat/mbstring.php
password.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/compat/password.php
standard.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/core/compat/standard.php
DB.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/database/DB.php
DB_driver.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/database/DB_driver.php
DB_query_builder.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/database/DB_query_builder.php
DB_result.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/database/DB_result.php
mysqli_driver.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/database/drivers/mysqli/mysqli_driver.php
mysqli_result.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/database/drivers/mysqli/mysqli_result.php
directory_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/helpers/directory_helper.php
form_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/helpers/form_helper.php
language_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/helpers/language_helper.php
url_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/helpers/url_helper.php
profiler_lang.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/language/english/profiler_lang.php
Cache.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/libraries/Cache/Cache.php
Cache_dummy.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/libraries/Cache/drivers/Cache_dummy.php
Driver.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/libraries/Driver.php
Session.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/libraries/Session/Session.php
Session_driver.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/libraries/Session/Session_driver.php
Session_database_driver.php
/var/www/clients/client2/web2/bonfire/bonfire/ci3/libraries/Session/drivers/Session_database_driver.php
BF_Lang.php
/var/www/clients/client2/web2/bonfire/bonfire/core/BF_Lang.php
BF_Loader.php
/var/www/clients/client2/web2/bonfire/bonfire/core/BF_Loader.php
BF_Model.php
/var/www/clients/client2/web2/bonfire/bonfire/core/BF_Model.php
BF_Router.php
/var/www/clients/client2/web2/bonfire/bonfire/core/BF_Router.php
BF_Security.php
/var/www/clients/client2/web2/bonfire/bonfire/core/BF_Security.php
BF_directory_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/helpers/BF_directory_helper.php
BF_form_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/helpers/BF_form_helper.php
application_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/helpers/application_helper.php
config_file_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/helpers/config_file_helper.php
markdown_extended_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/helpers/markdown_extended_helper.php
markdown_helper.php
/var/www/clients/client2/web2/bonfire/bonfire/helpers/markdown_helper.php
Assets.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/Assets.php
CommonMark.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/CommonMark.php
CommonMarkDriver.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/CommonMark/CommonMarkDriver.php
CommonMark_MarkdownExtended.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/CommonMark/drivers/CommonMark_MarkdownExtended.php
Console.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/Console.php
Events.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/Events.php
Modules.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/Modules.php
Route.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/Route.php
Template.php
/var/www/clients/client2/web2/bonfire/bonfire/libraries/Template.php
docs.php
/var/www/clients/client2/web2/bonfire/bonfire/modules/docs/config/docs.php
routes.php
/var/www/clients/client2/web2/bonfire/bonfire/modules/docs/config/routes.php
Docs.php
/var/www/clients/client2/web2/bonfire/bonfire/modules/docs/controllers/Docs.php
docs_lang.php
/var/www/clients/client2/web2/bonfire/bonfire/modules/docs/language/english/docs_lang.php
_sidebar.php
/var/www/clients/client2/web2/bonfire/bonfire/modules/docs/views/_sidebar.php
index.php
/var/www/clients/client2/web2/bonfire/bonfire/modules/docs/views/index.php
Settings_lib.php
/var/www/clients/client2/web2/bonfire/bonfire/modules/settings/libraries/Settings_lib.php
Settings_model.php
/var/www/clients/client2/web2/bonfire/bonfire/modules/settings/models/Settings_model.php
index.php
index.php
index.php
themes/docs/index.php