README

Display formatting utilities for WordPress with full internationalization support. Provides clean, consistent formatting for numbers, dates, text, and data presentation across WordPress themes and plugins.

Features

• 🌍 Internationalization Ready: Full i18n support using WordPress translation functions
• 📊 Number Formatting: Percentages and numeric values with WordPress standards
• 📅 Date/Time Formatting: WordPress-compatible date formatting with timezone support
• 📝 Text Formatting: HTML processing, truncation, and label generation
• ✅ Boolean Formatting: Translatable yes/no, on/off, true/false strings
• 📋 List Formatting: Smart lists with overflow handling and natural language conjunctions
• 🛡️ WordPress-Native: Leverages WordPress core functions for consistency

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later

Installation

composer require arraypress/wp-format-utils

Basic Usage

Boolean Formatting

use ArrayPress\FormatUtils\Format;

// Translatable boolean strings
Format::yes_no( true );              // 'yes' (translatable)
Format::yes_no( true, true );        // 'Yes' (translatable, title case)
Format::on_off( false );             // 'off' (translatable)
Format::true_false( true );          // 'true' (translatable)

// Perfect for admin interfaces and form display
$enabled = get_option( 'feature_enabled' );
echo Format::yes_no( $enabled, true ); // Shows 'Yes' or 'No' in user's language

Number Formatting

// WordPress i18n number formatting (returns em dash for non-numeric)
Format::numeric( 1234.56 );         // '1,234.56' (respects locale)
Format::numeric( 1234.56, 0 );      // '1,235' (no decimals)
Format::numeric( 'invalid' );       // '—' (em dash)

// Percentage formatting
Format::percentage( 0.75 );         // '75%'
Format::percentage( 0.756, 1 );     // '75.6%'

Date and Time Formatting

// WordPress i18n date formatting (accepts timestamp, string, or DateTime)
Format::date( '2024-01-15' );                    // 'January 15, 2024' (translated)
Format::date( '2024-01-15', 'Y-m-d' );          // '2024-01-15'
Format::date( time(), 'F j, Y', false );        // English only

// Duration formatting
Format::duration( 90 );                         // '1 minutes'
Format::duration( 3661 );                       // '1 hours 1 minutes'
Format::duration( 3661, true );                 // '1h 1m' (abbreviated)
Format::duration( 90061 );                      // '1 days 1 hours'

// Relative time
Format::time_ago( strtotime( '-2 hours' ) );    // '2 hours ago'

Text Formatting

// WordPress text processing
Format::html( "Hello\n\nWorld" );               // '<p>Hello</p><p>World</p>'

// Key to label conversion
Format::label( 'first_name' );                  // 'First Name'
Format::label( 'user-profile-id' );             // 'User Profile Id'

// Multibyte-safe truncation
Format::excerpt( $long_text, 100 );             // 'First 97 chars...'
Format::excerpt( $text, 50, '…' );              // 'First 49 chars…'

// Email link generation
Format::email_link( 'user@example.com' );       
// '<a href="mailto:user@example.com">user@example.com</a>'

Format::email_link( 'user@example.com', 'Contact Us' ); 
// '<a href="mailto:user@example.com">Contact Us</a>'

// Rating with proper pluralization
Format::rating( 1 );                            // '1 Star'
Format::rating( 4 );                            // '4 Stars'
Format::rating( 0 );                            // 'No Rating'

Utility Methods

// Em dash fallback for empty values
Format::maybe_dash( 'value' );                  // 'value'
Format::maybe_dash( '' );                       // '—'
Format::maybe_dash( null );                     // '—'

// Natural language lists
Format::list( ['Apple'] );                      // 'Apple'
Format::list( ['Apple', 'Banana'] );            // 'Apple and Banana'
Format::list( ['A', 'B', 'C'] );               // 'A, B and C'
Format::list( ['A', 'B', 'C'], ', ', ' or ' ); // 'A, B or C'

// Lists with overflow handling
$items = ['Theme A', 'Plugin B', 'Template C', 'Widget D', 'Block E'];

Format::list_with_overflow( $items, 3 );        // 'Theme A, Plugin B and 3 more'
Format::list_with_overflow( $items, 2 );        // 'Theme A and 4 more'

// Custom overflow text
Format::list_with_overflow( 
    $items, 
    3, 
    ' | ',           // separator
    ' & ',           // last separator  
    '%d others'      // overflow text
); // 'Theme A | Plugin B & 3 others'

API Reference

Boolean Formatting Methods

Number Formatting Methods

Date/Time Formatting Methods

Text Formatting Methods

Utility Methods

Constants

Common Use Cases

Admin Table Display

// Settings page display
function display_settings_table( $options ) {
    foreach ( $options as $key => $value ) {
        echo '<tr>';
        echo '<td>' . esc_html( Format::label( $key ) ) . '</td>';
        
        if ( is_bool( $value ) ) {
            echo '<td>' . esc_html( Format::yes_no( $value, true ) ) . '</td>';
        } elseif ( is_numeric( $value ) ) {
            echo '<td>' . esc_html( Format::numeric( $value ) ) . '</td>';
        } else {
            echo '<td>' . esc_html( Format::maybe_dash( $value ) ) . '</td>';
        }
        
        echo '</tr>';
    }
}

Content Lists

// Category display with overflow
$categories = wp_get_post_categories( $post_id, ['fields' => 'names'] );
echo 'Categories: ' . esc_html( Format::list_with_overflow( $categories, 3 ) );
// Output: "Categories: WordPress, PHP and 2 more"

// Tag cloud with natural language
$tags = get_the_tags( $post_id );
$tag_names = wp_list_pluck( $tags, 'name' );
echo 'Tagged: ' . esc_html( Format::list( $tag_names ) );
// Output: "Tagged: Development, Tutorial and Advanced"

Dashboard Statistics

$stats = get_site_statistics();

echo 'Total Users: ' . esc_html( Format::numeric( $stats['users'] ) );
echo 'Uptime: ' . esc_html( Format::duration( $stats['uptime_seconds'] ) );
echo 'Success Rate: ' . esc_html( Format::percentage( $stats['success_rate'] ) );
echo 'Last Updated: ' . esc_html( Format::time_ago( $stats['last_update'] ) );

Internationalization

All user-facing strings are translatable using WordPress i18n functions:

• Text Domain: arraypress
• Translation Functions: __(), _n() for plurals
• Translator Comments: Included for context

Translatable Strings

• Yes/No, On/Off, True/False formatting
• "X more" overflow text
• Star rating text
• "No Rating" text
• "ago" text

Requirements

• PHP 7.4+
• WordPress 5.0+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-2.0-or-later License.

Support

• Documentation
• Issue Tracker