GUMP - A Fast PHP Data Validation & Filtering Library

๐ Overview
GUMP is a standalone PHP data validation and filtering library that makes validating any data easy and painless without
the reliance on a framework. GUMP has been serving the PHP community since 2013 and is trusted by thousands of
developers worldwide.
Key Features
- ๐ Zero Dependencies - Pure PHP, no external dependencies required
- ๐ 19 Languages - Built-in internationalization support
- โก High Performance - Lightweight and fast validation processing
- ๐ง Extensible - Easy to add custom validators and filters
- ๐ 76 Validators - Comprehensive set of validation rules out of the box
- ๐ก๏ธ Security Focused - Built-in XSS protection and data sanitization
- ๐ฏ Framework Agnostic - Works with any PHP project or framework
- ๐ฑ Modern PHP - Supports PHP 7.1 to 8.4+
Table of Contents
- Installation
- Requirements
- Quick Start
- Usage Examples
- Available Validators
- Available Filters
- Advanced Usage
- Internationalization
- Custom Validators & Filters
- Configuration
- Testing
- Contributing
- Security
- Changelog
- Support
- License
Installation
Via Composer (Recommended)
Manual Installation
- Download the latest release from GitHub Releases
- Extract and include
gump.class.php
in your project:
Requirements
- PHP: 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4+
- Extensions:
ext-mbstring
- Multibyte string support
ext-json
- JSON processing
ext-intl
- Internationalization functions
ext-bcmath
- Arbitrary precision mathematics
ext-iconv
- Character encoding conversion
Quick Start
Simple Validation
Simple Filtering
Usage Examples
Basic Validation with Custom Error Messages
File Upload Validation
Array and Nested Field Validation
Available Validators
GUMP provides 76 built-in validators for comprehensive data validation:
| Rule | Description |
|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **required** | Ensures the specified key value exists and is not empty (not null, not empty string, not empty array). |
| **contains**,one;two;use array format if one of the values contains semicolons | Verify that a value is contained within the pre-defined value set. |
| **contains_list**,value1;value2 | Verify that a value is contained within the pre-defined value set. Error message will NOT show the list of possible values. |
| **doesnt_contain_list**,value1;value2 | Verify that a value is contained within the pre-defined value set. Error message will NOT show the list of possible values. |
| **boolean**,strict | Determine if the provided value is a valid boolean. Returns true for: yes/no, on/off, 1/0, true/false. In strict mode (optional) only true/false will be valid which you can combine with boolean filter. |
| **valid_email** | Determine if the provided email has valid format. |
| **max_len**,240 | Determine if the provided value length is less or equal to a specific value. |
| **min_len**,4 | Determine if the provided value length is more or equal to a specific value. |
| **exact_len**,5 | Determine if the provided value length matches a specific value. |
| **between_len**,3;11 | Determine if the provided value length is between min and max values. |
| **alpha** | Determine if the provided value contains only alpha characters. |
| **alpha_numeric** | Determine if the provided value contains only alpha-numeric characters. |
| **alpha_dash** | Determine if the provided value contains only alpha characters with dashed and underscores. |
| **alpha_numeric_dash** | Determine if the provided value contains only alpha numeric characters with dashed and underscores. |
| **alpha_numeric_space** | Determine if the provided value contains only alpha numeric characters with spaces. |
| **alpha_space** | Determine if the provided value contains only alpha characters with spaces. |
| **numeric** | Determine if the provided value is a valid number or numeric string. |
| **integer** | Determine if the provided value is a valid integer. |
| **float** | Determine if the provided value is a valid float. |
| **valid_url** | Determine if the provided value is a valid URL. |
| **url_exists** | Determine if a URL exists & is accessible. |
| **valid_ip** | Determine if the provided value is a valid IP address. |
| **valid_ipv4** | Determine if the provided value is a valid IPv4 address. |
| **valid_ipv6** | Determine if the provided value is a valid IPv6 address. |
| **valid_cc** | Determine if the input is a valid credit card number. |
| **valid_name** | Determine if the input is a valid human name. |
| **street_address** | Determine if the provided input is likely to be a street address using weak detection. |
| **iban** | Determine if the provided value is a valid IBAN. |
| **date**,d/m/Y | Determine if the provided input is a valid date (ISO 8601) or specify a custom format (optional). |
| **min_age**,18 | Determine if the provided input meets age requirement (ISO 8601). Input should be a date (Y-m-d). |
| **max_numeric**,50 | Determine if the provided numeric value is lower or equal to a specific value. |
| **min_numeric**,1 | Determine if the provided numeric value is higher or equal to a specific value. |
| **starts**,Z | Determine if the provided value starts with param. |
| **required_file** | Determine if the file was successfully uploaded. |
| **extension**,png;jpg;gif | Check the uploaded file for extension. Doesn't check mime-type yet. |
| **equalsfield**,other_field_name | Determine if the provided field value equals current field value. |
| **guidv4** | Determine if the provided field value is a valid GUID (v4) |
| **phone_number** | Determine if the provided value is a valid phone number. |
| **regex**,/test-[0-9]{3}/ | Custom regex validator. |
| **valid_json_string** | Determine if the provided value is a valid JSON string. |
| **valid_array_size_greater**,1 | Check if an input is an array and if the size is more or equal to a specific value. |
| **valid_array_size_lesser**,1 | Check if an input is an array and if the size is less or equal to a specific value. |
| **valid_array_size_equal**,1 | Check if an input is an array and if the size is equal to a specific value. |
| **strong_password** | Validate strong password with uppercase, lowercase, number and special character. |
| **jwt_token** | Validate JWT token format. |
| **hash**,Array | Validate hash format for specified algorithm. |
| **no_sql_injection** | Detect common SQL injection patterns. |
| **no_xss** | Enhanced XSS detection beyond basic sanitize_string. |
| **uuid** | Validate UUID format (any version). |
| **base64** | Validate base64 encoded data. |
| **hex_color** | Validate hexadecimal color code. |
| **rgb_color** | Validate RGB color format. |
| **timezone** | Validate timezone identifier. |
| **language_code** | Validate language code (ISO 639). |
| **country_code** | Validate country code (ISO 3166). |
| **currency_code** | Validate currency code (ISO 4217). |
| **mac_address** | Validate MAC address format. |
| **domain_name** | Validate domain name format (without protocol). |
| **port_number** | Validate port number (1-65535). |
| **social_handle** | Validate social media handle format. |
| **latitude** | Validate latitude coordinate (-90 to 90). |
| **longitude** | Validate longitude coordinate (-180 to 180). |
| **postal_code**,Array | Validate postal code for specified country. |
| **coordinates** | Validate coordinates in lat,lng format. |
| **future_date** | Validate that date is in the future. |
| **past_date** | Validate that date is in the past. |
| **business_day** | Validate that date falls on a business day (Monday-Friday). |
| **valid_time** | Validate time format (HH:MM:SS or HH:MM). |
| **date_range**,2024-01-01;2024-12-31 | Validate date falls within specified range. |
| **even** | Validate that number is even. |
| **odd** | Validate that number is odd. |
| **prime** | Validate that number is prime. |
| **word_count**,min,10,max,500 | Validate word count within specified range. |
| **camel_case** | Validate camelCase format. |
| **snake_case** | Validate snake_case format. |
| **url_slug** | Validate URL slug format. |
Comprehensive Validator Reference
Essential Validators
required
- The most fundamental validator
between_len,min;max
- String length range validation
Real-World Usage Examples
User Registration Form
E-commerce Product Form
API Payload Validation
Security & Authentication Form
Geographic & Network Validation
Content & Format Validation
Advanced Validation Patterns
Conditional Validation
File Upload with Metadata
Nested Array Validation
๐ก Pro Tips:
Parameter Conflicts: When using pipe (|
) or semicolon (;
) in validator parameters, use array format:
Performance: Put faster validators first in chains:
Boolean Values: The boolean
filter accepts various formats:
Available Filters
GUMP includes 16 filters for data sanitization and transformation:
| Filter | Description |
|------------------------|-----------------------------------------------------------------------------------------------------------------------|
| **noise_words** | Replace noise words in a string (http://tax.cchgroup.com/help/Avoiding_noise_words_in_your_search.htm). |
| **rmpunctuation** | Remove all known punctuation from a string. |
| **urlencode** | Sanitize the string by urlencoding characters. |
| **htmlencode** | Sanitize the string by converting HTML characters to their HTML entities. |
| **sanitize_email** | Sanitize the string by removing illegal characters from emails. |
| **sanitize_numbers** | Sanitize the string by removing illegal characters from numbers. |
| **sanitize_floats** | Sanitize the string by removing illegal characters from float numbers. |
| **sanitize_string** | Sanitize the string by removing any script tags. |
| **boolean** | Converts ['1', 1, 'true', true, 'yes', 'on'] to true, anything else is false ('on' is useful for form checkboxes). |
| **basic_tags** | Filter out all HTML tags except the defined basic tags. |
| **whole_number** | Convert the provided numeric value to a whole number. |
| **ms_word_characters** | Convert MS Word special characters to web safe characters. ([โ โ] => ", [โ โ] => ', [โ] => -, [โฆ] => ...) |
| **lower_case** | Converts to lowercase. |
| **upper_case** | Converts to uppercase. |
| **slug** | Converts value to url-web-slugs. |
| **trim** | Remove spaces from the beginning and end of strings. |
Filter Chaining Example
Advanced Usage
Instance Methods
Field Name Customization
Global Error Message Customization
Internationalization
GUMP supports 19 languages out of the box:
Supported Languages: German (de), Greek (el), English (en), Esperanto (eo), Spanish (es), Persian (fa), French (fr),
Hebrew (he), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Dutch (nl), Portuguese Brazil (pt-br),
Russian (ru), Turkish (tr), Ukrainian (uk), Vietnamese (vi), Chinese Simplified (zh-CN)
Custom Validators & Filters
Adding Custom Validators
Adding Custom Filters
Extending GUMP Class
Configuration
Global Delimiter Configuration
Customize the delimiters used in validation rule strings:
Field Character Replacement
Testing
GUMP includes comprehensive test coverage with PHPUnit:
Running Tests in Docker
Contributing
We welcome contributions! Please read our Contributing Guidelines before submitting PRs.
Development Setup
- Fork the repository
- Clone your fork:
git clone https://github.com/yourusername/gump.git
- Install dependencies:
composer install
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes and add tests
- Run tests:
composer test
- Submit a pull request
Contribution Guidelines
- Add tests for new features and bug fixes
- Follow PSR-12 coding standards
- Update documentation for new validators/filters
- Add translations for new error messages
- Maintain backward compatibility
Areas We Need Help With
- ๐ Translations - Help us support more languages
- ๐งช Test Coverage - Add more edge case tests
- ๐ Documentation - Improve examples and guides
- ๐ Performance - Optimize validation algorithms
- ๐ก๏ธ Security - Security audits and improvements
Security
Security Best Practices
- Always validate AND filter user input
- Use appropriate validators for your data types
- Be cautious with
regex
validator - avoid ReDoS attacks
- Use
sanitize_string
filter to prevent XSS
- Validate file uploads thoroughly
- Keep GUMP updated to the latest version
Security Features
- XSS Protection: Built-in
sanitize_string
filter
- SQL Injection Prevention: Proper data validation
- File Upload Security: Extension and type validation
- Input Sanitization: Multiple sanitization filters
- Safe Defaults: Secure by default configuration
Support
Community Support
Statistics
- โญ GitHub Stars: 1000+
- ๐ฆ Downloads: 1M+ via Packagist
- ๐ญ Production Use: Thousands of projects
- ๐ Languages: 19 supported languages
- โก Performance: <1ms validation time for typical forms
- ๐งช Test Coverage: 100%
Why Choose GUMP?
โ
Battle-Tested
- 10+ years in production
- Trusted by thousands of developers
- Proven in high-traffic applications
โก Performance First
- Zero dependencies - no bloat
- Optimized algorithms - fast validation
- Memory efficient - low resource usage
๐ Security Focused
- XSS protection built-in
- Regular security audits
- Secure defaults everywhere
๐ Global Ready
- 19 languages supported
- UTF-8 compatible
- Timezone aware date validation
๐ ๏ธ Developer Friendly
- Clean, simple API
- Excellent documentation
- Extensive examples
- Framework agnostic
License
GUMP is open-source software licensed under the MIT License.