Skip to content

method-reference.md

Latest commit

 

History

History
148 lines (113 loc) · 12.2 KB

method-reference.md

File metadata and controls

148 lines (113 loc) · 12.2 KB
Raw

Method Reference

Every method, grouped by what it returns and how it treats missing values. Each group heading links to the guide page that teaches those methods.

If you're working with arrays, the companion library SmartArray wraps them into collections of SmartStrings: SmartArrayHtml::new($record) takes a database row, $_REQUEST, or any array. SmartArray has its own method reference.

Contents:

Basic Usage

$str = SmartString::new("It's easy!<hr>");

echo $str;           // It&​apos;s easy!&​lt;hr&​gt; (HTML-encoded automatically)
echo $str->value();  // It's easy!<hr> (the original value)

echo $str->trim()->maxChars(60)->or('None');  // methods chain left to right

Here $str is an object, not a string. Whenever PHP needs it as a string (echo, print, "$str", concatenation), the object converts itself to its HTML-encoded value, which is why echo above prints It&apos;s easy!&lt;hr&gt;. The value() method is the escape hatch: it returns the original, unencoded value in its original type, ready for regular PHP code.

Type Conversion

These return the value as a plain PHP type, so they end the chain.

Method Description
->value() Returns the original, unencoded value in its original type - the escape hatch
->int() Returns the value as an integer
->float() Returns the value as a float
->bool() Returns the value as a boolean
->string() Returns the value as a string (original value, not HTML-encoded)
SmartString::getRawValue($value) Returns the original value when you don't know what you have: Smart* objects are converted to their original value, plain values pass through unchanged

Encoding

These return the encoded value as a plain string, so they end the chain. Missing values (null or "") return "", so echoing an empty field prints nothing, except where noted below.

Method Description
->htmlEncode() Returns the value as an HTML-encoded string
->urlEncode() Returns the value as a URL-encoded string
->jsonEncode() Returns the value as a JSON-encoded string; missing values stay valid JSON (null → null, "" → ""), malformed UTF-8 becomes � instead of throwing
->rawHtml() Alias for value() - reads clearly when you're outputting trusted HTML on purpose (returns the original value, so null stays null)
->nl2br() HTML-encodes special chars, then converts newlines to <br> tags (unlike PHP's nl2br(), output is XSS-safe)
->appendHtml($html) HTML-encodes the value, then appends your trusted markup as-is
->wrapHtml($before, $after) HTML-encodes the value, then wraps it in your trusted markup as-is

String Manipulation

These return a new SmartString, so you can keep chaining. Missing values (null or "") come through unchanged, so a later or() fallback still works.

Method Description
->append($value) Adds $value to the end of the current value
->prepend($value) Adds $value to the beginning of the current value
->wrap($before, $after) Wraps the value; pass "" for a side you don't want
->textOnly() Removes HTML tags, decodes entities, and trims whitespace
->trim(...$args) Trims whitespace from both ends, or pass a character list like PHP trim()
->maxWords($max, $ellipsis = '...') Limits the value to $max words; adds $ellipsis if text was cut off
->maxChars($max, $ellipsis = '...') Limits the value to $max characters; adds $ellipsis if text was cut off
->pregReplace($pattern, $replacement) Replaces text matching a regex; an invalid $pattern throws InvalidArgumentException, a value it can't process (bad UTF-8) returns null

Dates & Numbers

These return a new SmartString, so you can keep chaining. If the value is missing or not a valid date or number, the result is null - add or() after to show a fallback.

Method Description
->dateFormat($format = null) Formats as a date or datetime, e.g. dateFormat('Y-m-d H:i:s'); default: SmartString::$dateFormat
->numberFormat($decimals = 0) Formats the value as a number with thousands separators and $decimals decimal places
->percent($decimals = 0, $ifZero = null) Converts a decimal to a percentage, e.g. 0.24 becomes 24%; $ifZero is shown for zero values
->percentOf($total, $decimals = 0) Calculates what percentage the value is of $total, e.g. 24 of 100 is 24%
->add($value) Adds $value to the current number
->subtract($value) Subtracts $value from the current number
->multiply($value) Multiplies the current number by $value
->divide($value) Divides the current number by $value

Conditional Replacement

These return a new SmartString, so you can keep chaining. Each swaps in a replacement value when its condition matches - most commonly or(), to show a default when a field is empty.

Method Description
->or($fallback) Replaces missing values (null or "") with $fallback; zero counts as present
->ifNull($fallback) Replaces null with $fallback
->ifZero($fallback) Replaces zero with $fallback
->ifTrue($condition, $newValue) Replaces the value with $newValue when your condition is truthy
->ifEquals($match, $newValue) Replaces the value with $newValue when it loosely equals $match (==, so "5" matches 5)
->set($newValue) Replaces the value unconditionally - useful for storing the result of a match() or a calculation

Require a Value

Use these for values that must exist, like a record ID from the URL. If the value is missing (null or "") they stop the page; otherwise the chain continues. Zero counts as present.

Method Description
->orDie($text) Outputs the message and exits
->or404($text = null) Outputs a 404 header and the message (default: standard not-found text), then exits
->orThrow($text) Throws a RuntimeException with the message
->orRedirect($url) Redirects to $url and exits (throws RuntimeException if headers were already sent)

Value Checks

These return a plain true or false, typically used in if statements. Zero is "empty" but not "missing".

Method Description
->isEmpty() Returns true when the value is empty ("", null, false, 0, "0") - same as PHP empty()
->isNotEmpty() Returns true when the value has content - the exact opposite of isEmpty()
->isMissing() Returns true when the value is missing (null or ""); zero counts as present
->isNull() Returns true when the value is null

Custom Functions

Method Description
->map($callback, ...$args) Calls your function with the original value and returns the result as a new SmartString - runs even when the value is null

← Documentation Index | ← Prev: Common Patterns | Next: Troubleshooting →