A modern PHP string manipulation library with fluent interface and extensive functionality

v1.0.2 2025-08-02 18:42 UTC

This package is auto-updated.

Last update: 2025-08-05 13:55:03 UTC


README

Latest Version PHP Version Total Downloads License

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

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