wixel / gump
A fast, extensible & stand-alone PHP input validation class that allows you to validate any data.
Installs: 1 079 505
Dependents: 61
Suggesters: 0
Security: 0
Stars: 1 168
Watchers: 83
Forks: 341
Open Issues: 15
Requires
- php: >=7.1
- ext-bcmath: *
- ext-iconv: *
- ext-intl: *
- ext-json: *
- ext-mbstring: *
Requires (Dev)
- kamermans/docblock-reflection: ^1.0
- maddhatter/markdown-table: ^1.0
- mockery/mockery: ^1.3
- php-coveralls/php-coveralls: ^2.5
- phpspec/prophecy: ^v1.10|^v1.17
- phpunit/phpunit: ^6|^9
This package is not auto-updated.
Last update: 2024-10-28 17:10:05 UTC
README
GUMP is a standalone PHP data validation and filtering class that makes validating any data easy and painless without the reliance on a framework. GUMP is open-source since 2013.
Supports wide range of PHP versions (php7.1 to php8.3) and ZERO dependencies!
Install with composer
composer require wixel/gump
Short format example for validations
$is_valid = GUMP::is_valid(array_merge($_POST, $_FILES), [ 'username' => 'required|alpha_numeric', 'password' => 'required|between_len,4;100', 'avatar' => 'required_file|extension,png;jpg', 'tags' => 'required|alpha_numeric', // ['value1', 'value3'] 'person.name' => 'required', // ['person' => ['name' => 'value']] 'persons.*.age' => 'required' // ['persons' => [ // ['name' => 'value1', 'age' => 20], // ['name' => 'value2'] // ]] ]); // 1st array is rules definition, 2nd is field-rule specific error messages (optional) $is_valid = GUMP::is_valid(array_merge($_POST, $_FILES), [ 'username' => ['required', 'alpha_numeric'], 'password' => ['required', 'between_len' => [6, 100]], 'avatar' => ['required_file', 'extension' => ['png', 'jpg']] ], [ 'username' => ['required' => 'Fill the Username field please.'], 'password' => ['between_len' => '{field} must be between {param[0]} and {param[1]} characters.'], 'avatar' => ['extension' => 'Valid extensions for avatar are: {param}'] // "png, jpg" ]); if ($is_valid === true) { // continue } else { var_dump($is_valid); // array of error messages }
Short format example for filtering
$filtered = GUMP::filter_input([ 'field' => ' text ', 'other_field' => 'Cool Title' ], [ 'field' => ['trim', 'upper_case'], 'other_field' => 'slug' ]); var_dump($filtered['field']); // result: "TEXT" var_dump($filtered['other_field']); // result: "cool-title"
Long format example
$gump = new GUMP(); // set validation rules $gump->validation_rules([ 'username' => 'required|alpha_numeric|max_len,100|min_len,6', 'password' => 'required|max_len,100|min_len,6', 'email' => 'required|valid_email', 'gender' => 'required|exact_len,1|contains,m;f', 'credit_card' => 'required|valid_cc' ]); // set field-rule specific error messages $gump->set_fields_error_messages([ 'username' => ['required' => 'Fill the Username field please, its required.'], 'credit_card' => ['extension' => 'Please enter a valid credit card.'] ]); // set filter rules $gump->filter_rules([ 'username' => 'trim|sanitize_string', 'password' => 'trim', 'email' => 'trim|sanitize_email', 'gender' => 'trim', 'bio' => 'noise_words' ]); // on success: returns array with same input structure, but after filters have run // on error: returns false $valid_data = $gump->run($_POST); if ($gump->errors()) { var_dump($gump->get_readable_errors()); // ['Field <span class="gump-field">Somefield</span> is required.'] // or var_dump($gump->get_errors_array()); // ['field' => 'Field Somefield is required'] } else { var_dump($valid_data); }
⭐ Available Validators
Important: If you use Pipe or Semicolon as parameter value, you must use array format.
$is_valid = GUMP::is_valid(array_merge($_POST, $_FILES), [ 'field' => 'regex,/partOf;my|Regex/', // NO 'field' => ['regex' => '/partOf;my|Regex/'] // YES ]);
⭐ Available Filters
Filter rules can also be any PHP native function (e.g.: trim).
Other Available Methods
/** * Setting up the language, see available languages in "lang" directory */ $gump = new GUMP('en'); /** * This is the most flexible validation "executer" because of it's return errors format. * * Returns bool true when no errors. * Returns array of errors with detailed info. which you can then use with your own helpers. * (field name, input value, rule that failed and it's parameters). */ $gump->validate(array $input, array $ruleset); /** * Filters input data according to the provided filterset * * Returns array with same input structure but after filters have been applied. */ $gump->filter(array $input, array $filterset); // Sanitizes data and converts strings to UTF-8 (if available), optionally according to the provided field whitelist $gump->sanitize(array $input, $whitelist = null); // Override field names in error messages GUMP::set_field_name('str', 'Street'); GUMP::set_field_names([ 'str' => 'Street', 'zip' => 'ZIP Code' ]); // Set custom error messages for rules. GUMP::set_error_message('required', '{field} is required.'); GUMP::set_error_messages([ 'required' => '{field} is required.', 'valid_email' => '{field} must be a valid email.' ]);
Creating your own validators and filters
Adding custom validators and filters is made easy by using callback functions.
/** * You would call it like 'equals_string,someString' * * @param string $field Field name * @param array $input Whole input data * @param array $params Rule parameters. This is usually empty array by default if rule does not have parameters. * @param mixed $value Value. * In case of an array ['value1', 'value2'] would return one single value. * If you want to get the array itself use $input[$field]. * * @return bool true or false whether the validation was successful or not */ GUMP::add_validator("equals_string", function($field, array $input, array $params, $value) { return $value === $params; }, 'Field {field} does not equal to {param}.'); // You might want to check whether a validator exists first GUMP::has_validator($rule); /** * @param string $value Value * @param array $param Filter parameters (optional) * * @return mixed result of filtered value */ GUMP::add_filter("upper", function($value, array $params = []) { return strtoupper($value); }); // You might want to check whether a filter exists first GUMP::has_filter($rule);
Alternately, you can simply create your own class that extends GUMP. You only have to have in mind:
- For filter methods, prepend the method name with "filter_".
- For validator methods, prepend the method name with "validate_".
class MyClass extends GUMP { protected function filter_myfilter($value, array $params = []) { return strtoupper($value); } protected function validate_myvalidator($field, array $input, array $params = [], $value) { return $input[$field] === 'good_value'; } } $validator = new MyClass(); $validated = $validator->validate($_POST, $rules);
Global configuration
This configuration values allows you to change default rules delimiters (e.g.: required|contains,value1;value2
to required|contains:value1,value2
).
GUMP::$rules_delimiter = '|'; GUMP::$rules_parameters_delimiter = ','; GUMP::$rules_parameters_arrays_delimiter = ';';