Download the PHP package itools/smartarray without Composer

SmartArray: Enhanced Arrays with Chainable Methods and Automatic HTML Encoding

SmartArray extends PHP arrays with automatic HTML encoding and chainable utility methods. It adds powerful features for filtering, mapping, and data manipulation - making common array operations simpler, safer, and more expressive.

Table of Contents

• SmartArray: Enhanced Arrays with Chainable Methods and Automatic HTML Encoding
  • Table of Contents
  • Quick Start
  • Usage Examples
    • Highlighting Recent Articles with position()
    • Accessing Elements by Position with nth()
    • Looking Up Authors by ID with indexBy()
    • Organizing Books by Genre with groupBy()
    • Extracting Unique Tags with pluck(), unique(), and implode()
    • Building Dynamic HTML Tables with sprintf()
    • Creating Grid Layouts with isFirst() and isLast()
    • Debugging and Help
  • Method Reference
  • Questions?

Quick Start

Install via Composer:

Include the Composer autoloader and SmartArray class:

Convert an array to a SmartArray and use the recommended workflow:

See the Method Reference for more information on available methods.

Usage Examples

Highlighting Recent Articles with position()

The position() method returns an element's position within its parent array (starting from 1), making it easy to give special treatment to important items like featured articles based on their position:

Accessing Elements by Position with nth()

The nth() method provides a convenient way to access elements by their position, supporting both positive and negative indices. This is particularly useful for accessing specific items in ordered lists like search results, leaderboards, or recent activity feeds.

Key Features:

• Zero-based indexing: nth(0) returns the first element
• Negative indices: nth(-1) returns the last element
• Works with both indexed and associative arrays

Looking Up Authors by ID with indexBy()

When working with collections of records, you often need to look up specific records by their ID or another unique field. The indexBy() method makes this easy by creating an associative array using a specified field as the key:

Output:

Important Notes:

• If multiple records have the same key value, later records will overwrite earlier ones
• For collections with duplicate keys, use groupBy() instead to preserve all records
• Keys are automatically converted to strings (as per PHP array key behavior)
• Missing keys in the source data will be skipped with a warning

Need to preserve duplicate keys? Consider using groupBy() instead.

Organizing Books by Genre with groupBy()

When working with data that has multiple items sharing the same key (like books by genre, products by category, or employees by department), groupBy() helps organize them into logical groups while preserving all records:

Output:

Common Use Cases for groupBy():

• Products by category or manufacturer
• Employees by department or location
• Sales by region or time period
• Students by grade level or class
• Events by date or venue
• Comments by post or user
• Tasks by status or priority

Important Notes:

• Each group contains a new SmartArray of all matching records
• Original record order is preserved within groups
• Groups are created in order of first appearance
• Missing or null values in the group key will be skipped with a warning
• Use indexBy() instead if you only need one record per key

Extracting Unique Tags with pluck(), unique(), and implode()

When working with collections, you often need to extract a single field, remove duplicates, and produce a display string. Here's how SmartArray chains these operations into a single expressive pipeline.

Building Dynamic HTML Tables with sprintf()

The sprintf() method applies formatting to each element, making it easy to wrap values in HTML tags. Combined with implode(), you can build table rows in a single expression.

Key Features:

• Supports {value} and {key} as readable aliases for %1$s and %2$s
• Also works with standard sprintf formats: %s, %1$s, %2$s, etc.
• Values are automatically HTML-encoded for SmartArrayHtml (XSS-safe)
• Format string is applied to each element, then implode() joins them

Output:

Note how O'Connor, <script>, and & are safely HTML-encoded in the output.

Using {key} for Select Options:

Output:

Creating Grid Layouts with isFirst() and isLast()

SmartArray provides isFirst() and isLast() methods for position-based operations, making it easy to add opening and closing markup around iterated elements:

Debugging and Help

SmartArray provides helpful debugging tools to inspect your data structures and explore available methods.

Debug View Call print_r() on any SmartArray to see a detailed view of its structure:

The output shows the nested structure and metadata:

Interactive Help

Need a quick reference? Call help() on any SmartArray object to see available methods and usage examples:

Method Reference

Note: All methods return a new SmartArray object unless otherwise specified.

See Also: For working with SmartArrayHtml values, check out the included companion library SmartString. SmartArrayHtml values are SmartString objects with automatic HTML encoding and chainable methods: https://github.com/interactivetools-com/SmartString?tab=readme-ov-file#method-reference

Questions?

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