Procedural File: formatting.php

Source Location: /formatting.php

Page Details:

Main Wordpress Formatting API.

Handles many functions for formatting output.

addslashes_gpc [line 886]

string addslashes_gpc(
string $gpc)

Adds slashes to escape strings.

Slashes will first be removed if magic_quotes_gpc is set, see http://www.php.net/magic_quotes for more details.

Tags:

return:	Returns a string escaped with slashes.
since:	0.71

Parameters

string

$gpc

The string returned from HTTP request data.

[ Top ]

antispambot [line 937]

string antispambot(
string $emailaddy, [int $mailto = 0])

Converts email addresses characters to HTML entities to block spam bots.

Tags:

return:	Converted email address.
since:	0.71

Parameters

string	$emailaddy	Email address.
int	$mailto	Optional. Range from 0 to 1. Used for encoding.

[ Top ]

attribute_escape [line 1759]

string attribute_escape(
string $text)

Escaping for HTML attributes.

Tags:

since:

2.0.6

Parameters

string

$text

[ Top ]

backslashit [line 835]

string backslashit(
string $string)

Adds backslashes before letters and before a number at the start of a string.

Tags:

return:	String with backslashes inserted.
since:	0.71

Parameters

string

$string

Value to which backslashes will be added.

[ Top ]

balanceTags [line 650]

string balanceTags(
string $text, [bool $force = false])

Will only balance the tags if forced to and the option is set to balance tags.

The option 'use_balanceTags' is used for whether the tags will be balanced. Both the $force parameter and 'use_balanceTags' option will have to be true before the tags will be balanced.

Tags:

return:	Balanced text
since:	0.71

Parameters

string	$text	Text to be balanced
bool	$force	Forces balancing, ignoring the value of the option. Default false.

[ Top ]

clean_pre [line 89]

string clean_pre(
array|string $matches)

Accepts matches array from preg_replace_callback in wpautop() or a string.

Ensures that the contents of a <pre>...</pre> HTML block are not converted into paragraphs or line-breaks.

Tags:

return:	The pre block without paragraph/line-break conversion.
since:	1.2.0

Parameters

array|string

$matches

The array or string

[ Top ]

clean_url [line 1673]

string clean_url(
string $url, [array $protocols = null], [string $context = 'display'])

Checks and cleans a URL.

A number of characters are removed from the URL. If the URL is for displaying (the default behaviour) amperstands are also replaced. The 'clean_url' filter is applied to the returned cleaned URL.

Tags:

return:	The cleaned $url after the 'cleaned_url' filter is applied.
since:	1.2.0
uses:	wp_kses_bad_protocol() - To only permit protocols in the URL set via $protocols or the common ones set in the function.

Parameters

string	$url	The URL to be cleaned.
array	$protocols	Optional. An array of acceptable protocols. Defaults to 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet' if not set.
string	$context	Optional. How the URL will be used. Default is 'display'.

[ Top ]

convert_chars [line 560]

string convert_chars(
string $content, [string $deprecated = ''])

Converts a number of characters from a string.

Metadata tags title>> and category>> are removed, <br> and hr>> are converted into correct XHTML and Unicode characters are converted to the valid range.

Tags:

return:	Converted string.
since:	0.71

Parameters

string	$content	String of characters to be converted.
string	$deprecated	Not used.

[ Top ]

convert_smilies [line 1093]

string convert_smilies(
string $text)

Convert text equivalent of smilies to images.

Will only convert smilies if the option 'use_smilies' is true and the globals used in the function aren't empty.

Tags:

return:	Converted content with text smilies replaced with images.
since:	0.71
uses:	$wp_smiliessearch, - $wp_smiliesreplace Smiley replacement arrays.

Parameters

string

$text

Content to convert smilies from text.

[ Top ]

ent2ncr [line 1352]

string ent2ncr(
string $text)

Converts named entities into numbered entities.

Tags:

return:	Text with converted entities.
since:	1.5.1

Parameters

string

$text

The text within which entities will be converted.

[ Top ]

force_balance_tags [line 674]

string force_balance_tags(
string $text)

Balances tags of string using a modified stack.

Tags:

return:	Balanced text.
author:	Leonard Lin <leonard@acm.org>
version:	1.1
copyright:	November 4, 2001
border="0":	Make better - change loop condition to $text in 1.2
since:	2.0.4
license:	GPL

Parameters

string

$text

Text to be balanced.

[ Top ]

format_to_edit [line 786]

string format_to_edit(
string $content, [bool $richedit = false])

Acts on text which is about to be edited.

Unless $richedit is set, it is simply a holder for the 'format_to_edit' filter. If $richedit is set true htmlspecialchars() will be run on the content, converting special characters to HTMl entities.

Tags:

return:	The text after the filter (and possibly htmlspecialchars()) has been run.
since:	0.71

Parameters

string	$content	The text about to be edited.
bool	$richedit	Whether or not the $content should pass through htmlspecialchars(). Default false.

[ Top ]

format_to_post [line 801]

string format_to_post(
string $content)

Holder for the 'format_to_post' filter.

Tags:

return:	Text returned from the 'format_to_post' filter.
since:	0.71

Parameters

string

$content

The text to pass through the filter.

[ Top ]

funky_javascript_fix [line 626]

string funky_javascript_fix(
string $text)

Fixes javascript bugs in browsers.

Converts unicode characters to HTML numbered entities.

Tags:

return:	Fixed text.
since:	1.5.0
uses:	$is_winIE
uses:	$is_macIE

Parameters

string

$text

Text to be made safe.

[ Top ]

get_date_from_gmt [line 1185]

string get_date_from_gmt(
string $string)

Converts a GMT date into the correct format for the blog.

Requires and returns in the Y-m-d H:i:s format. Simply adds the value of gmt_offset.

Tags:

return:	Formatted date relative to the GMT offset.
since:	1.2.0

Parameters

string

$string

The date to be converted.

[ Top ]

get_gmt_from_date [line 1167]

string get_gmt_from_date(
string $string)

Returns a date in the GMT equivalent.

Requires and returns a date in the Y-m-d H:i:s format. Simply subtracts the value of gmt_offset.

Tags:

return:	GMT version of the date provided.
since:	1.2.0

Parameters

string

$string

The date to be converted.

[ Top ]

htmlentities2 [line 1728]

string htmlentities2(
string $myHTML)

Convert entities, while preserving already-encoded entities.

Tags:

return:	Converted text.
link:	http://www.php.net/htmlentities Borrowed from the PHP Manual user notes.
since:	1.2.2

Parameters

string

$myHTML

The text to be converted.

[ Top ]

human_time_diff [line 1286]

string human_time_diff(
int $from, [int $to = ''])

Determines the difference between two timestamps.

The difference is returned in a human readable format such as "1 hour", "5 mins", "2 days".

Tags:

return:	Human readable time difference.
since:	1.5.0

Parameters

int	$from	Unix timestamp from which the difference begins.
int	$to	Optional. Unix timestamp to end the time difference. Default becomes time() if not set.

[ Top ]

iso8601_timezone_to_offset [line 1200]

int|float iso8601_timezone_to_offset(
string $timezone)

Computes an offset in seconds from an iso8601 timezone.

Tags:

return:	The offset in seconds.
since:	1.5.0

Parameters

string

$timezone

Either 'Z' for 0 offset or '±hhmm'.

[ Top ]

iso8601_to_datetime [line 1222]

string iso8601_to_datetime(
string $date_string, [string $timezone = 'user'])

Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt].

Tags:

return:	The date and time in MySQL DateTime format - Y-m-d H:i:s.
since:	1.5.0

Parameters

string	$date_string	Date and time in ISO 8601 format http://en.wikipedia.org/wiki/ISO_8601.
string	$timezone	Optional. If set to GMT returns the time minus gmt_offset. Default is 'user'.

[ Top ]

is_email [line 1122]

bool is_email(
string $user_email)

Checks to see if the text is a valid email address.

Tags:

return:	Returns true if valid, otherwise false.
since:	0.71

Parameters

string

$user_email

The email address to be checked.

[ Top ]

js_escape [line 1744]

string js_escape(
string $text)

Escape single quotes, specialchar double quotes, and fix line endings.

The filter 'js_escape' is also applied here.

Tags:

return:	Escaped text.
since:	2.0.4

Parameters

string

$text

The text to be escaped.

[ Top ]

like_escape [line 1785]

string like_escape(
string $text)

Escapes text for SQL LIKE special characters % and _.

Tags:

return:	text, safe for inclusion in LIKE query.
since:	2.5.0

Parameters

string

$text

The text to be escaped.

[ Top ]

links_add_base_url [line 2090]

string links_add_base_url(
string $content, string $base, [array $attrs = array('src', 'href')])

Add a Base url to relative links in passed content.

By default it supports the 'src' and 'href' attributes. However this can be changed via the 3rd param.

Tags:

return:	The processed content.
since:	2.7.0

Parameters

string	$content	String to search for links in.
string	$base	The base URL to prefix to links.
array	$attrs	The attributes which should be processed.

[ Top ]

links_add_target [line 2131]

string links_add_target(
string $content, [string $target = '_blank'], [array $tags = array('a')])

Adds a Target attribute to all links in passed content.

This function by default only applies to <a> tags, however this can be modified by the 3rd param.

NOTE: Any current target attributed will be striped and replaced.

Tags:

return:	The processed content.
since:	2.7.0

Parameters

string	$content	String to search for links in.
string	$target	The Target to add to the links.
array	$tags	An array of tags to apply to.

[ Top ]

make_clickable [line 1035]

string make_clickable(
string $ret)

Convert plaintext URI to HTML links.

Converts URI, www and ftp, and email addresses. Finishes by fixing links within links.

Tags:

return:	Content with converted URIs.
since:	0.71

Parameters

string

$ret

Content to convert URIs.

[ Top ]

normalize_whitespace [line 2154]

void normalize_whitespace(
 $str)

Parameters

$str

[ Top ]

popuplinks [line 1257]

string popuplinks(
string $text)

Adds a element attributes to open links in new windows.

Comment text in popup windows should be filtered through this. Right now it's a moderately dumb function, ideally it would detect whether a target or rel attribute was already there and adjust its actions accordingly.

Tags:

return:	Content that has filtered links.
since:	0.71

Parameters

string

$text

Content to replace links to open in a new window.

[ Top ]

remove_accents [line 279]

string remove_accents(
string $string)

Converts all accent characters to ASCII characters.

If there are no accent characters, then the string given is just returned.

Tags:

return:	Filtered string with replaced "nice" characters.
since:	1.2.1

Parameters

string

$string

Text that might have accent characters

[ Top ]

sanitize_email [line 1270]

string sanitize_email(
string $email)

Strips out all characters that are not allowable in an email.

Tags:

return:	Filtered email address.
since:	1.5.0

Parameters

string

$email

Email address to filter.

[ Top ]

sanitize_file_name [line 422]

string sanitize_file_name(
string $name)

Filters certain characters from the file name.

Turns all strings to lowercase removing most characters except alphanumeric with spaces, dashes and periods. All spaces and underscores are converted to dashes. Multiple dashes are converted to a single dash. Finally, if the file name ends with a dash, it is removed.

Tags:

return:	Sanitized file name
since:	2.1.0

Parameters

string

$name

The file name

[ Top ]

sanitize_option [line 1816]

string sanitize_option(
string $option, string $value)

Sanitises various option values based on the nature of the option.

This is basically a switch statement which will pass $value through a number of functions depending on the $option.

Tags:

return:	Sanitized value.
since:	2.0.5

Parameters

string	$option	The name of the option.
string	$value	The unsanitised value.

[ Top ]

sanitize_sql_orderby [line 540]

string|false sanitize_sql_orderby(
string $orderby)

Ensures a string is a valid SQL order by clause.

Accepts one or more columns, with or without ASC/DESC, and also accepts RAND().

Tags:

return:	Returns the order by clause if it is a match, false otherwise.
since:	2.5.1

Parameters

string

$orderby

Order by string to be checked.

[ Top ]

sanitize_title [line 481]

string sanitize_title(
string $title, [string $fallback_title = ''])

Sanitizes title or use fallback title.

Specifically, HTML and PHP tags are stripped. Further actions can be added via the plugin API. If $title is empty and $fallback_title is set, the latter will be used.

Tags:

return:	The sanitized string.
since:	1.0.0

Parameters

string	$title	The string to be sanitized.
string	$fallback_title	Optional. A title to use if $title is empty.

[ Top ]

sanitize_title_with_dashes [line 502]

string sanitize_title_with_dashes(
string $title)

Sanitizes title, replacing whitespace with dashes.

Limits the output to alphanumeric characters, underscore (_) and dash (-). Whitespace becomes a dash.

Tags:

return:	The sanitized title.
since:	1.2.0

Parameters

string

$title

The title to be sanitized.

[ Top ]

sanitize_url [line 1714]

string sanitize_url(
string $url, [array $protocols = null])

Performs clean_url() for database usage.

Tags:

return:	The cleaned URL.
see:	clean_url()
since:	2.3.1

Parameters

string	$url	The URL to be cleaned.
array	$protocols	An array of acceptable protocols.

[ Top ]

sanitize_user [line 451]

string sanitize_user(
string $username, [bool $strict = false])

Sanitize username stripping out unsafe characters.

If $strict is true, only alphanumeric characters (as well as _, space, ., -,

Tags:

return:	The sanitized username, after passing through filters.
since:	2.0.0
uses:	apply_filters() - Calls 'sanitize_user' hook on username, raw username, and $strict parameter.

Parameters

string	$username	The username to be sanitized.
bool	$strict	If set limits $username to specific characters. Default false.

[ Top ]

seems_utf8 [line 168]

bool seems_utf8(
string $Str)

Checks to see if a string is utf8 encoded.

Tags:

return:	True if $Str fits a UTF-8 model, false otherwise.
author:	bmorel at ssi dot fr
since:	1.2.1

Parameters

string

$Str

The string to be checked

[ Top ]

stripslashes_deep [line 907]

array|string stripslashes_deep(
array|string $value)

Navigates through an array and removes slashes from the values.

If an array is passed, the array_map() function causes a callback to pass the value back to the function. The slashes from this value will removed.

Tags:

return:	Stripped array (or string in the callback).
since:	2.0.0

Parameters

array|string

$value

The array or string to be striped.

[ Top ]

tag_escape [line 1772]

string tag_escape(
string $tag_name)

Escape a HTML tag name.

Tags:

since:

2.5.0

Parameters

string

$tag_name

[ Top ]

trailingslashit [line 856]

string trailingslashit(
string $string)

Appends a trailing slash.

Will remove trailing slash if it exists already before adding a trailing slash. This prevents double slashing a string or path.

The primary use of this is for paths and thus should be used for paths. It is not restricted to paths and offers no specific path support.

Tags:

return:	String with trailing slash added.
since:	1.2.0
uses:	untrailingslashit() - Unslashes string if it was slashed already.

Parameters

string

$string

What to add the trailing slash to.

[ Top ]

untrailingslashit [line 871]

string untrailingslashit(
string $string)

Removes trailing slash if it exists.

The primary use of this is for paths and thus should be used for paths. It is not restricted to paths and offers no specific path support.

Tags:

return:	String without the trailing slash.
since:	2.2.0
usedby:	trailingslashit() - Unslashes string if it was slashed already.

Parameters

string

$string

What to remove the trailing slash from.

[ Top ]

urlencode_deep [line 923]

array|string urlencode_deep(
array|string $value)

Navigates through an array and encodes the values to be used in a URL.

Uses a callback to pass the value of the array back to the function as a string.

Tags:

return:	The encoded array (or string from the callback).
since:	2.2.0

Parameters

array|string

$value

The array or string to be encoded.

[ Top ]

utf8_uri_encode [line 228]

string utf8_uri_encode(
string $utf8_string, [int $length = 0])

Encode the Unicode values to be used in the URI.

Tags:

return:	String with Unicode encoded for URI.
since:	1.5.0

Parameters

string	$utf8_string
int	$length	Max length of the string

[ Top ]

wpautop [line 116]

string wpautop(
string $pee, [int|bool $br = 1])

Replaces double line-breaks with paragraph elements.

A group of regex replaces used to identify text formatted with newlines and replace double line-breaks with HTML paragraph tags. The remaining line-breaks after conversion become <br /> tags, unless $br is set to '0' or 'false'.

Tags:

return:	Text which has been converted into correct paragraph tags.
since:	0.71

Parameters

string	$pee	The text which has to be formatted.
int\|bool	$br	Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true.

[ Top ]

wptexturize [line 29]

string wptexturize(
string $text)

Replaces common plain text characters into formatted entities

As an example,

'cause today's effort makes it worth tomorrows "holiday"...

Becomes:

’cause today’s effort makes it worth tomorrow’s “holiday”…

Code within certain html blocks are skipped.

Tags:

return:	The string replaced with html entities
since:	0.71
uses:	$wp_cockneyreplace - Array of formatted entities for certain common phrases

Parameters

string

$text

The text to be formatted

[ Top ]

wp_htmledit_pre [line 1649]

string wp_htmledit_pre(
string $output)

Formats text for the HTML editor.

Unless $output is empty it will pass through htmlspecialchars before the 'htmledit_pre' filter is applied.

Tags:

return:	Formatted text after filter applied.
since:	2.5.0

Parameters

string

$output

The text to be formatted.

[ Top ]

wp_html_excerpt [line 2069]

string wp_html_excerpt(
integer $str, integer $count)

Safely extracts not more than the first $count characters from html string.

UTF-8, tags and entities safe prefix extraction. Entities inside will *NOT* be counted as one character. For example & will be counted as 4, < as 3, etc.

Tags:

return:	The excerpt.
since:	2.5.0

Parameters

integer	$str	String to get the excerpt from.
integer	$count	Maximum number of characters to take.

[ Top ]

wp_iso_descrambler [line 1144]

string wp_iso_descrambler(
string $string)

Convert to ASCII from email subjects.

Tags:

return:	Converted string to ASCII
since:	1.2.0

Parameters

string

$string

Subject line

[ Top ]

wp_make_link_relative [line 1800]

string wp_make_link_relative(
string $link)

Convert full URL paths to absolute paths.

Removes the http or https protocols and the domain. Keeps the path '/' at the beginning, so it isn't a true relative link, but from the web root base.

Tags:

return:	Absolute path.
since:	2.1.0

Parameters

string

$link

Full URL path.

[ Top ]

wp_parse_str [line 1911]

void wp_parse_str(
string $string,  &$array, array $array)

Parses a string into variables to be stored in an array.

Uses parse_str() and stripslashes if magic_quotes_gpc is on.

Tags:

since:	2.2.1
uses:	apply_filters() - for the 'wp_parse_str' filter.

Parameters

string	$string	The string to be parsed.
array	$array	Variables will be stored in this array.
	&$array

[ Top ]

wp_pre_kses_less_than [line 1929]

string wp_pre_kses_less_than(
string $text)

Convert lone less than signs.

KSES already converts lone greater than signs.

Tags:

return:	Converted text.
since:	2.3.0
uses:	wp_pre_kses_less_than_callback() - in the callback function.

Parameters

string

$text

Text to be converted.

[ Top ]

wp_pre_kses_less_than_callback [line 1942]

string wp_pre_kses_less_than_callback(
array $matches)

Callback function used by preg_replace.

Tags:

return:	The text returned after wp_specialchars if needed.
since:	2.3.0
usedby:	wp_pre_kses_less_than() - in the callback function.
uses:	wp_specialchars() - to format the $matches text.

Parameters

array

$matches

Populated by matches to preg_replace.

[ Top ]

wp_rel_nofollow [line 1055]

string wp_rel_nofollow(
string $text)

Adds rel nofollow string to all HTML A elements in content.

Tags:

return:	Converted content.
since:	1.5.0

Parameters

string

$text

Content that may contain HTML A elements.

[ Top ]

wp_rel_nofollow_callback [line 1075]

string wp_rel_nofollow_callback(
array $matches)

Callback to used to add rel=nofollow string to HTML A element.

Will remove already existing rel="nofollow" and rel='nofollow' from the string to prevent from invalidating (X)HTML.

Tags:

return:	HTML A Element with rel nofollow.
since:	2.3.0

Parameters

array

$matches

Single Match

[ Top ]

wp_richedit_pre [line 1627]

string wp_richedit_pre(
string $text)

Formats text for the rich text editor.

The filter 'richedit_pre' is applied here. If $text is empty the filter will be applied to an empty string.

Tags:

return:	The formatted text after filter is applied.
since:	2.0.0

Parameters

string

$text

The text to be formatted.

[ Top ]

wp_specialchars [line 201]

string wp_specialchars(
string $text, [mixed $quotes = 0])

Converts a number of special characters into their HTML entities.

Differs from htmlspecialchars as existing HTML entities will not be encoded. Specifically changes: & to &, < to < and > to >.

$quotes can be set to 'single' to encode ' to ', 'double' to encode " to ", or '1' to do both. Default is 0 where no quotes are encoded.

Tags:

return:	The encoded text with HTML entities.
since:	1.2.2
usedby:	wp_pre_kses_less_than_callback() - to format the $matches text.

Parameters

string	$text	The text which is to be encoded.
mixed	$quotes	Optional. Converts single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default 0.

[ Top ]

wp_sprintf [line 1958]

string wp_sprintf(
string $pattern, mixed $args,...)

WordPress implementation of PHP sprintf() with filters.

Tags:

return:	The formatted string.
link:	http://www.php.net/sprintf
since:	2.5.0

Parameters

string	$pattern	The string which formatted args are inserted.
mixed	$args,...	Arguments to be formatted into the $pattern string.

[ Top ]

wp_sprintf_l [line 2023]

string wp_sprintf_l(
string $pattern, array $args)

Localize list items before the rest of the content.

The '%l' must be at the first characters can then contain the rest of the content. The list items will have ', ', ', and', and ' and ' added depending on the amount of list items in the $args parameter.

Tags:

return:	Localized list items and rest of the content.
since:	2.5.0

Parameters

string	$pattern	Content containing '%l' at the beginning.
array	$args	List items to prepend to the content and replace '%l'.

[ Top ]

wp_trim_excerpt [line 1324]

string wp_trim_excerpt(
string $text)

Generates an excerpt from the content, if needed.

The excerpt word amount will be 55 words and if the amount is greater than that, then the string '[...]' will be appended to the excerpt. If the string is less than 55 words, then the content will be returned as is.

Tags:

return:	The excerpt.
since:	1.5.0

Parameters

string

$text

The exerpt. If set to empty an excerpt is generated.

[ Top ]

zeroise [line 823]

string zeroise(
mixed $number, int $threshold)

Add leading zeros when necessary.

If you set the threshold to '4' and the number is '10', then you will get back '0010'. If you set the number to '4' and the number is '5000', then you will get back '5000'.

Uses sprintf to append the amount of zeros based on the $threshold parameter and the size of the number. If the number is large enough, then no zeros will be appended.

Tags:

return:	Adds leading zeros to number if needed.
since:	0.71

Parameters

mixed	$number	Number to append zeros to if not greater than threshold.
int	$threshold	Digit places number needs to be to not have zeros added.

[ Top ]

Documentation generated on Sun, 29 Mar 2009 16:21:45 +0900 by phpDocumentor 1.4.2