This packages allows you to validate arbitrary business requirements within your application.
You can basically validate anything as long as you can make a logical expression out of it.
Examples:
- Extend Laravel Gates/Policies with extensive validations based on your business rules
- Validate rules stored on your database models, eg. Coupon Code availability, Subscription validations, ..
- Perform any other arbitrary data validation within your classes based on e.g. request input, ...
- ...
Your options are basically endless
You can install the package via composer:
composer require jkbennemann/laravel-foliage
You can publish the config file with:
php artisan vendor:publish --tag="foliage-config"
This is the contents of the published config file:
return [
'available_rules' => [
//add your rules here
//SampleRule::class,
],
'rule_parser' => \Jkbennemann\Foliage\Core\RuleParser::class,
'payload_namespace' => 'App\Services\Foliage\Payloads',
'rules_namespace' => 'App\Services\Foliage\Rules',
'validator' => \Jkbennemann\Foliage\Validator\TreeValidator::class,
'validation_data_builder' => \Jkbennemann\Foliage\Validator\ValidationDataBuilder::class,
];
The whole concept of this package is to enable arbitrary validations of business rules.
To achieve this we will create a binary tree from your set of rules.
The resulting tree can then be validated by a given input of data.
For each rule the required data to validate against will automatically be taken from the provided payload.
Each tree node later will be expressed as an array, containing the following data.
[
'alias' => null,
'children' => [
//sub nodes
],
'data' => [
//data of your rule
],
'name' => 'rule_key',
'operation' => 'AND|OR|NOT|null',
'type' => 'node|leaf',
]
To create new you can either use the class provided by the package or just make use of the Facade for an easy and expressive API.
$availableRules = config('foliage.available_rules');
$ruleParser = new \Jkbennemann\Foliage\Core\RuleParser($availableRules);
$foliage = new Jkbennemann\Foliage\Core\Rule($ruleParser);
$rule = $foliage->single(SampleRule::class, ['sample' => 'data']);
$rule = $foliage->and([
[SampleRule::class, ['sample' => 'data']),
[AnotherRule::class, ['another_sample' => 'data']),
]);
$rule = $foliage->or([
[SampleRule::class, ['sample' => 'data']),
[AnotherRule::class, ['another_sample' => 'data']),
]);
use Jkbennemann\Foliage\Facades\Rule;
//Single rule usage
$rule = Rule::single(
SampleRule::class, ['sample' => 'data']
);
$rule = Rule::not(
SampleRule::class, ['sample' => 'data']
);
//Multi rule usage
$rule = Rule::and(
Rule::single(SampleRule::class, ['sample' => 'data']),
Rule::not(AnotherRule::class, ['another_sample' => 'data']),
);
$rule = Rule::or(
Rule::single(SampleRule::class, ['sample' => 'data']),
Rule::not(AnotherRule::class, ['another_sample' => 'data']),
Rule::and(
Rule::not(ThirdRule::class, ['another_sample' => 'data']),
Rule::not(ThirdRule::class, ['another_sample' => 'data']),
)
);
A sample representation of a simple and
rule will look like this
$rule = Rule::and(
Rule::single(SampleRule::class, ['sample' => 'data']),
Rule::not(AnotherRule::class, ['another_sample' => 'data']),
);
$structure = $rule->toArray();
echo $rule->jsonSerialize();
{
"alias": null,
"children":
[
{
"alias": null,
"children":
[],
"data":
{
"sample": "data"
},
"name": "sample_rule",
"operation": null,
"type": "leaf"
},
{
"alias": null,
"children":
[],
"data":
{
"another_sample": "data"
},
"name": "another_rule",
"operation": null,
"type": "leaf"
}
],
"data": null,
"name": null,
"operation": "AND",
"type": "node"
}
If you want to use the same rule multiple times, with different options you will need to specify an alias to the rule.
A alias basically overrides the argument name for the payload to validate against.
Assuming you as an administrator want to perform an action on behalf of a user of your application.
You as the administrator have the right to do so, but the user under consideration itself has not.
$payload = [
'user_is_admin' => $user->isAdmin(),
'performing_user_is_admin' => $currentLoggedInUser->isAdmin(),
];
$rule = Rule::or(
Rule::single(IsAdminRule::class)->alias('performing_user_is_admin'),
Rule::and(
Rule::not(IsAdminRule::class)->alias('user_is_admin'),
Rule::not(IsAllowedUser::class, ['user' => 'allowed_user']),
),
);
Eventually you want to store the tree structure inside your database to validate against eloquent models.
In this case you model should implement the HasValidationRules
trait provided by the package.
This gives you access to those rules.
Your database field should be a json
field if you're using MySQL/MariaDB.
use Jkbennemann\Foliage\Core\HasValidationRules;
class CouponCode extends Model {
use HasValidationRules;
protected $casts = [
'database_field_name' => 'array',
];
//..
protected function rulesFieldName(): string
{
return 'database_field_name';
}
}
Your model now has access to
$node = $coupon->validationNode(); //returns a Node object for validation
If you have an array, already in the tree structure, you can create a node from it like so
$ruleData = [
'alias' => null,
'children' => [
[
'alias' => null,
'children' => [],
'data' => [
'foo' => 'bar',
],
'name' => 'rule_1',
'operation' => null,
'type' => 'leaf',
],
[
'alias' => null,
'children' => [],
'data' => [
'bar' => 'baz',
],
'name' => 'rule_2',
'operation' => null,
'type' => 'leaf',
],
],
'data' => null,
'name' => null,
'operation' => 'AND',
'type' => 'node',
]
$builder = app(\Jkbennemann\Foliage\Core\TreeBuilder::class);
$node = $builder->build($ruleData);
To validate a created set of rules you can
- invoke the
validate()
method of the Foliage class - create your own validator
- call the
validate()
method on aNode
instance
$rule = Rule::single(SampleRule::class, ['name' => 'John Doe']);
$node = $rule->node();
//payload constructed during your application's request lifecycle.
$payload = [
'name' => 'John Doe'
];
//manual instantiation
//returns `Result` object
$foliage = new Foliage($validator, $treeBuilder);
$result = $foliage->validateSilently($node, $payload); // does not throw an exception on error
$foliage->validate($node, $payload); // throws exception on error
//using Facade
//returns `Result` object
$result = \Jkbennemann\Foliage\Facades\Foliage::validate($node, $payload)
$result->isValid(); //true
$result->errors(); //empty collection
By default, the validator throws an exception on first occurring validation error.
If you want to change this behaviour you can instruct the validator not to raise an exception.
$validator = new TreeValidator(new ValidationDataBuilder(), new PostOrderEvaluator());
$validator->withoutExceptions();
$isValid = $validator->evaluate($node, $payload);
$errors = $validator->errors();
$validator->evaluate($node, $payload)
The package makes use of the Laravel container, by taking the settings from the config file config/foliage.php
Because of this you can also instantiate a validator by calling the container.
use Jkbennemann\Foliage\Validator\Contracts\BaseValidator;
$validator = app(BaseValidator::class);
$validator->withoutExceptions();
$validator->withExceptions();
If you want to create a new rule, you can run the artisan
command.
php artisan validation:create-rule SampleRule
This command creates a new rule within the namespace, specified inside the config file.
The content will be
<?php
declare(strict_types=1);
namespace App\Services\BusinessRequirements\Rules;
use Jkbennemann\Foliage\Core\BaseValidationRule;
use Jkbennemann\Foliage\Core\Payload\BaseValidationPayload;
use Jkbennemann\Foliage\Exceptions\RuleValidation;
class SampleRule extends BaseValidationRule
{
/** @throws RuleValidation */
protected function validation(BaseValidationPayload $payload): void
{
//your implementation
}
protected function key(): string
{
return 'sample';
}
protected function inverseValidationException(BaseValidationPayload $payload): RuleValidation
{
throw new RuleValidation($this, 'error_message', $payload, 'custom_key');
}
}
If you want to create a payload class that can be used for a specific rule, you can run the artisan
command.
php artisan validation:create-payload AvailabilityPayload
This command creates a new payload within the namespace, specified inside the config file.
The content will be
<?php
declare(strict_types=1);
namespace App\Services\BusinessRequirements\Payloads;
use Jkbennemann\Foliage\Core\Payload\BaseValidationPayload;
class AvailabilityPayload extends BaseValidationPayload
{
public function __construct(
) {
}
}
You can add any arguments to the constructor you like, e.g:
public function __construct(public \Illuminate\Support\Carbon $date) {}
Now inside of you validation rule, you can override the used payload class for this rule as follows:
class SampleRule extends BaseValidationRule
{
/**
* @param AvailabilityPayload $payload
* @throws RuleValidation
*/
protected function validation(BaseValidationPayload $payload): void
{
$ruleSettings = $this->settings();
$dateNeeded = $ruleSettings['until'];
if ($payload->date->lt($dateNeeded)) {
return;
}
throw new \Jkbennemann\Foliage\Exceptions\RuleValidation($this, 'Not available', $payload);
}
//..
public function payloadObjectClass(): string
{
return AvailabilityPayload::class;
}
}
To construct the rule you can now validate your business logic like this:
$payload = [
'date' => now(),
];
$rule = Rule::single(SampleRule::class, ['until' => Carbon::make('01-02-2024')])
$result = Foliage::validateSilently($rule->node(), $payload);
$result->isValid();
$result->errors();
composer test
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.