README

A modern, fluent PHP library for string manipulation with extensive functionality inspired by Laravel's Str class and enhanced with additional features for Brazilian Portuguese development.

🇧🇷 Versão em Português | 📖 English Documentation

Features

• 🔄 Fluent Interface: Chain methods for readable and maintainable code
• 🌍 Internationalization: Built-in support for Portuguese and English
• 🚀 Modern PHP: Requires PHP 8.2+ with full type declarations
• 📱 Brazilian Helpers: CPF, CNPJ, phone formatting and validation
• 🔧 Laravel-inspired: Methods compatible with Laravel's Str class
• 🧪 Well-tested: Comprehensive test suite
• 📚 Well-documented: Extensive documentation with examples

📖 When to use get() and when it's optional

✅ NO need for get() (automatic conversion):

• Echo and print: echo Str::of('hello')->upper()
• Concatenation: "Result: " . Str::of('test')->title()
• Interpolation: "Value: $str"
• Comparisons: if ($str == 'expected')
• Direct assignments: $var = Str::of('test')->lower()

⚠️ Needs explicit cast (string):

• PHP functions: strlen((string) $str)
• PHP functions: empty((string) $str)
• Arrays: ['key' => (string) $str]
• JSON: json_encode(['key' => (string) $str])

🔧 Always works with get():

• When in doubt, use .get() at the end
• To ensure full compatibility
• In contexts where string type is mandatory

Installation

composer require robertaodj/str

Quick Start

use Robertaodj\Str\Str;

// Create a string instance
$result = Str::of("  Hello World!  ")
    ->trim()
    ->lower()
    ->studly()
    ->get(); // "HelloWorld!"

// Static methods
echo Str::slug("Olá Mundo"); // "ola-mundo"
echo Str::kebab("HelloWorld"); // "hello-world"
echo Str::mask("12345678901", "###.###.###-##"); // "123.456.789-01"

Examples

Basic String Manipulation

use Robertaodj\Str\Str;

// Text cleaning and formatting
$text = Str::of("  Texto com acentos e símbolos!@#  ")
    ->trim()
    ->removeAccents()
    ->alphanumeric(' ')
    ->title()
    ->get(); // "Texto Com Acentos E Simbolos"

// Case conversions
echo Str::camel("hello-world"); // "helloWorld"
echo Str::snake("HelloWorld"); // "hello_world"
echo Str::studly("hello_world"); // "HelloWorld"

Brazilian Portuguese Features

// Document formatting
echo Str::mask("12345678901", "cpf"); // "123.456.789-01"
echo Str::mask("12345678000195", "cnpj"); // "12.345.678/0001-95"

// Capitalization with Portuguese rules
echo Str::of("o gato subiu no telhado da casa")
    ->capitalize('pt')
    ->get(); // "O Gato Subiu no Telhado da Casa"

Advanced Features

// Content validation
$html = "<p>Hello <b>World</b></p>";
echo Str::of($html)->isHtml()->get(); // true
echo Str::of($html)->stripTags()->get(); // "Hello World"

// Text truncation
$longText = "Lorem ipsum dolor sit amet...";
echo Str::of($longText)->limit(10)->get(); // "Lorem ipsu..."
echo Str::of($longText)->words(3)->get(); // "Lorem ipsum dolor..."

Available Methods

Validation Methods

• isEmail() - Check if string is a valid email
• isHtml() - Check if string contains HTML tags
• isJson() - Check if string is valid JSON
• isXml() - Check if string is valid XML
• isSerialized() - Check if string is serialized
• isUrl() - Check if string is a valid URL
• isUuid() - Check if string is a valid UUID

Transformation Methods

• camel() - Convert to camelCase
• studly() - Convert to StudlyCase
• snake() - Convert to snake_case
• kebab() - Convert to kebab-case
• slug() - Create URL-friendly slug
• title() - Convert to Title Case
• upper() - Convert to UPPERCASE
• lower() - Convert to lowercase

Filtering Methods

• alphanumeric() - Keep only alphanumeric characters
• numeric() - Keep only numbers
• alpha() - Keep only letters
• removeAccents() - Remove accents and diacritics
• stripTags() - Remove HTML/XML tags

Formatting Methods

• mask() - Apply formatting masks (CPF, CNPJ, phone, etc.)
• pad() - Pad string to specified length
• trim() - Remove whitespace from both ends
• truncate() - Truncate to specified length
• words() - Limit to specified number of words

Documentation

• 📖 Complete API Documentation
• 🔧 Usage Examples
• 🚀 Migration Guide
• 🇧🇷 Documentação em Português

Testing

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Fix code style
composer cs-fix

# Run static analysis
composer phpstan

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security related issues, please email security@robertaodj.com instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

Credits

• Robert D Jesus
• Based on Simpla Components Str
• Inspired by Laravel's Str class
• All Contributors