Native Methods

Native methods are methods that are built into PHP. CE String provides a simple way to use these methods in your templates.

A Note About Type Casting

Keep in mind that EE will always cast PHP variables as strings. To get around this when needed, you can prefix the value with one of the following:

  • :CONST: - Casts the value as a constant. If the constant cannot be found, it will be replaced with a blank string.
  • :BOOL: - Casts the value as boolean
  • :INT: - Casts the value as an integer

Don’t worry if casting doesn’t make sense to you. The examples are pretty self explanatory. :)

Note: By default, you can separate arguments with a pipe (|) and lists with a comma (,), but you can easily change that. Take a look at the parameters page for more details.

htmlentities

Convert all applicable characters to HTML entities.

PHP Manual: http://php.net/manual/en/function.htmlentities.php

  • quote_style: Can be ENT_COMPAT, ENT_QUOTES, and ENT_NOQUOTES. Defaults to ENT_COMPAT
  • charset: defaults to ISO-8859-1 in versions of PHP prior to 5.4.0, and UTF-8 from PHP 5.4.0 onwards
{exp:ce_str:ing htmlentities=":CONST:ENT_COMPAT"}I'll "walk" the <b>dog</b> now{/exp:ce_str:ing}
{exp:ce_str:ing htmlentities=":CONST:ENT_QUOTES"}I'll "walk" the <b>dog</b> now{/exp:ce_str:ing}
{exp:ce_str:ing htmlentities=":CONST:ENT_NOQUOTES"}I'll "walk" the <b>dog</b> now{/exp:ce_str:ing}

Returns:

I'll &quot;walk&quot; the &lt;b&gt;dog&lt;/b&gt; now
I&#039;ll &quot;walk&quot; the &lt;b&gt;dog&lt;/b&gt; now
I'll "walk" the &lt;b&gt;dog&lt;/b&gt; now

html_entity_decode

Convert all HTML entities to their applicable characters.

PHP Manual: http://php.net/manual/en/function.html-entity-decode.php

  • quote_style: Can be ENT_COMPAT, ENT_QUOTES, and ENT_NOQUOTES. Defaults to ENT_COMPAT
  • charset: defaults to ISO-8859-1 in versions of PHP prior to 5.4.0, and UTF-8 from PHP 5.4.0 onwards
{exp:ce_str:ing html_entity_decode}I'll &quot;walk&quot; the &lt;b&gt;dog&lt;/b&gt; now{/exp:ce_str:ing}

Returns: I'll "walk" the <b>dog</b> now

htmlspecialchars

Convert special characters to HTML entities.

PHP Manual: http://www.php.net/manual/en/function.htmlspecialchars.php

  • flags: Can be ENT_COMPAT, ENT_QUOTES, and ENT_NOQUOTES. Defaults to ENT_COMPAT
  • charset: Defines character set used in conversion. The default character set is ISO-8859-1.
  • double_encode: When double_encode is turned off PHP will not encode existing html entities, the default (true) is to convert everything.
{exp:ce_str:ing htmlspecialchars=":CONST:ENT_QUOTES"}<a href='test'>Test</a>{/exp:ce_str:ing}

Returns: &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;

htmlspecialchars_decode

Convert special HTML entities back to characters. This function is the opposite of htmlspecialchars

PHP Manual: http://www.php.net/manual/en/function.htmlspecialchars-decode.php

  • quote_style: Can be ENT_COMPAT, ENT_QUOTES, and ENT_NOQUOTES. Defaults to ENT_COMPAT
{exp:ce_str:ing htmlspecialchars_decode=":CONST:ENT_NOQUOTES"}<p>this -&gt; &quot;</p>{/exp:ce_str:ing}
Returns: <p>this -> &quot;</p>

json_encode

Returns the JSON representation of a value (PHP version 5.2.0 or greater)

PHP Manual: http://php.net/manual/en/function.json-encode.php

  • options: Bitmask consisting of JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_NUMERIC_CHECK, JSON_PRETTY_PRINT, JSON_UNESCAPED_SLASHES, JSON_FORCE_OBJECT
<script type="text/javascript">
var paragraph = {exp:ce_str:ing json_encode}<p>This is a paragraph.</p>{/exp:ce_str:ing};
</script>

Returns:

<script type="text/javascript">
var paragraph = "<p>This is a paragraph.<\/p>";
</script>

levenshtein

Calculate Levenshtein distance between two strings. The Levenshtein distance is defined as the minimal number of characters you have to replace, insert or delete to transform str1 into str2. In its simplest form the function will take only the two strings as parameter and will calculate just the number of insert, replace and delete operations needed to transform str1 into str2.

PHP Manual: http://www.php.net/manual/en/function.levenshtein.php

  • second: The second string being evaluated for Levenshtein distance (the first is the string passed in through the tagdata).
{exp:ce_str:ing levenshtein="carrot"}carrrot{/exp:ce_str:ing}

Returns: 1

ltrim

Strip whitespace (or other characters) from the beginning of a string

PHP Manual: http://php.net/manual/en/function.ltrim.php

  • charlist: You can also specify the characters you want to strip, by means of the charlist parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.
{exp:ce_str:ing ltrim="#"}#################This is a test#################{/exp:ce_str:ing}

Returns: This is a test#################

mb_strimwidth

Truncate a multibyte string

PHP Manual: http://de2.php.net/manual/en/function.mb-strimwidth.php

  • start: The start position offset. Number of characters from the beginning of string. (First character is 0)
  • width: The width of the desired trim.
  • trimmarker: A string that is added to the end of string when string is truncated.
  • encoding: The encoding parameter is the character encoding. If it is omitted, the internal character encoding value will be used.
{exp:ce_str:ing remove_html mb_strimwidth="0|100|&hellip;"}
半夜十二点多，我独自在房间里看林达的《历史深处的忧虑》，忽然想起海子的诗句——珍惜黄昏的村庄，珍惜雨水的村庄，万里无云如同我永恒的悲伤。在这样的情境下，竟是如此地契合。
{/exp:ce_str:ing}

Returns: 半夜十二点多，我独自在房间里看林达的《历史深处的忧虑》，忽然想起海子的诗句——珍惜黄昏的村庄，&hellip;

Note: Unlike the truncate= method, this method is not HTML aware.

md5

Calculate the md5 hash of a string

PHP Manual: http://php.net/manual/en/function.md5.php

  • raw_output: If the optional raw_output is set to true, then the md5 digest is instead returned in raw binary format with a length of 16. The default is false.
{exp:ce_str:ing md5}Check out my hash!{/exp:ce_str:ing}

Returns: ca44b13a9affa8673bea09454793e1b7

nl2br

Inserts HTML line breaks before all newlines in a string

PHP Manual: http://php.net/manual/en/function.nl2br.php

  • is_xhtml: Whenever to use XHTML compatible line breaks or not. Defaults to true. Available for PHP versions 5.3+.
{exp:ce_str:ing nl2br}This
is
my
text.{/exp:ce_str:ing}

Returns:
```html5
This<br />
is<br />
my<br />
text.

number_format

Format a number with grouped thousands

PHP Manual: http://php.net/manual/en/function.number-format.php

  • decimals: Sets the number of decimal points.
  • dec_point: Sets the separator for the decimal point.
  • thousands_sep: Sets the thousands separator.
{exp:ce_str:ing number_format}10000.57{/exp:ce_str:ing}

Returns: 10,001

{exp:ce_str:ing number_format="2|,| " array_delimiter="#"}10000.57{/exp:ce_str:ing}

Returns: 10 000,57

{exp:ce_str:ing number_format="2|.|"}10000.57{/exp:ce_str:ing}

Returns: 10000.57

ord

Returns the ASCII value of the first character passed in.

PHP Manual: http://php.net/manual/en/function.ord.php

{exp:ce_str:ing ord}Apple{/exp:ce_str:ing}

Returns: 65

rawurldecode

Decodes URL-encoded strings.

PHP Manual: http://php.net/manual/en/function.rawurldecode.php

{ exp:ce_str:ing rawurldecode}ftp://user:foo%20%40%2B%25%2F@ftp.example.com/x.txt{/exp:ce_str:ing}

Returns: ftp://user:foo @+%/@ftp.example.com/x.txt

rawurlencode

URL-encodes according to RFC 3986.

PHP Manual: http://php.net/manual/en/function.rawurlencode.php

<a href="ftp://user:{exp:ce_str:ing rawurlencode}foo @+%/{/exp:ce_str:ing}@ftp.example.com/x.txt">FTP</a>

Returns: <a href="ftp://user:foo%20%40%2B%25%2F@ftp.example.com/x.txt">FTP</a>

rtrim

Strips whitespace (or other characters) from the end of a string

PHP Manual: http://php.net/manual/en/function.ltrim.php

  • charlist: You can also specify the characters you want to strip, by means of the charlist parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.
{exp:ce_str:ing rtrim="#"}#################This is a test#################{/exp:ce_str:ing}

Returns: #################This is a test

sha1

Calculate the sha1 hash of a string

PHP Manual: http://php.net/manual/en/function.sha1.php

  • raw_output: If the optional raw_output is set to true, then the sha1 digest is instead returned in raw binary format with a length of 20, otherwise the returned value is a 40-character hexadecimal number.
{exp:ce_str:ing sha1}apple{/exp:ce_str:ing}

Returns: d0be2dc421be4fcd0172e5afceea3970e2f3d940

similar_text

Calculate the similarity between two strings and returns the number of matching characters in both strings

PHP Manual: http://php.net/manual/en/function.similar-text.php

  • second: The second string.
{exp:ce_str:ing similar_text="dictionary"}dictator{/exp:ce_str:ing}

Returns: 6

str_pad

Pad a string to a certain length with another string

PHP Manual: http://php.net/manual/en/function.str-pad.php

  • pad_length: If the value of pad_length is negative, less than, or equal to the length of the input string, no padding takes place.
  • pad_string: The pad_string may be truncated if the required number of padding characters can't be evenly divided by the pad_string's length.
  • pad_type: Optional argument pad_type can be STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If pad_type is not specified it is assumed to be STR_PAD_RIGHT.
{exp:ce_str:ing str_pad="10|-="}Alien{/exp:ce_str:ing}

Returns: Alien-=-=-

{exp:ce_str:ing str_pad="10|-=|:CONST:STR_PAD_LEFT"}Alien{/exp:ce_str:ing}

Returns: -=-=-Alien

{exp:ce_str:ing str_pad="10|-=|:CONST:STR_PAD_BOTH"}Alien{/exp:ce_str:ing}

Returns: -=Alien-=-

{exp:ce_str:ing str_pad="6|-="}Alien{/exp:ce_str:ing}

Returns: Alien-

str_word_count

Counts the number of words inside string

PHP Manual: http://php.net/manual/en/function.str-word-count.php

{exp:ce_str:ing str_word_count}Two roads diverged in a wood, and I- I took the one less traveled by, And that has made all the difference.{/exp:ce_str:ing}

Returns: 22

strlen

Get string length

PHP Manual: http://php.net/manual/en/function.strlen.php

{exp:ce_str:ing strlen}Like a G6{/exp:ce_str:ing}

Returns: 9

stristr

Case-insensitive strstr(). Returns all of haystack from the first occurrence of needle to the end. The haystack is the string passed in the tagdata.

PHP Manual: http://php.net/manual/en/function.stristr.php

  • needle: If the value of pad_length is negative, less than, or equal to the length of the input string, no padding takes place.
  • before_needle: If true, stristr() returns the part of the haystack before the first occurrence of the needle. Defaults to false. This parameter is only available for PHP version 5.3.0+
{exp:ce_str:ing stristr="e"}USER@EXAMPLE.com{/exp:ce_str:ing}

Returns: ER@EXAMPLE.com

{exp:ce_str:ing stristr="e"}USER@EXAMPLE.com{/exp:ce_str:ing}

Returns: ER@EXAMPLE.com

strrchr

Find the last occurrence of a character in a string. The haystack (string to search in) is the tagdata. This function returns the portion of the found string, or false if needle is not found.

PHP Manual: http://php.net/manual/en/function.strrchr.php

  • needle: If needle contains more than one character, only the first is used.
{exp:ce_str:ing strrchr="n"}apples and bananas{/exp:ce_str:ing}

Returns: nas

strrev

Reverse a string

PHP Manual: http://php.net/manual/en/function.strrev.php

{exp:ce_str:ing strrev}Hello world!{/exp:ce_str:ing}

Returns: !dlrow olleH

strstr

Find first occurrence of a string. The haystack is the string passed in as tagdata.

PHP Manual: http://php.net/manual/en/function.strstr.php

  • needle:
  • before_needle: If TRUE, strstr() returns the part of the haystack before the first occurrence of the needle. Defaults to FALSE. This parameter is only available for PHP version 5.3.0+
{exp:ce_str:ing strstr="@"}name@example.com{/exp:ce_str:ing}

Returns: @example.com

{exp:ce_str:ing strstr="@|:BOOL:true"}name@example.com{/exp:ce_str:ing}

Returns: name

strtolower

Make a string lowercase. This will automatically work with multi-byte strings if possible (if the mb_strtolower function is available to PHP).

PHP Manual: http://php.net/manual/en/function.strtolower.php

{exp:ce_str:ing strtolower}Mary Had A Little Lamb in São Paulo and She LOVED It So{/exp:ce_str:ing}

Returns: mary had a little lamb in são paulo and she loved it so

strtoupper

Make a string uppercase. This will automatically work with multi-byte strings if possible (if the mb_strtoupper function is available to PHP).

PHP Manual: http://php.net/manual/en/function.strtoupper.php

{exp:ce_str:ing strtoupper}Mary Had A Little Lamb in São Paulo and She LOVED It So{/exp:ce_str:ing}

Returns: MARY HAD A LITTLE LAMB IN SÃO PAULO AND SHE LOVED IT SO

substr

Returns the portion of string specified by the start and length parameters. The tagdata string must be one character or longer.

PHP Manual: http://php.net/manual/en/function.substr.php

  • start: If start is non-negative, the returned string will start at the start'th position in string, counting from zero. For instance, in the string abcdef, the character at position 0 is a, the character at position 2 is c, and so forth. If start is negative, the returned string will start at the start'th character from the end of string. If string is less than or equal to start characters long, false will be returned.
  • length: If length is given and is positive, the string returned will contain at most length characters beginning from start (depending on the length of string). If length is given and is negative, then that many characters will be omitted from the end of string (after the start position has been calculated when a start is negative). If start denotes the position of this truncation or beyond, false will be returned. If length is given and is 0, false or null an empty string will be returned. If length is omitted, the substring starting from start until the end of the string will be returned.
{exp:ce_str:ing substr="3"}abcdef{/exp:ce_str:ing}

Returns: def

{exp:ce_str:ing substr="0|-1"}abcdef{/exp:ce_str:ing}

Returns: abcde

{exp:ce_str:ing substr="2|-1"}abcdef{/exp:ce_str:ing}

Returns: cde

{exp:ce_str:ing substr="4|-4"}abcdef{/exp:ce_str:ing}

Returns: [boolean false]

{exp:ce_str:ing substr="-3|-1"}abcdef{/exp:ce_str:ing}

Returns: de

substr_count

Count the number of substring occurrences. The haystack (string to search in) is the tagdata.

PHP Manual: http://php.net/manual/en/function.substr-count.php

  • needle: The substring to search for.
  • offset: The offset where to start counting. This parameter is available for PHP versions 5.1.0+.
  • length: The maximum length after the specified offset to search for the substring. It outputs a warning if the offset plus the length is greater than the haystack length. This parameter is available for PHP versions 5.1.0+.
{exp:ce_str:ing substr_count="is"}This is a test{/exp:ce_str:ing}

Returns: 2

{exp:ce_str:ing substr_count="is|3"}This is a test{/exp:ce_str:ing}

Returns: 1

{exp:ce_str:ing substr_count="is|3|3"}This is a test{/exp:ce_str:ing}

Returns: 0

{exp:ce_str:ing substr_count="is|5|10"}This is a test{/exp:ce_str:ing}

Returns: [throws a PHP warning because 5+10 > 14]

substr_replace

Replace text within a portion of a string

PHP Manual: http://php.net/manual/en/function.substr-replace.php

  • replacement: The replacement string.
  • start: If start is positive, the replacing will begin at the start'th offset into string. If start is negative, the replacing will begin at the start'th character from the end of string.
  • length: If given and is positive, it represents the length of the portion of string which is to be replaced. If it is negative, it represents the number of characters from the end of string at which to stop replacing. If it is not given, then it will default to strlen( string ); i.e. end the replacing at the end of string. Of course, if length is zero then this function will have the effect of inserting replacement into string at the given start offset.

Replace all of the text with 'bob'

{exp:ce_str:ing substr_replace="bob|0"}ABCDEFGH:/MNRPQR/{/exp:ce_str:ing}

Returns: bob

Inserts 'bob' at the beginning of the text

{exp:ce_str:ing substr_replace="bob|0|0"}ABCDEFGH:/MNRPQR/{/exp:ce_str:ing}

Returns: bobABCDEFGH:/MNRPQR/

These next two tags replace 'MNRPQR' with 'bob'

{exp:ce_str:ing substr_replace="bob|10|-1"}ABCDEFGH:/MNRPQR/{/exp:ce_str:ing}

Returns: ABCDEFGH:/bob/

{exp:ce_str:ing substr_replace="bob|-7|-1"}ABCDEFGH:/MNRPQR/{/exp:ce_str:ing}

Returns: ABCDEFGH:/bob/

Remove 'MNRPQR' from the text

{exp:ce_str:ing substr_replace="|10|-1"}ABCDEFGH:/MNRPQR/{/exp:ce_str:ing}

Returns: ABCDEFGH://

trim

Strip whitespace (or other characters) from the beginning and end of a string

PHP Manual: http://php.net/manual/en/function.trim.php

  • charlist: Optionally, the stripped characters can also be specified using the charlist parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.

The following example will remove all whitespace (line breaks, tabs, spaces, etc) from around the text

{exp:ce_str:ing trim}

test

{/exp:ce_str:ing}

Returns: test

{exp:ce_str:ing trim="$"}$$$$$$$$$$$$$$$$$$$$$$$$$$test$$$$$$$$$${/exp:ce_str:ing}

Returns: test

ucfirst

Make a string's first character uppercase

PHP Manual: http://php.net/manual/en/function.ucfirst.php

{exp:ce_str:ing ucfirst}hello world!{/exp:ce_str:ing}

Returns: Hello world!

ucwords

Returns a string with the first character of each word in str capitalized, if that character is alphabetic. The definition of a word is any string of characters that is immediately after a whitespace.

PHP Manual: http://php.net/manual/en/function.ucwords.php

{exp:ce_str:ing ucwords}hello world!{/exp:ce_str:ing}

Returns: Hello World!

urldecode

Decodes URL-encoded strings.

PHP Manual: http://php.net/manual/en/function.urldecode.php

{ exp:ce_str:ing urldecode}http://wwww.example.com/some_script?name=Billy+%28Bob%29+Brown%2C+Jr.{/exp:ce_str:ing}

Returns: http://wwww.example.com/some_script?name=Billy (Bob) Brown, Jr.

urlencode

This function is convenient when encoding a string to be used in a query part of a URL, as a convenient way to pass variables to the next page.

PHP Manual: http://php.net/manual/en/function.urlencode.php

<a href="http://wwww.example.com/some_script?name={exp:ce_str:ing urlencode}Billy (Bob) Brown, Jr.{/exp:ce_str:ing}">Example</a>

Returns: <a href="http://wwww.example.com/some_script?name=Billy+%28Bob%29+Brown%2C+Jr.">Example</a>

utf8_decode

This function decodes data, assumed to be UTF-8 encoded, to ISO-8859-1.

PHP Manual: http://php.net/manual/en/function.utf8-decode.php

{exp:ce_str:ing utf8_decode}Njål{/exp:ce_str:ing}

Returns: Njål

utf8_encode

This function encodes data to UTF-8.

PHP Manual: http://php.net/manual/en/function.utf8-encode.php

{exp:ce_str:ing utf8_encode}Njål{/exp:ce_str:ing}

Returns: Njål

wordwrap

Wraps a string to a given number of characters.

PHP Manual: http://php.net/manual/en/function.wordwrap.php

  • width: The column width.
  • break: The line is broken using the optional break parameter.
  • cut: If the cut is set to true, the string is always wrapped at or before the specified width. So if you have a word that is larger than the given width, it is broken apart.
{exp:ce_str:ing wordwrap="20|<br>\n" expand_escaped}The quick brown fox jumped over the lazy dog.{/exp:ce_str:ing}

Returns:

The quick brown fox<br>
jumped over the lazy<br>
dog.