Text and Formatting

Text Helper

The Text class provides various helper methods for manipulating and formatting text.

Namespace: Medialight\Textstem\Helpers

toHtml

Return formatted HTML paragraph string with escaped special characters.

public static function toHtml($string): string

Parameters:

$string (string): The string to convert to HTML.

Returns:

(string): The formatted HTML paragraph string.

strip_bare

Strip out all formatting from some HTML.

public static function strip_bare($str, $treatasHTML = false): string

Parameters:

$str (string): The HTML string to strip formatting from.
$treatasHTML (bool): Whether to treat the input as HTML. Default is false.

Returns:

(string): The stripped string without formatting.

formatForSort

Format a string for sorting. (eg 'The Great Escape' => 'Great Escape, The')

public static function formatForSort(string $rawString): string

Parameters:

$rawString (string): The original string to be formatted.

Returns:

(string): The formatted string for sorting.

formatFromSort

Format a string from sorting. (eg 'Great Escape, The' => 'The Great Escape')

public static function formatFromSort(string $str): string

Parameters:

$str (string): The sorted string to be formatted.

Returns:

(string): The formatted string.

nicefy

Convert a string to a more readable format by handling hyphens, slashes, and camelCase.

public static function nicefy($str, $ucwrds = true, $keepHyphens = true): string

Parameters:

$str (string): The string to be formatted.
$ucwrds (bool): Whether to convert the result to title case. Default is true.
$keepHyphens (bool): Whether to keep hyphens in the string. Default is true.

Returns:

(string): The formatted string.

toArray

This function is the same as explode, but trims white space and skips empties.

public static function toArray(mixed $str = '', ?string $sep = ','): array

Parameters:

$str (mixed): The string to be exploded or an array to be returned as is.
$sep (string|null): The separator to use for exploding the string. Default is comma.

Returns:

(array): The resulting array after exploding and filtering.

truncate

Truncate a given text, preserving word boundaries and adding a signify chop with.

public static function truncate(mixed $text = '', ?int $length = 50, $signifyChopWith = '...'): string

Parameters:

$text (mixed): The text to be truncated. Default is an empty string.
$length (int|null): The maximum length of the truncated text. Default is 50.
$signifyChopWith (string): The signify chop with to be added at the end of the truncated text. Default is '...'.

Returns:

(string): The truncated text with signify chop with added.

truncateMiddle

Truncates a given text in the middle if it exceeds the specified length.

public static function truncateMiddle(mixed $text = '', ?int $length = 50, $signifyChopWith = '...'): string

Parameters:

$text (mixed): The text to truncate. Default is an empty string.
$length (int|null): The maximum length of the truncated text. Default is 50.
$signifyChopWith (string): The string to insert at the truncation point. Default is '...'.

Returns:

(string): The truncated text, if necessary.

CastStrData Helper

The CastStrData class provides helper methods for casting data to different types.

Namespace: Medialight\Textstem\Helpers

cast

Casts a value to the specified type.

public static function cast($v, $casts)

Parameters:

$v (mixed): The value to cast.
$casts (string): The type to cast to ('array', 'int', or default).

Returns:

(mixed): The value cast to the specified type.

Formatters Helper

The Formatters class provides helper methods for formatting various types of data.

Namespace: Medialight\Textstem\Helpers

format_for_id

Formats a string for use as an ID.

public static function format_for_id($str)

Parameters:

$str (string): The string to format.

Returns:

(string): The formatted string suitable for use as an ID.

format_for_sort

Formats a string for sorting.

public static function format_for_sort($str)

Parameters:

$str (string): The string to format.

Returns:

(string): The formatted string suitable for sorting.

format_from_name_sort

Formats a string from a name sort.

public static function format_from_name_sort($str, $harsh)

Parameters:

$str (string): The string to format.
$harsh (bool): Whether to use harsh formatting.

Returns:

(string): The formatted string.

nicefy (Formatters)

Makes a string more readable.

public static function nicefy($str, $ucwrds, $keepHyphens)

Parameters:

$str (string): The string to format.
$ucwrds (bool): Whether to convert the result to title case.
$keepHyphens (bool): Whether to keep hyphens in the string.

Returns:

(string): The formatted string.

titleFromFileName

Extracts a title from a file name.

public static function titleFromFileName($filepath)

Parameters:

$filepath (string): The file path to extract a title from.

Returns:

(string): The extracted title.

format_daterange_str (Formatters)

Formats a date range.

public static function format_daterange_str($start_date, $end_date)

Parameters:

$start_date (string): The start date string.
$end_date (string): The end date string.

Returns:

(string): The formatted date range string.

formatTimeRange (Formatters)

Formats a time range.

public static function formatTimeRange($t1, $t2)

Parameters:

$t1 (mixed): The start time (string or timestamp).
$t2 (mixed): The end time (string or timestamp).

Returns:

(string): The formatted time range string.

makePreview

Creates a preview of an array.

public static function makePreview($arr, $maxchar)

Parameters:

$arr (array): The array to create a preview of.
$maxchar (int): The maximum number of characters in the preview.

Returns:

(string): The preview string.

JsonFormatter Helper

The JsonFormatter class provides helper methods for formatting JSON data.

Namespace: Medialight\Textstem\Helpers

spaced

Adds spaces after commas and colons in JSON.

public static function spaced($json)

Parameters:

$json (string): The JSON string to format.

Returns:

(string): The formatted JSON string.

array

Formats a JSON array as HTML badges.

public static function array($json, $link = '')

Parameters:

$json (string): The JSON string to format.
$link (string): Optional link to wrap around each badge.

Returns:

(string): The HTML badges.

objectBadges

Parses JSON into objects and loops through printing as badges assuming obj->name exists.

public static function objectBadges($json, $link = '')

Parameters:

$json (string): The JSON string to format.
$link (string): Optional link to wrap around each badge.

Returns:

(string): The HTML badges.

generateHtmlFromJson

Generates HTML from JSON data.

public static function generateHtmlFromJson($data)

Parameters:

$data (mixed): The JSON data to format (string or array).

Returns:

(string): The generated HTML.

generateHtmlForElement

Generates HTML for a specific element.

public static function generateHtmlForElement($key, $value)

Parameters:

$key (string): The key of the element.
$value (mixed): The value of the element.

Returns:

(string): The generated HTML.

NumberFormats Helper

The NumberFormats class provides helper methods for formatting numbers, particularly file sizes.

Namespace: Medialight\Textstem\Helpers

bytesToHuman

Converts bytes to a human-readable format (e.g., KB, MB, GB).

public static function bytesToHuman($size, $precision = 2): string

Parameters:

$size (int): The size in bytes.
$precision (int): The number of decimal places to round to. Default is 2.

Returns:

(string): The human-readable file size.

humanToBytes

Converts a human readable file size value to a number of bytes that it represents. Supports the following modifiers: K, M, G and T.

public static function humanToBytes($value): int

Parameters:

$value (number|string): The human-readable file size (e.g., '10K', '5MB').

Returns:

(int): The size in bytes.

Examples:

humanToBytes(10);          // 10
humanToBytes('10b');       // 10
humanToBytes('10k');       // 10240
humanToBytes('10K');       // 10240
humanToBytes('10kb');      // 10240
humanToBytes('10Kb');      // 10240
humanToBytes('   10 KB '); // 10240

OptionFormatter Helper

The OptionFormatter class provides helper methods for formatting options arrays.

Namespace: Medialight\Textstem\Helpers

format

Makes sure an array of options takes a specific format.

public static function format($setup, $class = null)

Parameters:

$setup (mixed): The array of options to format, or a string which is either a method name in the component class or class name for a helper class (which should have method 'collectForSelectOptions').
$class (ClassString): The class of the component being set up. Default is null.

Returns:

(array): The formatted options array.

Format:

'options' => [
    'label' => 'Choose One',
    'value' => "value_1"
], [
    // ...etc
]

This function lets you specify options as a simple linear array like this:

'options' => ['publish', 'pending', 'archive']

Linear lists are treated as lists of values (and a label is created using the nicefy method). If you want to treat the list as a list of labels (and use the index or key as the value), include 'usekey' = 1 in the setup.