README

SmartString: PHP Strings That HTML-Encode Themselves

SmartString lets you write template code that's shorter, easier to read, and XSS-safe by default. Values HTML-encode themselves the moment you echo, interpolate, or concatenate them, so one forgotten htmlspecialchars() can't become an injection.

Instead of writing code like this:

echo "<h1>" . htmlspecialchars($article['title'], ENT_QUOTES|ENT_SUBSTITUTE|ENT_HTML5, 'UTF-8') . "</h1>";
$summary = strip_tags($article['content']);                                             // remove tags
$summary = html_entity_decode($summary, ENT_QUOTES|ENT_SUBSTITUTE|ENT_HTML5, 'UTF-8');  // decode entities
$summary = substr($summary, 0, 120);                                                    // limit to 120 characters
echo "Summary: " . htmlspecialchars($summary, ENT_QUOTES|ENT_SUBSTITUTE|ENT_HTML5, 'UTF-8') . "...";

You can write code like this:

echo "<h1>$article->title</h1>";
echo "Summary: {$article->content->textOnly()->maxChars(120, '...')}\n";

SmartString encodes HTML output automatically and includes utility functions for common template tasks.

Documentation

Full guides and references (browse on GitHub):

• The Basics (read in order)
  • Getting Started - install, your first auto-encoded value, and the mental model
  • Encoding and HTML - how auto-encoding works and the methods that let real markup through
  • Text and Formatting - truncating, regex, dates, numbers, math, and custom functions with map()
  • Conditionals and Error Checking - fallbacks, checks, and the guards that stop the page
• Everyday Use
  • Common Patterns - copy-paste recipes for everyday template tasks
• Lookup
  • Method Reference - every method, grouped by what it returns
  • Troubleshooting - common error messages and gotchas, with fixes
  • Performance - how our automatic encoding is at least 3x faster than calling htmlspecialchars() yourself
  • AI Reference - the complete API in one dense file, written for AI coding assistants

You're Never Locked In

Use SmartString where it makes your code simpler, and plain PHP where you prefer it. The original value is always one call away:

// SmartString: ->value() returns the original value, in its original type
$name = $user->name->value();

// SmartArray (companion library): ->toArray() returns a plain nested array
$rows = $orders->toArray();

Security

Values encode for HTML text and quoted attribute values, and markup reaches the page only through the methods in Encoding and HTML. A link URL from user input still needs its scheme checked: encoding leaves javascript: intact. Report a security problem as described in SECURITY.md.

Related Libraries

• SmartArray - database rows as chainable collections, with fields returned as SmartStrings.
• ZenDB - database library that returns query results as SmartArrays of SmartStrings, so fields arrive HTML-safe.
• HtmlSecurityCheck - checks rich-text HTML for anything that could run script and lists each problem it finds.
• SvgSecurityCheck - checks uploaded SVG files for anything that could run script and lists each problem it finds.

Questions?

This library was developed for CMS Builder. Post a message in our "CMS Builder" forum here: https://www.interactivetools.com/forum/

License

MIT