Ez Validator
EzValidator offers a dead-simple approach to field and object schema validation tailored for Flutter. Inspired by the intuitive API of Yup, EzValidator simplifies the process of defining and enforcing data schemas within your Flutter applications.
Key Features of EzValidator
- Flutter Schema Builder: Seamlessly integrate EzValidator into your Flutter projects to build and manage data validation schemas.
- Versatile Validation: Whether you need to validate individual fields or entire objects, EzValidator is designed to handle both with ease.
Installing
Add EzValidator to your pubspec:
dependencies:
ez_validator: any # or the latest version on Pub
Getting Started
To begin with EzValidator
, define a schema object that represents the structure and validation rules for your data. Below is an example demonstrating how to create a schema for user data, including validations for email, password, and date fields.
Defining a Schema
Create a schema using EzSchema.shape
where each field in the data object is associated with an EzValidator
specifying its validation rules:
final EzSchema userSchema = EzSchema.shape(
{
"email": EzValidator<String>(label: "Email").required().email(),
"password": EzValidator<String>(label: 'Password').required().minLength(8),
'date': EzValidator<DateTime>()
.required()
.date()
.minDate(DateTime(2019))
.maxDate(DateTime(2025)),
},
);
Validating Data
Use the catchErrors
method of the schema to validate a data object. This method returns a map of validation errors, if any:
final errors = userSchema.catchErrors({
'email': 'example@domain.com',
'password': '12345678',
'date': DateTime.now(),
});
print(errors);
Understanding the Output
- If there are validation errors,
errors
will contain a map of field names to error messages. For example:
{
"password": "Minimum six characters, at least one letter, one number and one special character",
"age": "The field must be greater than or equal to 18"
}
- If the data object is valid according to the schema,
errors
will be an empty map ({}
).
Additionally, use the validateSync
method to validate data and simultaneously retrieve the processed data along with any errors:
final (data, errors) = userSchema.validateSync({
'email': 'example@domain.com',
'password': '12345678',
'date': DateTime.now(),
});
print(data); // Processed data
print(errors); // Validation errors
Understanding the Output
- If there are validation errors, the
errors
map will contain field names and their corresponding error messages. - If the data object passes all validations,
errors
will be an empty map ({}
). - The
data
map returned byvalidateSync
contains the processed data, which may include default values set by the schema.
Custom Validation with addMethod
EzValidator
also supports custom validation rules through the addMethod
function. This feature allows you to define your own validation logic, making EzValidator
highly adaptable to various unique use cases.
Using addMethod
for Custom Validation
You can use addMethod
to add custom validation functions to your validator. Each function should take the value to be validated as an argument and return null
if the value passes the validation or an error message if it fails.
Here's an example of using addMethod
to validate a JSON structure:
final checkJson = EzValidator<Map<String, dynamic>>()
.addMethod((v) => v?['foo'] == 'bar' ? null : 'Foo should be bar')
.addMethod((v) => v?['bar'] == 'Flutter' ? null : 'Bar should be Flutter')
.addMethod((v) => v?['items'][0] == 'a' ? null : 'First item should be a')
.build();
final errors = checkJson({
'foo': 'bar',
'bar': 'Flutter',
'items': ['a', 'b', 'c']
});
print(errors); // Outputs the validation errors, if any
If any of these checks fail, the corresponding error message is returned.
Flexibility of Custom Validation
The addMethod
function opens up endless possibilities for custom validation logic, allowing EzValidator
to be tailored to your specific validation needs.
Direct Use in Flutter Widgets
EzValidator
is designed to integrate smoothly with Flutter widgets, providing a straightforward way to add validation to user inputs. One common use case is within forms, where you can directly use EzValidator
in form fields such as TextFormField
.
Example: Email Validation in a TextFormField
Here's an example of how to apply EzValidator
for email validation in a TextFormField
:
TextFormField(
validator: EzValidator<String>()
.required()
.email()
.build(),
decoration: InputDecoration(labelText: 'Email'),
),
If the input fails these validations, the corresponding error message is displayed under the TextFormField
.
Validation Methods
EzValidator
offers a wide range of validation methods to suit different data types and validation scenarios. Below is a breakdown of these methods:
-
General/Common Validations
.required([String? message])
: Ensures that the value is not null or empty. This is a fundamental validation to check for the presence of a value..isType(Type type, [String? message])
: Validates that the value matches the specifiedtype
. This method is useful for type checking in more dynamic contexts..minLength(int minLength, [String? message])
: Checks that the length of the value (String, List, or Map) is not less than the specifiedminLength
..maxLength(int maxLength, [String? message])
: Ensures that the length of the value (String, List, or Map) does not exceed the specifiedmaxLength
..addMethod(bool Function(T? v) validWhen, [String? message])
: Allows for the addition of custom validation logic. If the provided functionvalidWhen
returnsfalse
, the custom error message is returned..when(ValidationCallback<T> validator)
: Provides conditional validation based on the value of another field in the schema. The method accepts aref
, which refers to another field in the schema, and avalidator
, which is a function that executes the validation logic. Thevalidator
function should returnnull
if the validation passes or a custom error message if it fails. This method is particularly useful for scenarios where the validation of one field depends on the value of another field, such as confirming a password..dependsOn({required bool Function(Map<dynamic, dynamic>? ref) condition, required EzValidator<T> then, EzValidator<T>? orElse})
: Enables conditional validation based on the state of other fields within the same schema. This method requires acondition
function, which evaluates the schema's current values and decides which validation to apply based on its return value. If the condition istrue
, the validation defined inthen
is applied; otherwise, the validation inorElse
(if provided) is applied. This is especially useful for cases where the requirement for a field is dependent on another field's value, offering a flexible way to implement complex validation logic within your schema..transform(T Function(T) transformFunction)
: Applies a transformation function to the field's value before any validation is performed. The method takes atransformFunction
which receives the current field value and returns a transformed value. This method is useful for preprocessing the data, such as trimming strings, converting types, or formatting values, before applying the validation rules..arrayOf<EzValidator<T>>(EzValidator<T> itemValidator)
: when you have a list of items that need to be individually validated. This method is ideal for scenarios like validating a list of user inputs, where each input must pass certain validation criteria..schema<EzSchema>(EzSchema schema)
: is ideal for nested or complex data structures where multiple fields need to be validated in relation to each other. It's particularly useful in cases where you need to enforce a specific data format, such as validating JSON objects, complex forms, or data models.
-
String Validations
.email([String? message])
: Validates if the value is a valid email address..phone([String? message])
: Validates if the value is a valid phone number..ip([String? message])
: Validates if the value is a correct IPv4 address..ipv6([String? message])
: Validates if the value is a correct IPv6 address..url([String? message])
: Validates if the value is a valid URL address..uuid([String? message])
: Validates if the value is a valid UUID..lowerCase([String? message])
: Checks if the value is in lowercase..upperCase([String? message])
: Checks if the value is in uppercase..matches(RegExp reg, [String? message])
: Validates if the value matches the provided regular expression pattern.
-
Numerical Validations
.min(num min, [String? message])
: Validates if the numeric value is greater than or equal tomin
..max(num max, [String? message])
: Validates if the numeric value is less than or equal tomax
..positive([String? message])
: Validates if the numeric value is positive..negative([String? message])
: Validates if the numeric value is negative..number([String? message])
: Checks if the value is a number..isInt([String? message])
: Checks if the value is an integer..isDouble([String? message])
: Checks if the value is a double. Also validates integers, as they can be implicitly converted to doubles..notNumber([String? message])
: Checks if the value is not a number.
-
Date Validations
.date([String? message])
: Checks if the value is a valid date. If the value is aDateTime
object or can be parsed into aDateTime
, the validation passes..minDate(DateTime date, [String? message])
: Ensures the date value is not earlier than the specified minimum date. If the value is aDateTime
object and is equal to or after the provideddate
, the validation passes..maxDate(DateTime date, [String? message])
: Ensures the date value is not later than the specified maximum date. If the value is aDateTime
object and is equal to or before the provideddate
, the validation passes.
-
Boolean Validation
.boolean([String? message])
: Validates whether the value is a boolean (true
orfalse
). This method checks the data type of the value and ensures it is strictly a boolean.
-
List (Array) Validations
.listOf(Type type, [String? message])
: Validates that each element in the list is of the specifiedtype
. It iterates through the list and checks if each item matches the given type..oneOf(List<T> items, [String? message])
: Checks if the value is one of the specified items in the list. It is useful for ensuring a value is among a predefined set of options..notOneOf(List<T> items, [String? message])
: Ensures that the value is not one of the specified items in the list. This is the opposite of.oneOf
and is used to exclude certain values.
Using Custom Locales with EzValidator
EzValidator
allows the integration of custom locales, facilitating localization of error messages. Below is an example of creating an Arabic locale (ArLocale
) and applying it in EzValidator
.
Creating ArLocale
Define the Custom Locale: Implement the EzLocale
interface to create ArLocale
with Arabic error messages.
class ArLocale implements EzLocale {
const ArLocale();
// Implement all required methods with Arabic error messages
@override
String minLength(String v, int n, [String? label]) =>
'${label ?? 'الحقل'} يجب أن يحتوي على الأقل $n أحرف';
// ... other method implementations ...
@override
String required([String? label]) => '${label ?? 'الحقل'} مطلوب';
// Example implementation for a valid email
@override
String email(String v, [String? label]) =>
'${label ?? 'الحقل'} ليس بريدًا إلكترونيًا صحيحًا';
// ... further implementations for other methods ...
}
Set the Locale in EzValidator
: Configure EzValidator
to use the ArLocale
.
EzValidator.setLocale(const ArLocale());
Use Validators as Usual: Now, the validation error messages will be in Arabic.
Nested Validation Example with EzValidator
EzValidator
not only handles simple validations but also excels in managing complex, nested data structures. This is particularly useful when dealing with intricate data models, like user profiles with multiple layers of details. Here’s an example of how you can define a nested validation schema using EzValidator
:
Defining a Complex User Profile Schema
final EzSchema userProfileSchema = EzSchema.shape({
"firstName": EzValidator<String>().required(),
"lastName": EzValidator<String>().required(),
"email": EzValidator<String>().required().email(),
"age": EzValidator<int>().min(18).max(100),
'contactDetails': EzSchema.shape({
'mobile': EzValidator<String>()
.required()
.matches(RegExp(r'^\+\d{10,15}$'), 'Invalid phone number'),
'landline': EzValidator<String?>(optional: true),
}),
'address': EzSchema.shape({
'street': EzValidator<String>().required(),
'city': EzValidator<String>().required(),
'state': EzValidator<String>().required(),
'zipCode': EzValidator<num>().required(),
'country': EzSchema.shape({
'name': EzValidator<String>(defaultValue: 'TUNISIA').required(),
'code': EzValidator<String>().required(),
'continent': EzSchema.shape({
'name': EzValidator<String>().required(),
'code': EzValidator<String>().required(),
})
}),
}),
'employment': EzSchema.shape({
'current': EzValidator<String?>(optional: true),
'previous': EzSchema.shape({
'companyName': EzValidator<String>().required(),
'position': EzValidator<String>().required(),
'years': EzValidator<int>().min(1).max(50),
}),
}),
});
Validation
final (data, errors) = userProfileSchema.validateSync({
'firstName': 'John',
'lastName': 'Doe',
'email': 'john.doe@example.com',
'age': 30,
'contactDetails': {
'mobile': '+12345678901',
},
'address': {
'street': '123 Main St',
'city': 'Anytown',
'state': 'Anystate',
'zipCode': 12345,
'country': { }, // I will not define the country
},
'employment': {
'current': 'Current Company',
'previous': {
'companyName': 'Previous Company',
'position': 'Previous Position',
'years': 5,
},
},
});
print(data);
// Result of displayed data will contain country with default values
// {
// firstName: John,
// lastName: Doe,
// email: john.doe@example.com,
// age: 30,
// contactDetails: { mobile: +12345678901, landline: null },
// address:
// {
// street: 123 Main St,
// city: Anytown,
// state: Anystate,
// zipCode: 12345,
// country:
// { name: TUNISIA, code: null, continent: { name: null, code: null } },
// },
// employment:
// {
// current: Current Company,
// previous:
// {
// companyName: Previous Company,
// position: Previous Position,
// years: 5,
// },
// },
// }
//
print(errors)
// {address: {country: {code: The field is required, continent: {name: The field is required, code: The field is required}}}}
Example Usage of .when
and .transform
and .dependsOn
This example demonstrates how to use the .when
and .transform
methods in EzValidator
to perform conditional validations and pre-validate data transformations.
final EzSchema schema = EzSchema.shape({
// Use .transform to trim whitespace before validating the name
"name": EzValidator<String>()
.transform((value) => value.trim())
.minLength(3, "Name must be at least 3 characters long."),
// Use .when to validate confirmPassword based on the password field
"password": EzValidator<String>()
.minLength(8, "Password must be at least 8 characters long."),
"confirmPassword": EzValidator<String>().when(
"password",
(confirmValue, [ref]) =>
confirmValue == ref?["password"] ? null : "Passwords do not match",
)
});
var result = schema.validateSync({
"name": " John ",
"password": "password123",
"confirmPassword": "password123",
});
print(result); // Should be empty if no validation errors
/// Use .dependsOn to dynamically adjust field validation based on another field's value.
final EzSchema carValidationSchema = EzSchema.shape({
"car_type": EzValidator<CarType>(defaultValue: CarType.suv).required(),
"passangers_number": EzValidator<int>().dependsOn(
condition: (ref) => ref!["car_type"] == CarType.suv,
then: EzValidator<int>().required().max(6, 'Max 6 passangers'),
orElse: EzValidator<int>().required().max(4, 'Max 4 passangers'),
),
});
final errors = carValidationSchema.catchErrors({
"car_type": CarType.suv,
"passangers_number": 7,
});
print(errors); // {'passangers_number' : 'Max 6 passangers'}
Example Usage of .arrayOf
and .schema
This example shows how to use .arrayOf
for validating a list of items and .schema
for validating nested objects within a schema.
// Define a schema for individual student validation
final EzSchema studentSchema = EzSchema.shape({
"name": EzValidator<String>().required(),
"age": EzValidator<int>().min(18, "Students must be at least 18 years old."),
});
// Validator for validating a list of students
final EzValidator<List<Map<String, dynamic>>> studentsListValidator =
EzValidator<List<Map<String, dynamic>>>()
.required()
.arrayOf<Map<String, dynamic>>(
EzValidator<Map<String, dynamic>>().schema(studentSchema),
);
// Define a schema for a classroom, which includes a list of students
final EzSchema classroomSchema = EzSchema.shape({
"className": EzValidator<String>().required(),
"students": studentsListValidator,
});
var result = classroomSchema.validateSync({
"className": "Advanced Mathematics",
"students": [
{"name": "John Doe", "age": 20},
{"name": "Jane Smith", "age": 17}, // ---> This will cause a validation error
],
});
print(result.$2); // {students: {"age":"Students must be at least 18 years old."}}
Example Usage of noUnknown
in the .schema
final EzSchema strictSchema = EzSchema.shape(
{
'email': EzValidator<String>().required().email(),
'password': EzValidator<String>().required(),
'username': EzValidator<String>().required(),
},
noUnknown: true, // Disallow unknown fields
fillSchema: false, // Do not fill missing fields
);
final Map<String, dynamic> dataWithUnknown = {
'email': 'test@email.com',
'password': 'password',
'age': 30, // Unknown field
};
final (_, errors) = strictSchema.validateSync(dataWithUnknown);
print(errors) // {age: is not defined in the schema}
ShowCase
with default locale | with French locale |
---|---|