diff --git a/.gitignore b/.gitignore index 55794ef..3ff5c4c 100644 --- a/.gitignore +++ b/.gitignore @@ -13,5 +13,6 @@ vendor coverage build .phpunit.result.cache +.php-cs-fixer.cache user.env composer.lock \ No newline at end of file diff --git a/.php-cs-fixer.php b/.php-cs-fixer.php new file mode 100644 index 0000000..30b26d8 --- /dev/null +++ b/.php-cs-fixer.php @@ -0,0 +1,22 @@ +in(__DIR__) + ->exclude('vendor') + ->exclude('dev') + ->name('*.php'); + +return (new PhpCsFixer\Config()) + ->setRules([ + '@PSR12' => true, + 'array_syntax' => ['syntax' => 'short'], + 'no_unused_imports' => true, + 'ordered_imports' => ['sort_algorithm' => 'alpha'], + 'single_quote' => true, + 'trailing_comma_in_multiline' => ['elements' => ['arrays']], + 'no_extra_blank_lines' => true, + 'no_whitespace_in_blank_line' => true, + 'blank_line_before_statement' => ['statements' => ['return']], + ]) + ->setFinder($finder) + ->setRiskyAllowed(false); diff --git a/README.md b/README.md index 017c445..d8915f7 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![Coverage Status](https://coveralls.io/repos/github/Wixel/GUMP/badge.svg?branch=master)](https://coveralls.io/github/Wixel/GUMP?branch=master) [![License](https://poser.pugx.org/wixel/gump/license)](https://packagist.org/packages/wixel/gump) -## 🚀 Overview +## 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 @@ -14,33 +14,32 @@ 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+ +- **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](#-installation) -- [Requirements](#-requirements) -- [Quick Start](#-quick-start) -- [Usage Examples](#-usage-examples) -- [Available Validators](#-available-validators) -- [Available Filters](#-available-filters) -- [Advanced Usage](#-advanced-usage) -- [Internationalization](#-internationalization) -- [Custom Validators & Filters](#-custom-validators--filters) -- [Configuration](#-configuration) -- [Testing](#-testing) -- [Contributing](#-contributing) -- [Security](#-security) -- [Changelog](#-changelog) -- [Support](#-support) -- [License](#-license) +- [Installation](#installation) +- [Requirements](#requirements) +- [Quick Start](#quick-start) +- [Usage Examples](#usage-examples) +- [Available Validators](#available-validators) +- [Available Filters](#available-filters) +- [Advanced Usage](#advanced-usage) +- [Internationalization](#internationalization) +- [Custom Validators & Filters](#custom-validators--filters) +- [Configuration](#configuration) +- [Testing](#testing) +- [Contributing](#contributing) +- [Security](#security) +- [Support](#support) +- [License](#license) ## Installation @@ -63,11 +62,11 @@ require_once 'path/to/gump.class.php'; - **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 + - `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 @@ -88,11 +87,11 @@ $is_valid = GUMP::is_valid([ ]); if ($is_valid === true) { - echo "✅ All data is valid!"; + echo "All data is valid!"; } else { // Display validation errors foreach ($is_valid as $error) { - echo "❌ " . $error . "\n"; + echo "Error: " . $error . "\n"; } } ``` @@ -289,6 +288,7 @@ GUMP provides **76 built-in validators** for comprehensive data validation: | **camel_case** | Validate camelCase format. | | **snake_case** | Validate snake_case format. | | **url_slug** | Validate URL slug format. | + ## Comprehensive Validator Reference @@ -446,27 +446,30 @@ $rules = [ ]; ``` -> **💡 Pro Tips**: +> **Pro Tips**: > > **Parameter Conflicts**: When using pipe (`|`) or semicolon (`;`) in validator parameters, use array format: +> > ```php -> // ❌ Wrong - will break parsing +> // Wrong - will break parsing > 'field' => 'regex,/part|of;pattern/' -> -> // ✅ Correct - use array format +> +> // Correct - use array format > 'field' => ['regex' => '/part|of;pattern/'] > ``` > > **Performance**: Put faster validators first in chains: +> > ```php -> // ✅ Good - required fails fast for empty values +> // Good - required fails fast for empty values > 'email' => 'required|valid_email|max_len,255' -> -> // ❌ Less efficient - validates email format on empty values +> +> // Less efficient - validates email format on empty values > 'email' => 'valid_email|required|max_len,255' > ``` > > **Boolean Values**: The `boolean` filter accepts various formats: +> > ```php > // All these become TRUE: '1', 1, 'true', true, 'yes', 'on' > // All these become FALSE: '0', 0, 'false', false, 'no', 'off', null, '' @@ -496,6 +499,7 @@ GUMP includes 16 filters for data sanitization and transformation: | **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 @@ -522,6 +526,42 @@ $filtered = GUMP::filter_input([ ## Advanced Usage +### Singleton Pattern + +GUMP supports a singleton pattern for cases where you want to reuse the same instance across your application: + +```php +// Get the singleton instance +$gump = GUMP::get_instance(); + +// Subsequent calls return the same instance +$sameGump = GUMP::get_instance(); + +// Both variables reference the same object +var_dump($gump === $sameGump); // true +``` + +### Field Helper Method + +The `field()` static method provides safe array access with a default fallback: + +```php +// Safely get a value from an array with a default +$username = GUMP::field('username', $_POST, 'guest'); + +// Returns 'guest' if 'username' key doesn't exist +$email = GUMP::field('email', $_POST); // Returns null if not set + +// Useful for optional form fields +$data = [ + 'name' => 'John', + 'age' => 25 +]; + +$name = GUMP::field('name', $data); // 'John' +$country = GUMP::field('country', $data, 'US'); // 'US' (default) +``` + ### Instance Methods ```php @@ -750,11 +790,17 @@ We welcome contributions! Please read our [Contributing Guidelines](CONTRIBUTING ### 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 +- **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 + +### Contributors + + + + ## Security @@ -779,51 +825,9 @@ We welcome contributions! Please read our [Contributing Guidelines](CONTRIBUTING ### Community Support -- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/wixel/gump/issues) -- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/wixel/gump/discussions) -- 📚 **Documentation**: [GitHub Wiki](https://github.com/wixel/gump/wiki) - -## 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** +- **Bug Reports**: [GitHub Issues](https://github.com/wixel/gump/issues) +- **Feature Requests**: [GitHub Discussions](https://github.com/wixel/gump/discussions) +- **Documentation**: [GitHub Wiki](https://github.com/wixel/gump/wiki) ## License diff --git a/ci/boot.php b/ci/boot.php index 6d76131..98ec984 100644 --- a/ci/boot.php +++ b/ci/boot.php @@ -1,4 +1,5 @@ getMethods(), function($method) { + $validators = array_filter($reflect->getMethods(), function ($method) { return strpos($method->name, VALIDATORS_PREFIX) !== false; }); @@ -22,7 +24,7 @@ function get_gump_validators() { $ruleExampleParameter = $docblock->getTag('example_parameter'); $item = [ - 'description' => $ruleDescription + 'description' => $ruleDescription, ]; if (!is_null($ruleExampleParameter)) { @@ -37,7 +39,8 @@ function get_gump_validators() { return $result; } -function get_docs_validators(string $readmePath) { +function get_docs_validators(string $readmePath) +{ $readmeContents = file_get_contents($readmePath); preg_match_all('/
(.*?)<.div>/ms', $readmeContents, $outerMatches); @@ -56,19 +59,20 @@ function get_docs_validators(string $readmePath) { $result[$ruleMatch[1]] = [ 'rule' => $rawRule, - 'description' => trim($matches[2][$key]) + 'description' => trim($matches[2][$key]), ]; } return $result; } -function get_gump_filters() { - $reflect = new ReflectionClass("GUMP"); +function get_gump_filters() +{ + $reflect = new ReflectionClass('GUMP'); $methodsToIgnore = ['filter_input', 'filter_rules', 'filter_to_method']; - $filters = array_filter($reflect->getMethods(), function($method) use($methodsToIgnore) { + $filters = array_filter($reflect->getMethods(), function ($method) use ($methodsToIgnore) { return strpos($method->name, FILTERS_PREFIX) === 0 && !in_array($method->name, $methodsToIgnore); }); @@ -81,7 +85,7 @@ function get_gump_filters() { $ruleExampleParameter = $docblock->getTag('example_parameter'); $item = [ - 'description' => $ruleDescription + 'description' => $ruleDescription, ]; if (!is_null($ruleExampleParameter)) { @@ -96,8 +100,8 @@ function get_gump_filters() { return $result; } - -function get_docs_filters(string $readmePath) { +function get_docs_filters(string $readmePath) +{ $readmeContents = file_get_contents($readmePath); preg_match_all('/
(.*?)<.div>/ms', $readmeContents, $outerMatches); @@ -116,10 +120,9 @@ function get_docs_filters(string $readmePath) { $result[$ruleMatch[1]] = [ 'rule' => $rawRule, - 'description' => trim($matches[2][$key]) + 'description' => trim($matches[2][$key]), ]; } return $result; } - diff --git a/ci/check_filters_docs.php b/ci/check_filters_docs.php index da9bc6e..c5e3b45 100644 --- a/ci/check_filters_docs.php +++ b/ci/check_filters_docs.php @@ -1,4 +1,5 @@ XML; - + file_put_contents('build/logs/clover.xml', $placeholderXml); - + echo "✅ Created placeholder coverage file for Coveralls compatibility\n"; echo "ℹ️ To enable real coverage, install xdebug or pcov extension\n"; } -echo "Coverage workflow completed successfully\n"; \ No newline at end of file +echo "Coverage workflow completed successfully\n"; diff --git a/ci/dump_filters_docs.php b/ci/dump_filters_docs.php index 5b31807..b0dc93e 100644 --- a/ci/dump_filters_docs.php +++ b/ci/dump_filters_docs.php @@ -1,24 +1,24 @@ '**trim**', - 'description' => 'Remove spaces from the beginning and end of strings (PHP).' - ] + 'description' => 'Remove spaces from the beginning and end of strings (PHP).', + ], ]; -$rows = array_map(function($v) { +$rows = array_map(function ($v) { return [$v['rule'], $v['description']]; }, array_merge(get_gump_filters(), $extraRules)); - $tableBuilder = new \MaddHatter\MarkdownTable\Builder(); $tableBuilder - ->headers(['Filter','Description']) - ->align(['L','L']) - ->rows($rows); + ->headers(['Filter','Description']) + ->align(['L','L']) + ->rows($rows); $readme = file_get_contents(README_FILE); @@ -29,4 +29,3 @@ file_put_contents(README_FILE, $replaced); print('Filters docs updated!'.PHP_EOL); - diff --git a/ci/dump_validators_docs.php b/ci/dump_validators_docs.php index efe5083..4abfedb 100644 --- a/ci/dump_validators_docs.php +++ b/ci/dump_validators_docs.php @@ -1,16 +1,17 @@ headers(['Rule','Description']) - ->align(['L','L']) - ->rows($rows); + ->headers(['Rule','Description']) + ->align(['L','L']) + ->rows($rows); $readme = file_get_contents(README_FILE); @@ -21,4 +22,3 @@ file_put_contents(README_FILE, $replaced); print('Validators docs updated!'.PHP_EOL); - diff --git a/ci/generate_phpunit_config.php b/ci/generate_phpunit_config.php index e5ade1e..9410119 100644 --- a/ci/generate_phpunit_config.php +++ b/ci/generate_phpunit_config.php @@ -1,4 +1,5 @@ =7.1", @@ -39,6 +40,8 @@ "scripts": { "test": "php ./vendor/bin/phpunit", "dump": "php ./ci/dump_filters_docs.php && php ./ci/dump_validators_docs.php", - "check": "php ./ci/check_filters_docs.php && php ./ci/check_validators_docs.php && php ./ci/check_validators_translations.php" + "check": "php ./ci/check_filters_docs.php && php ./ci/check_validators_docs.php && php ./ci/check_validators_translations.php", + "lint": "php ./vendor/bin/php-cs-fixer fix --dry-run --diff", + "lint:fix": "php ./vendor/bin/php-cs-fixer fix" } } diff --git a/coverage.xml b/coverage.xml new file mode 100644 index 0000000..7362153 --- /dev/null +++ b/coverage.xml @@ -0,0 +1,640 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gump.class.php b/gump.class.php index 4299fe6..9f1f740 100644 --- a/gump.class.php +++ b/gump.class.php @@ -5,18 +5,18 @@ /** * GUMP - A Fast PHP Data Validation & Filtering Library - * - * GUMP is a standalone PHP data validation and filtering library that makes validating - * any data easy and painless without the reliance on a framework. Supports 41 validators, - * 15+ filters, internationalization (19 languages), and custom validators/filters. - * + * + * GUMP is a standalone PHP data validation and filtering library that makes validating + * any data easy and painless without the reliance on a framework. Supports 76 validators, + * 16 filters, internationalization (19 languages), and custom validators/filters. + * * @package GUMP * @version 1.x * @author Sean Nieuwoudt * @copyright 2013-2025 Sean Nieuwoudt * @license MIT * @link https://github.com/wixel/gump - * + * * @since 1.0 */ class GUMP @@ -106,14 +106,14 @@ public static function get_instance() /** * Basic HTML tags allowed in the basic_tags filter. - * + * * @var string */ public static $basic_tags = '