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.
- 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.
Add EzValidator to your pubspec:
dependencies:
ez_validator: any # or the latest version on PubTo 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.
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)),
},
);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);
- If there are validation errors,
errorswill 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,
errorswill 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
- If there are validation errors, the
errorsmap will contain field names and their corresponding error messages. - If the data object passes all validations,
errorswill be an empty map ({}). - The
datamap returned byvalidateSynccontains the processed data, which may include default values set by the schema.
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.
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.
The addMethod function opens up endless possibilities for custom validation logic, allowing EzValidator to be tailored to your specific validation needs.
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.
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.
EzValidator offers a wide range of validation methods to suit different data types and validation scenarios. Below is a breakdown of these methods:
-
.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 functionvalidWhenreturnsfalse, 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. Thevalidatorfunction should returnnullif 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 aconditionfunction, 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 inthenis 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 atransformFunctionwhich 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..union(List<EzValidator> validators): Used for composing "OR" types by combining multiple validators into a union
-
.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.
-
.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([String? message]): Checks if the value is a valid date. If the value is aDateTimeobject 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 aDateTimeobject 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 aDateTimeobject and is equal to or before the provideddate, the validation passes.
-
.boolean([String? message]): Validates whether the value is a boolean (trueorfalse). This method checks the data type of the value and ensures it is strictly a boolean.
-
.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.oneOfand is used to exclude certain values.
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.
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.
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:
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}}}}
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'}
/// Use .union to compose "OR" types.
final schema = EzSchema.shape({
'mixedField': EzValidator().union([
EzValidator<String>().isType(String),
EzValidator<num>().isType(num)
])
});
schema.catchErrors({'mixedField': 'test'}) // passed
schema.catchErrors({'mixedField': true}) // not passed
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."}}
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}
| with default locale | with French locale |
|---|---|
 |
 |