Download the PHP package moe-mizrak/validator-guard without Composer

Validator Guard

ValidatorGuard enables attribute-driven validation to control Laravel method behavior.

Attribute validation is a powerful way to validate method parameters, method results, and method behavior in a declarative way.

If the transaction amount is not between 100 and 10,000, the exception will be thrown/logged (based on throwing or logging enabled in config).

Table of Contents

• 🤖 Requirements
• 🏁 Get Started
• 🧩 Configuration
• 🎨 Usage
  • Using valguard Helper
  • Using Service Container Bindings
  • Attributes
    • IntervalGuard
    • DateGuard
    • AllowedValuesGuard
    • CallbackGuard
    • ArrayKeysExistGuard
  • Create Your Own Attribute
• 💫 Contributing
• 📜 License

🤖 Requirements

• PHP 8.2 or higher
• Validator Guard Core

🏁 Get Started

You can install the package via composer:

You can publish the validator-guard config file with:

🧩 Configuration

And the details of validator-guard config file options as follows:

• attributes: Here add the attributes that are used for Validation Guard. You can add the attributes that will be handled before method execution to the before array, and the attributes that will be handled after method execution to the after array. Some attributes are already added to the config file. You can remove or add new attributes as needed. You can check the details of the attributes in the Attributes section.
  • before: Attributes processed before method execution, allowing validation to be handled upfront, which avoids unnecessary method calls and improves performance.
  • after: Attributes processed after method execution, enabling validations that depend on method results or cases where method execution is needed (e.g., logging, database operations) even if validation fails.
• class_list: Here add all classes that you use attribute validation in order to bind them to ValidatorGuardCore in the service provider. Whenever these classes are resolved by the container, the package will initiate the ValidatorGuardCore to mimic the classes as a wrapper and handle validation. Check the Using Service Container Bindings section for more details.
• throw_exceptions: Enable/Disable throwing exceptions in case of validation failure. (🚩default: true)
• log_exceptions: Enable/Disable logging exceptions in case of validation failure. (🚩default: false)
• log_channel: Set an option for the default channel for logging so that it can be configured when needed (only applicable if VALIDATOR_GUARD_LOG_EXCEPTIONS is enabled). (🚩default: stack)

You can also set the throw_exceptions, log_exceptions, and log_channel options in the .env file as follows:

🎨 Usage

There are two ways to use Validator Guard, either by using the valguard helper or service container bindings.

[!IMPORTANT] Service container bindings is not recommended for classes that cannot be resolved by the container, such as facades or helpers, or for classes requiring parameters like runtime-specific data.

It is also unsuitable for objects that are short-lived, require complex setup, and so on.

Using valguard Helper

Helper method valguard offers a simple way to use Validator Guard for classes that cannot be resolved by the container or require runtime-specific data. For example, if you have a class named UserService, and method named getTransactionAmount that you want to use for attribute validation:

You can use the valguard helper as follows:

(You can check the details of the IntervalGuard attribute in the Attributes section.)

[!NOTE] For valguard helper method, you do NOT need to add the classes that you use for attribute validation to the class_list in the configuration file. And classes do NOT have to be resolved by the container.

Using Service Container Bindings

By using service container bindings, you need to add the classes that you use for attribute validation to the class_list in the configuration file. For the classes that you add to the class_list, the package will bind them to the ValidatorGuardCore in the service provider. So whenever these classes are resolved by the container, the package will initiate the ValidatorGuardCore to mimic the classes as a wrapper and handle validation.

For example, if you have a class named UserService that you want to use for attribute validation, you need to add the class to the class_list in the configuration file as follows:

And let's say you have a method named getTransactionAmount in the UserService class that you want to validate the attributes. You can add the attributes that you want to validate to the method as follows:

In this example, the getTransactionAmount method will be validated by the IntervalGuard attribute after the method execution. (You can check the details of the IntervalGuard attribute in the Attributes section.)

And whenever UserService is resolved by the container (e.g. Dependency Injection, app() helper etc.), the package will initiate the ValidatorGuardCore to mimic the UserService as a wrapper and handle validation:

Attributes

More attributes will be added in the future. You can also create/add your custom attributes as explained in the Create Your Own Attribute section. We will cover the following attributes in this section:

• IntervalGuard
• DateGuard
• AllowedValuesGuard
• CallbackGuard
• ArrayKeysExistGuard

[!TIP] Attribute flags as follows:

• TARGET_METHOD : Marks that attribute declaration is allowed only in class methods.
• IS_REPEATABLE : Attribute declaration in the same place is allowed multiple times.
• TARGET_PARAMETER : Marks that attribute declaration is allowed only in function or method parameters.

IntervalGuard

The IntervalGuard attribute is used to validate the method result within a specified interval. Attribute flags for the IntervalGuard: TARGET_METHOD, IS_REPEATABLE

IntervalGuard is listed in the after array in the configuration file attributes option because it validates the method result after the method execution.

Sample usage:

And when the getTransactionAmount method is called, the result will be validated by the IntervalGuard attribute after the method execution.

InntervalGuard attribute parameters:

• lowerBound (float): The lower bound of the interval. (🚩required)
• operator (string): The operator to be used for comparison. (🚩required)
  • '<': Less than
  • '<=': Less than or equal to
  • '==': Equal to
  • '!=': Not equal to
  • '>': Greater than
  • '>=': Greater than or equal to
• upperBound (float|null): The upper bound of the interval.

Basically it checks: lowerBound < result < upperBound or lowerBound <= result <= upperBound based on the operator and son on.

IntervalGuard attribute is repeatable, so you can add multiple IntervalGuard attributes to the same method. For instance:

In this example, the getTransactionAmount method result will be validated by the IntervalGuard attribute twice after the method execution. The first validation will check if the transaction amount is bigger than 10, and the second validation will check if the transaction amount is less than or equal to 30.

• Potential use-cases for IntervalGuard Attribute:

  • Age Validation:

  • Login Attempt Monitoring:

  • Credit Score Validation:

There can be many other use cases for the IntervalGuard attribute. You can use it for any method that requires interval validation for the method result.

DateGuard

The DateGuard attribute is used to validate whether the given date parameter is in the future, past, weekdays, weekends, today, tomorrow or between two dates and so on. Attribute flag for the DateGuard: TARGET_PARAMETER

DateGuard is listed in the before array in the configuration file attributes option because it validates the method parameter before the method execution, which benefits the performance by avoiding unnecessary method execution.

Sample usage:

And when the createEvent method is called, the eventDate parameter will be validated by the DateGuard attribute before the method execution.

DateGuard attribute parameters:

• paramPosition (int): The position of the parameter in the method. (🚩required)
• boundary (string): The boundary to be used for comparison. (🚩required)
  • DateGuard::FUTURE: The date must be in the future.
  • DateGuard::FUTURE_OR_PRESENT: The date must be in the future or now.
  • DateGuard::PAST: The date must be in the past.
  • DateGuard::PAST_OR_PRESENT: The date must be in the past or now.
  • DateGuard::BETWEEN: The date must be between two dates. (! range parameter is required)
  • DateGuard::NOT_BETWEEN: The date must not be between two dates. (! range parameter is required)
  • DateGuard::WEEKDAYS: The date must be a weekday.
  • DateGuard::WEEKENDS: The date must be a weekend.
  • DateGuard::TODAY: The date must be today.
  • DateGuard::TOMORROW: The date must be tomorrow.

• range (array|null): The range of dates, it must include upper_bound and lower_bound keys. (🚩required if boundary is BETWEEN or NOT_BETWEEN)

  • upper_bound (string): The upper bound of the date range. (🚩required if range array is provided)
  • lower_bound (string): The lower bound of the date range. (🚩required if range array is provided)

• Potential use-cases for DateGuard Attribute:

  • Subscription Management:

  • Historical Data Retrieval:

  • Event Scheduling:

  • Reservation System:

There can be many other use cases for the DateGuard attribute. You can use it for any method that requires date validation for the method parameter.

AllowedValuesGuard

The AllowedValuesGuard attribute is used to validate whether the given parameter is one of the allowed values. Attribute flag for the AllowedValuesGuard: TARGET_PARAMETER

AllowedValuesGuard is listed in the before array in the configuration file attributes option because it validates the method parameter before the method execution.

Sample usage:

And when the createEvent method is called, the eventType parameter will be validated by the AllowedValuesGuard attribute before the method execution.

AllowedValuesGuard attribute parameters:

• paramPosition (int): The position of the parameter in the method. (🚩required)

• values (array): The allowed values for the parameter. (🚩required)

• Potential use-cases for AllowedValuesGuard Attribute:

  • Language Selection:

  • User Role Assignment:

  • Payment Method Validation:

  • Order Status Update:

There can be many other use cases for the AllowedValuesGuard attribute. You can use it for any method that requires allowed values validation for the method parameter.

CallbackGuard

The CallbackGuard attribute is used to invoke a specified class method with given parameters and validate its result against the expected value. Attribute flag for the CallbackGuard: TARGET_METHOD, IS_REPEATABLE

CallbackGuard is listed in the before array in the configuration file attributes option because it validates the method parameter before the method execution.

Sample usage:

And when the processPayment method is called, the isPaymentMethodSupported method of the PaymentGateway class will be invoked with the given parameters, and the result of isPaymentMethodSupported method will be validated by the CallbackGuard attribute before the processPayment method execution.

CallbackGuard attribute parameters:

• className (string): The class name of the callback method. (🚩required)
• methodName (string): The method name of the callback method. (🚩required)
• params (array|null): The parameters to be passed to the callback method.

• expectedResult (mixed): The expected result of the callback method. It can be any type: string, null, int, bool, array, object etc.

• Potential use-cases for CallbackGuard Attribute:

  • Active Payment Methods:

  • User Permissions/Authentications:

  • Withdraw Availability:

  • Subscription Management:

There can be many other use cases for the CallbackGuard attribute. You can use it for any method that requires callback method validation before the method execution.

ArrayKeysExistGuard

The ArrayKeysExistGuard attribute is used to validate whether array key exists in the method array result or array parameter. Attribute flag for the ArrayKeysExistGuard: TARGET_METHOD, IS_REPEATABLE

ArrayKeysExistGuard is listed in the after array in the configuration file attributes option because it validates the method result after the method execution, along with method parameters.

Sample usage:

And when the getUserData method is called, the result array will be validated by the ArrayKeysExistGuard attribute after the method execution.

ArrayKeysExistGuard attribute parameters:

• keys (array): The keys to be checked in the array. (🚩required)
• inMethodResult (bool|null): If true, the keys will be checked in the method result array. If false while inParam is true, the keys will be checked in the method parameter array.
• inParam (bool|null): If true, the keys will be checked in the method parameter array.

• paramPosition (int|null): The position of the parameter in the method. (🚩required if inParam is true)

• Potential use-cases for ArrayKeysExistGuard Attribute:

  • Validating API Responses:

  • Order Data Validation:

  • Validating Request Parameters:

  • Payment Gateway Payload Validation:

There can be many other use cases for the ArrayKeysExistGuard attribute. You can use it for any method that requires array key validation for the method result or method parameter.

Create Your Own Attribute

You can create your custom attribute quite easily and use it for attribute validation. For this purpose, follow the steps below:

• Create a new attribute class that implements the ValidationAttributeInterface interface. (use MoeMizrak\ValidatorGuardCore\Contracts\ValidationAttributeInterface;)

• Add the new attribute class to the attributes array in the validator-guard config file.
  • If the newly created attribute validation logic in handle method requires method execution (e.g. It makes use of method result, you do some logging or database operations which are crucial etc.) then add the attribute to the after array.
  • Otherwise, add it to the before array in case the attribute validation logic does not require method execution. This will improve performance by avoiding unnecessary method calls.

• Now you can use the new attribute for attribute validation in your methods as explained in the Usage section.

  [!NOTE] Check out Using valguard Helper sections for more details in order to decide how to trigger the attribute validation.

💫 Contributing

Your contributions are welcome! f you'd like to improve this package, simply create a pull request with your changes. Your efforts help enhance its functionality and documentation.

If you find this package useful, please consider ⭐ it to show your support!

📜 License

Validator Guard is an open-sourced software licensed under the MIT license.