class Convert (View source)

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

Encode an array as a JSON encoded string.

static string|array
raw2sql(mixed|array $val, bool $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|bool
json2obj(string $val) deprecated

Convert a JSON encoded string into an object.

static array|bool
json2array(string $val) deprecated

Convert a JSON string into an array.

static array
xml2array(string $val, bool $disableDoctypes = false, bool $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 = 0, 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 = 0)

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

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

Convert a value to be suitable for an XML attribute.

Warning: Does not escape array keys

Parameters

array|string $val

String to escape, or array of strings

Return Value

array|string

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

Convert a value to be suitable for an HTML attribute.

Warning: Does not escape array keys

Parameters

string|array $val

String to escape, or array of strings

Return Value

array|string

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.

Warning: Does not escape array keys

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

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.

Warning: Does not escape array keys

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

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

Ensure that text is properly escaped for XML.

Warning: Does not escape array keys

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

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

Ensure that text is properly escaped for Javascript.

Warning: Does not escape array keys

Parameters

array|string $val

String to escape, or array of strings

Return Value

array|string

static string raw2json(mixed $val, int $options = 0) 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

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

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

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

Warning: Does not encode array keys

Parameters

mixed|array $val

Input value, or list of values as an array

bool $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

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"'

static array|string xml2raw(mixed $val)

Convert XML to raw text.

Warning: Does not decode array keys

Parameters

mixed $val

Return Value

array|string

static object|bool 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|bool

static array|bool 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|bool

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

Parameters

string $val
bool $disableDoctypes

Disables the use of DOCTYPE, and will trigger an error if encountered. false by default.

bool $disableExternals

Disables the loading of external entities. false by default. No-op in PHP 8.

Return Value

array

Exceptions

Exception

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

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

Simple conversion of HTML to plaintext.

Parameters

string $data

Input data

bool $preserveLinks
int $wordWrap
array $config

Return Value

string

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

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

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

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

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

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

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

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

Parameters

float $bytes
int $decimal

decimal precision

Return Value

string

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