PHP SmartyPants: Configuration

PHP SmartyPants Lib includes two parsers: SmartyPants and SmartyPantsTypographer. This is a list of the settings that can be can tweaked on each of them.

Configure the Parser
Presets
SmartyPants Configuration
SmartyPants Typographer Configuration
UTF-8 Output
Configuring the classic version

Configure the Parser

To change the default behaviour, you can pass a second argument to the defaultTransform function with a configuration string:

use Michelf\SmartyPants;
$html = SmartyPants::defaultTransform($text, "1");

You can also instantiate a parser object directly with the configuration string and then call its transform method:

use Michelf\SmartyPants;
$parser = new SmartyPants("1");
$html = $parser->transform($text);

The configuration string can take one of two forms: it can specify a preset, or it can supply a list of options to enable. The available presets and configuration options are described below.

You can also change the configuration variables directly on the parser:

use Michelf\SmartyPants;
$parser = new SmartyPants;
$parser->do_dashes = 2;
$html = $parser->transform($text);

Configuration of the SmartyPantsTypographer parser work the same way. Simply replace SmartyPants in the examples above with SmartyPantsTypogrpaher.

Presets

SmartyPants comes with three presets configurations you can use instead of using a configuration string:

"0": Suppress all transformations. (Do nothing.) The output is identical to the input.
"1": Performs default SmartyPants transformations: quotes (including backticks-style), em-dashes, and ellipses. -- (dash dash) is used to signify an em-dash; there is no support for en-dashes.
"2": Same as "1", except that it uses the old-school typewriter shorthand for dashes: -- (dash dash) for en-dashes, --- (dash dash dash) for em-dashes.
"3": Same as "2", but inverts the shorthand for dashes: -- (dash dash) for em-dashes, and --- (dash dash dash) for en-dashes.
"-1": Stupefy mode. Reverses the SmartyPants transformation process, turning the HTML entities produced by SmartyPants into their ASCII equivalents. E.g. “ is turned into a simple double-quote ("), — is turned into two dashes, etc. This is useful if you wish to suppress smart punctuation in specific pages, such as RSS feeds.

SmartyPants Configuration

List of HTML tags where the content will not be affected by SmartyPants.

(Note: This is injected in a regular expression, so be careful not to use special characters that might break the expression.)

do_nothing

Setting this to 1 will disable all transforms done by SmartyPants. Set to 0 to allow the other transforms to operate.

do_quotes

Transform straight quotes " into “curly” quotes. Also works with single quotes and apostrophes.

Option	Config Value	`"quote"`	`'quote'`
`q`	do_quotes = `1`	“curly”	‘curly’

This enabled by default with preset configurations. Set to 0 to disable.

do_backticks

Transform approximative ``quotes'' ' into “curly” quotes. Set to2` to also handle single quotes.

Option	Config Value	``quotes''	`quotes'
`b`	do_backticks = `1`	“curly”
`B`	do_backticks = `2`	“curly”	‘curly’

The first variant above is enabled by default with preset configurations. Set to 0 to disable.

do_dashes

Transform double-hyphens into em dashes, and optionally triple-hyphens.

Option	Config Value	Double hyphen `--`	Triple hyphen `---`
`d`	do_dashes = `1`	em dash: —
`D`	do_dashes = `2`	en dash: –	em dash: —
`i`	do_dashes = `3`	em dash: —	en dash: –

The first variant above is enabled by default with preset configurations. Set to 0 to disable.

do_ellipses

Transform three consecutive dots ... into the ellipsis character… Set to 0 to disable.

Option	Config Value	`...`
`e`	do_ellipses = `1`	…

This is enabled by default with preset configurations.

do_stupefy

Set to 1 to convert smart typographic characters back to their straight ASCII counterparts: quotes, apostrophes, dashes, and ellipses.

convert_quot

Convert " HTML entities to normal non-curly double quotes ". This is done before all the other transforms, and the final result will only be a straight quote if you do not have do_quotes enabled. Use this option if your HTML editor emits " when typing quotes.

Option	Config Value	`"`
`w`	convert_quot = `1`	`"`

smart_doublequote_open = '“'

smart_doublequote_close = '”'

smart_singlequote_open = '‘'

smart_singlequote_close = '’' (also apostrophe)

Replacement characters for replacing straight quotes with smart quotes. The default values will produce curly “double quotes”, ‘single quotes’, and apostrophes. Replace these if you want straight quotes to be converted to something suitable for another language.

backtick_doublequote_open = '“'

backtick_doublequote_close = '”'

backtick_singlequote_open = '‘'

backtick_singlequote_close = '’' (also apostrophe)

Replacement character used by do_backticks above.

em_dash = '—'

en_dash = '–'

Replacement character for em- and em- dashes.

ellipsis = '…'

Replacement character for ellipsis.

SmartyPants Typographer Configuration

do_comma_quotes

Transform approximative ,,german`` or ''greek,, quotes to their typographic character equivalent. This option only handles the ,, lower part made of two consecutive commas, and should be set in conjunction with do_backticks for the upper part to be converted too.

Option	Config Value	`,,`
`c`	do_comma_quotes = `1`	„

Set to 0 to disable.

do_guillemets

Transform approximative guillemets (<< and >>) to their typographic character equivalent.

Option	Config Value	`<<`	`>>`
`g`	do_guillemets = `1`	«	»

Set to 0 to disable.

do_geresh_gershayim

Transform apostrophe and straight double quotes in the middle of Hebrew words in typographic Geresh or Gershayim. Only applies when surrounded by Hebrew letters on both sides, and will not apply at word boundaries.

Option	Variable	`צ'ארלס`	`צה"ל`
`G`	do_geresh_gershayim = `1`	צ׳ארלס	צה״ל

do_space_colon

Transform space character before a colon to a no-break space. Can force-insert or force-remove the space too.

Option	Config Value	`this:`	`this :`
`:`	do_space_colon = `1`	`this:`	`this_:`
`:+`	do_space_colon = `2`	`this_:`	`this_:`
`:-`	do_space_colon = `-1`	`this:`	`this:`

The first variant above is enabled by default with preset configurations. Set to 0 to disable.

do_space_semicolon

Transform space character before a semicolon to a no-break space, Can force-insert or force-remove the space too.

Option	Config Value	`this;`	`this ;`
`:`	do_space_semicolon = `1`	`this;`	`this_;`
`:+`	do_space_semicolon = `2`	`this_;`	`this_;`
`:-`	do_space_semicolon = `-1`	`this;`	`this;`

The first variant above is enabled by default with preset configurations. Set to 0 to disable.

do_space_marks

Transform space character before an exclamation mark or a question mark to a no-break space. Can force-insert or force-remove the space too.

Option	Config Value	`¡this!`	`¡ this !`
`m`	do_space_semicolon = `1`	`¡this!`	`¡_this_!`
`m+`	do_space_semicolon = `2`	`¡_this_!`	`¡_this_!`
`m-`	do_space_semicolon = `-1`	`¡this!`	`¡this!`

The first variant above is enabled by default with preset configurations. Set to 0 to disable.

do_space_emdash

Transform space characters around an em-dash to a breaking space. Can force-insert or force-remove the space too.

Option	Config Value	`a—b`	`a — b`
`h`	do_space_emdash = `1`	`a—b`	`a_—_b`
`h+`	do_space_emdash = `2`	`a_—_b`	`a_—_b`
`h-`	do_space_emdash = `-1`	`a—b`	`a—b`

Set to 0 to disable.

do_space_endash

Transform space character around an em-dash to a breaking space. Can force-insert or force-remove the space too.

Option	Config Value	`a–b`	`a – b`
`H`	do_space_endash = `1`	`a–b`	`a_–_b`
`H+`	do_space_endash = `2`	`a_–_b`	`a_–_b`
`H-`	do_space_endash = `-1`	`a–b`	`a–b`

Set to 0 to disable.

do_space_frenchquote

Transform space character on the inside of french quotes to a no-break space. Can force-insert or force-remove the space too.

Option	Config Value	`«allô»`	`« allô »`
`f`	do_space_frenchquote = `1`	`«allô»`	`«_allô_»`
`f+`	do_space_frenchquote = `2`	`«_allô_»`	`«_allô_»`
`f-`	do_space_frenchquote = `-1`	`«allô»`	`«allô»`

Note that with the first variant from the table above, spacing around »German« and »Finnish» quotes are left untouched. The two other variants should only be used with French text.

The first variant above is enabled by default with preset configurations. Set to 0 to disable.

do_space_thousand

Transform space character used as a thousand separator to a no-break space. Can force-insert the space into numbers too.

Option	Config Value	`10 000 bugs`	`10000 bugs`
`t`	do_space_thousand = `1`	`10_000 bugs`	`10000 bugs`
`t+`	do_space_thousand = `2`	`10_000 bugs`	`10_000 bugs`

The first variant above is enabled by default with preset configurations. Set to 0 to disable.

do_space_unit

Transform space character used as a separator between a number and a recognized unit abberviation to a no-break space. Can force-insert the space into numbers too.

Option	Config Value	`12 kg`	`12kg`
`u`	do_space_unit = `1`	`12_kg`	`12kg`
`u+`	do_space_unit = `2`	`12_kg`	`12_kg`
`u-`	do_space_unit = `-1`	`12kg`	`12kg`

The first variant above is enabled by default with preset configurations. Set to 0 to disable.

doublequote_low = "„"

Replacement character for low double quotes used by do_comma_quotes above.

guillemet_leftpointing = "«"

guillemet_rightpointing = "»"

Replacement character for guillmets used by do_guillemets above.

geresh = "׳"

gershayim = "״"

Replacement character for Geresh and Gershayim in Hebrew.

space_emdash = " "

space_endash = " "

space_colon = " "

space_semicolon = " "

space_marks = " "

space_frenchquote = " "

space_thousand = " "

space_unit = " "

Space character to use as a replacement for each of the spacing rules. This is by default a regular no-break space, except around dashes where a regular space is used.

Use other unicode character or HTML markup to acheive more fine-grained spacing.

space = '(?: | | |&#0*160;|&#x0*[aA]0;)'

Regular expression for finding a space character (breakable or not).

UTF-8 Output

PHP SmartyPants default configuration will emit HTML entities in the output. While you can change this manually by replacing replacement character entities in configuration variables with their UTF-8 character equivalent, you can also call this method wich will do exactly that:

$parser->decodeEntitiesInConfiguration()

This method will replace all HTML entities in configuration variables by passing them through html_entity_decode.

Configuring the classic version

Configuration options for the classic version are done using an attribute string identical to the one used by PHP SmartyPants Lib.

The defaultTransform function does not exist. Instead a global SmartyPants function is available that will do the transform to which you can pass a configuration string.