Download the PHP package overtrue/laravel-text-guard without Composer

Laravel TextGuard

A powerful string sanitization and normalization tool for Laravel that can be used as validation rules or standalone utility.

English Documentation

Documentation

• Pipeline Guide - Complete guide to all pipeline steps
• Pipeline 指南 - 所有 pipeline 步骤的完整指南

Installation

Publish Configuration

Basic Usage

As a Utility

As Validation Rules

Model Auto-Filtering

Use the TextGuardable trait to provide automatic filtering for model fields:

When the model is saved, specified fields are automatically filtered:

Dynamic Field Management

FormRequest Integration

Pipeline Usage

Laravel TextGuard provides 14 built-in pipeline steps for text processing. Each pipeline step can be configured with specific parameters to meet different requirements.

Available Pipeline Steps

Basic Text Processing

• trim_whitespace - Remove leading/trailing whitespace (including full-width spaces)
• collapse_spaces - Collapse multiple consecutive spaces into single space
• remove_control_chars - Remove control characters while preserving newlines and tabs
• remove_zero_width - Remove zero-width characters (U+200B..200D, U+FEFF)

Unicode Processing

• unicode_normalization - Unicode normalization (NFC, NFD, NFKC, NFKD)
• fullwidth_to_halfwidth - Convert fullwidth characters to halfwidth
• normalize_punctuations - Normalize punctuation based on locale (zh/en)

HTML Processing

• strip_html - Remove all HTML tags
• html_decode - Decode HTML entities
• whitelist_html - Keep only allowed HTML tags and attributes

Character Filtering

• character_whitelist - Keep only allowed character types (with emoji support)
• collapse_repeated_marks - Limit repeated punctuation marks

Length Control

• visible_ratio_guard - Check visible character ratio
• truncate_length - Truncate text to maximum length

Pipeline Configuration Examples

Basic Text Cleaning

Username Processing

Rich Text Processing

Nickname with Emoji Support

Pipeline Parameter Types

The system automatically passes configuration to constructors based on type:

• Boolean values (true/false) → No parameter constructor: new Class()
• String values ('NFKC') → Single parameter constructor: new Class('NFKC')
• Array values (['max' => 100]) → Array parameter constructor: new Class(['max' => 100])

Usage Tips

1. Order matters: Pipeline steps are executed in configuration order
2. Basic cleanup first: Start with trim_whitespace, collapse_spaces, remove_control_chars, remove_zero_width
3. Unicode processing: Use unicode_normalization and fullwidth_to_halfwidth for international text
4. HTML handling: Use whitelist_html for rich text, strip_html for plain text
5. Length control last: Place visible_ratio_guard and truncate_length at the end

For detailed parameter information and more examples, see the Pipeline Guide.

Preset Configurations

Level-based Presets

safe Preset

Default preset suitable for most normal text input fields. Includes basic text sanitization features.

strict Preset

More restrictive filtering mode with stricter rules:

• No emoji characters allowed
• Converts all punctuation to half-width
• Higher visible character ratio requirement (0.8)
• Shorter text length limit (5000)

Function-specific Presets (Examples)

username Preset

Suitable for username input with stricter normalization.

nickname Preset

Suitable for user nicknames with emoji and Chinese punctuation support.

rich_text Preset

Suitable for rich text content, preserving safe HTML tags.

Extended Features

Register Custom Pipeline Steps

Get Available Steps

Create Custom Pipeline Steps

Constructor Configuration

All Pipeline steps now use constructor configuration, following traditional OOP design:

Configuration Passing Mechanism

The system automatically passes configuration to constructors based on type:

• true → No parameter constructor new Class()
• 'NFKC' → Single parameter constructor new Class('NFKC')
• ['max' => 100] → Array parameter constructor new Class(['max' => 100])

Real-world Usage Scenarios

User Registration Form

Article Content Management

Comment System

Search Keyword Processing

Batch Data Processing

Custom Pipeline Steps

Features

• Whitespace handling (trim, collapse spaces)
• Control character removal
• Zero-width character removal
• Unicode normalization
• Full-width to half-width conversion
• Punctuation normalization
• HTML tag processing
• Repeated punctuation collapsing
• Visibility checking
• Length truncation
• Extensible pipeline architecture
• Runtime custom step registration
• Emoji support
• Chinese punctuation support
• Character whitelist filtering

Testing

Code Quality

This project follows strict code quality standards:

License

MIT License