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) deprecated

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) deprecated

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
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 array|string
xml2raw(mixed $val)

Convert XML to raw text.

static object|boolean
json2obj(string $val) deprecated

Convert a JSON encoded string into an object.

static array|boolean
json2array(string $val) deprecated

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.

static string
upperCamelToLowerCamel($str)

Converts upper camel case names to lower camel case, with leading upper case characters replaced with lower case.

static int
memstring2bytes(string $memString)

Turn a memory string, such as 512M into an actual number of bytes.

static string
bytes2memstring(float $bytes, int $decimal)

No description

static string
slashes(string $path, string $separator = DIRECTORY_SEPARATOR, bool $multiple = true)

Convert slashes in relative or asolute filesystem path. Defaults to DIRECTORY_SEPARATOR

Details

at line 39
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 50
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 65
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 88
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 115
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 133
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 159
static string raw2json(mixed $val, int $options) deprecated

deprecated 4.4.0:5.0.0 Use json_encode() instead

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 174
static string array2json(array $val, int $options) deprecated

deprecated 4.4.0:5.0.0 Use json_encode() instead

Encode an array as a JSON encoded string.

Parameters

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

Return Value

string JSON encoded string

at line 191
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 217
static string 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' or list of identifiers to be joined via the separator.
string $separator The string that delimits subsequent identifiers

Return Value

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

at line 229
static array|string xml2raw(mixed $val)

Convert XML to raw text.

Parameters

mixed $val

Return Value

array|string

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

deprecated 4.4.0:5.0.0 Use json_decode() instead

Convert a JSON encoded string into an object.

Parameters

string $val

Return Value

object|boolean

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

deprecated 4.4.0:5.0.0 Use json_decode() instead

Convert a JSON string into an array.

Parameters

string $val JSON string to convert

Return Value

array|boolean

at line 286
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

Exceptions

Exception

at line 358
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 376
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 459
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:[email protected]?subject=" . Convert::raw2mailto($subject)

Parameters

$data string

Return Value

string

See also

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

at line 475
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 490
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 502
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 513
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

at line 534
static string upperCamelToLowerCamel($str)

Converts upper camel case names to lower camel case, with leading upper case characters replaced with lower case.

Tries to retain word case.

Examples: - ID => id - IDField => idField - iDField => iDField

Parameters

$str

Return Value

string

at line 572
static int memstring2bytes(string $memString)

Turn a memory string, such as 512M into an actual number of bytes.

Preserves integer values like "1024" or "-1"

Parameters

string $memString A memory limit string, such as "64M"

Return Value

int

at line 593
static string bytes2memstring(float $bytes, int $decimal)

Parameters

float $bytes
int $decimal decimal precision

Return Value

string

at line 615
static string slashes(string $path, string $separator = DIRECTORY_SEPARATOR, bool $multiple = true)

Convert slashes in relative or asolute filesystem path. Defaults to DIRECTORY_SEPARATOR

Parameters

string $path
string $separator
bool $multiple Collapses multiple slashes or not

Return Value

string