Convert

class Convert

Library of conversion functions, implemented as static methods.

The methods are all of the form (format)2(format), where the format is one of

raw: A UTF8 string attr: A UTF8 string suitable for inclusion in an HTML attribute js: A UTF8 string suitable for inclusion in a double-quoted javascript string.

array: A PHP associative array json: JavaScript object notation

html: HTML source suitable for use in a page or email text: Plain-text content, suitable for display to a user as-is, or insertion in a plaintext email.

Objects of type {@link ViewableData} can have an "escaping type", which determines if they are automatically escaped before output by {@link SSViewer}.

Methods

static array|string
raw2att(array|string $val)

Convert a value to be suitable for an XML attribute.

static array|string
raw2htmlatt(string|array $val)

Convert a value to be suitable for an HTML attribute.

static array|string
raw2htmlname(array|string $val)

Convert a value to be suitable for an HTML ID attribute. Replaces non supported characters with a space.

static array|string
raw2htmlid(array|string $val)

Convert a value to be suitable for an HTML ID attribute. Replaces non supported characters with an underscore.

static array|string
raw2xml(array|string $val)

Ensure that text is properly escaped for XML.

static array|string
raw2js(array|string $val)

Ensure that text is properly escaped for Javascript.

static string
raw2json(mixed $val, int $options)

Encode a value as a JSON encoded string. You can optionally pass a bitmask of JSON constants as options through to the encode function.

static string
array2json(array $val, int $options)

Encode an array as a JSON encoded string.

static string|array
raw2sql(mixed|array $val, boolean $quoted = false)

Safely encodes a value (or list of values) using the current database's safe string encoding method

static string|array
symbol2sql(string|array $identifier, string $separator = '.')

Safely encodes a SQL symbolic identifier (or list of identifiers), such as a database, table, or column name. Supports encoding of multi identfiers separated by a delimiter (e.g. ".")

static 
xml2raw($val)

Convert XML to raw text.

static object|boolean
json2obj(string $val)

Convert a JSON encoded string into an object.

static array|boolean
json2array(string $val)

Convert a JSON string into an array.

static array
xml2array(string $val, boolean $disableDoctypes = false, boolean $disableExternals = false)

Converts an XML string to a PHP array See http://phpsecurity.readthedocs.org/en/latest/Injection-Attacks.html#xml-external-entity-injection

static string
linkIfMatch(string $string)

Create a link if the string is a valid URL

static string
html2raw(string $data, bool $preserveLinks = false, int $wordWrap, array $config = null)

Simple conversion of HTML to plaintext.

static string
raw2mailto($data)

There are no real specifications on correctly encoding mailto-links, but this seems to be compatible with most of the user-agents.

static string
raw2url(string $title)

Convert a string (normally a title) to a string suitable for using in urls and other html attributes. Uses {@link URLSegmentFilter}.

static string
nl2os(string $data, string $nl = PHP_EOL)

Normalises newline sequences to conform to (an) OS specific format.

static string
base64url_encode(mixed $val)

Encode a value into a string that can be used as part of a filename.

static mixed
base64url_decode(string $val)

Decode a value that was encoded with Convert::base64url_encode.

Details

at line 31
static array|string raw2att(array|string $val)

Convert a value to be suitable for an XML attribute.

Parameters

array|string $val String to escape, or array of strings

Return Value

array|string

at line 41
static array|string raw2htmlatt(string|array $val)

Convert a value to be suitable for an HTML attribute.

Parameters

string|array $val String to escape, or array of strings

Return Value

array|string

at line 55
static array|string raw2htmlname(array|string $val)

Convert a value to be suitable for an HTML ID attribute. Replaces non supported characters with a space.

Parameters

array|string $val String to escape, or array of strings

Return Value

array|string

See also

http://www.w3.org/TR/REC-html40/types.html#type-cdata

at line 77
static array|string raw2htmlid(array|string $val)

Convert a value to be suitable for an HTML ID attribute. Replaces non supported characters with an underscore.

Parameters

array|string $val String to escape, or array of strings

Return Value

array|string

See also

http://www.w3.org/TR/REC-html40/types.html#type-cdata

at line 99
static array|string raw2xml(array|string $val)

Ensure that text is properly escaped for XML.

Parameters

array|string $val String to escape, or array of strings

Return Value

array|string

See also

http://www.w3.org/TR/REC-xml/#dt-escape

at line 114
static array|string raw2js(array|string $val)

Ensure that text is properly escaped for Javascript.

Parameters

array|string $val String to escape, or array of strings

Return Value

array|string

at line 136
static string raw2json(mixed $val, int $options)

Encode a value as a JSON encoded string. You can optionally pass a bitmask of JSON constants as options through to the encode function.

Parameters

mixed $val Value to be encoded
int $options Optional bitmask of JSON constants

Return Value

string JSON encoded string

at line 148
static string array2json(array $val, int $options)

Encode an array as a JSON encoded string.

This is an alias to {@link raw2json()}

Parameters

array $val Array to convert
int $options Optional bitmask of JSON constants

Return Value

string JSON encoded string

at line 162
static string|array raw2sql(mixed|array $val, boolean $quoted = false)

Safely encodes a value (or list of values) using the current database's safe string encoding method

Parameters

mixed|array $val Input value, or list of values as an array
boolean $quoted Flag indicating whether the value should be safely quoted, instead of only being escaped. By default this function will only escape the string (false).

Return Value

string|array Safely encoded value in the same format as the input

at line 186
static string|array symbol2sql(string|array $identifier, string $separator = '.')

Safely encodes a SQL symbolic identifier (or list of identifiers), such as a database, table, or column name. Supports encoding of multi identfiers separated by a delimiter (e.g. ".")

Parameters

string|array $identifier The identifier to escape. E.g. 'SiteTree.Title'
string $separator The string that delimits subsequent identifiers

Return Value

string|array The escaped identifier. E.g. '"SiteTree"."Title"'

at line 202
static xml2raw($val)

Convert XML to raw text.

Parameters

$val

at line 219
static object|boolean json2obj(string $val)

Convert a JSON encoded string into an object.

Parameters

string $val

Return Value

object|boolean

at line 230
static array|boolean json2array(string $val)

Convert a JSON string into an array.

Parameters

string $val JSON string to convert

Return Value

array|boolean

at line 245
static array xml2array(string $val, boolean $disableDoctypes = false, boolean $disableExternals = false)

Converts an XML string to a PHP array See http://phpsecurity.readthedocs.org/en/latest/Injection-Attacks.html#xml-external-entity-injection

Parameters

string $val
boolean $disableDoctypes Disables the use of DOCTYPE, and will trigger an error if encountered. false by default.
boolean $disableExternals Disables the loading of external entities. false by default.

Return Value

array

at line 299
static string linkIfMatch(string $string)

Create a link if the string is a valid URL

Parameters

string $string The string to linkify

Return Value

string A link to the URL if string is a URL

at line 315
static string html2raw(string $data, bool $preserveLinks = false, int $wordWrap, array $config = null)

Simple conversion of HTML to plaintext.

Parameters

string $data Input data
bool $preserveLinks
int $wordWrap
array $config

Return Value

string

at line 395
static string raw2mailto($data)

There are no real specifications on correctly encoding mailto-links, but this seems to be compatible with most of the user-agents.

Does nearly the same as rawurlencode(). Please only encode the values, not the whole url, e.g. "mailto:test@test.com?subject=" . Convert::raw2mailto($subject)

Parameters

$data string

Return Value

string

See also

http://www.ietf.org/rfc/rfc1738.txt

at line 410
static string raw2url(string $title)

Convert a string (normally a title) to a string suitable for using in urls and other html attributes. Uses {@link URLSegmentFilter}.

Parameters

string $title

Return Value

string

at line 424
static string nl2os(string $data, string $nl = PHP_EOL)

Normalises newline sequences to conform to (an) OS specific format.

Parameters

string $data Text containing potentially mixed formats of newline sequences including \r, \r\n, \n, or unicode newline characters
string $nl The newline sequence to normalise to. Defaults to that specified by the current OS

Return Value

string

at line 435
static string base64url_encode(mixed $val)

Encode a value into a string that can be used as part of a filename.

All string data must be UTF-8 encoded.

Parameters

mixed $val Value to be encoded

Return Value

string

at line 445
static mixed base64url_decode(string $val)

Decode a value that was encoded with Convert::base64url_encode.

Parameters

string $val Value to be decoded

Return Value

mixed Original value