Table of Contents
- Overview
- Installation
- Usage
- Security
- Contribution
- Changelog
- Upgrading
- License
Overview
A Laravel package that allows you to validate your config values and environment.
Installation
Requirements
The package has been developed and tested to work with the following minimum requirements:
- PHP 8.0
- Laravel 8
Install the Package
You can install the package via Composer:
composer require ashallendesign/laravel-config-validatorPublishing the Default Rulesets
To get you started with validating your app's config, Laravel Config Validator comes with some default rulesets. To start using these rulesets, you can publish them using the following command:
php artisan vendor:publish --tag=config-validator-defaultsThe above command will copy the validation files and place in a config-validation folder in your project's root. These rules
are just to get you started, so there are likely going to be rule in the files that don't apply to your app. So, once you've
published them, feel free to delete them or edit them as much as you'd like.
Usage
Creating a Validation Ruleset
Using the Generator Command
This package comes with a command that you can use to quickly create a validation file to get you started right away.
Lets say that you wanted to create a validation file for validating the config in the config/app.php file. To do
this, you could use the following command:
php artisan make:config-validation appRunning the above command would create a file in config-validation/app.php ready for you to start adding your config
validation.
Ruleset Location
To validate your application's config, you need to define the validation rules first. You can do this by placing them inside
files in a config-validation folder with names that match the config file you're validating. As an example, to
validate the config/app.php config file, you would create a new file at config-validation/app.php that
would hold the rules.
Adding Rules to a Ruleset
Once you have your ruleset file created in the config-validation folder, you can start adding your validation
rules.
Under the hood, Laravel Config Validator uses the built-in Validator class, so it should seem pretty familiar
to work with. To check out the available Laravel validation rules that can be used, click here.
As an example, we might want to add a config validation rule to ensure that the driver field in the app/mail.php
file is a supported field. To do this, we could create a file at config-validation/mail.php with the following:
<?php
use AshAllenDesign\ConfigValidator\Services\Rule;
return [
Rule::make('driver')->rules(['in:smtp,sendmail,mailgun,ses,postmark,log,array']),
// ...
];Custom Validation Error Messages
There may be times when you want to override the error message for a specific validation rule. This can be done by passing
in an array containing the messages to the ->messages() method for a Rule. This array should follow the same
pattern that would be used in a standard Laravel Validator object.
As an example, we might want to add a config validation rule to ensure that the driver field in the app/mail.php
file is a supported field and also use a custom error message. To do this, we could update our validation file to the following:
<?php
use AshAllenDesign\ConfigValidator\Services\Rule;
return [
Rule::make('driver')
->rules(['in:smtp,sendmail,mailgun,ses,postmark,log,array'])
->messages(['in' => 'The mail driver is invalid']),
// ...
];Only Running in Specific App Environments
You might not always want the same rule to be run in different environments. For example, you might want to have a relaxed set of validation rules for your local development environment and have a stricter set of rules for production.
To explicitly specify the environment that a rule can be run in, you can use the ->environments() method. If no
environment is defined, the rule will be run in all environments.
The following example shows how you could set 2 different rules, one for production and one for local:
<?php
use AshAllenDesign\ConfigValidator\Services\Rule;
return [
Rule::make('driver')
->rules(['in:smtp,sendmail,mailgun,ses,postmark,log,array'])
->environments([Rule::ENV_LOCAL]),
Rule::make('driver')
->rules(['in:mailgun'])
->environments([Rule::ENV_PRODUCTION])
];Running the Validation
Running the Validation Manually
To run the config validation you can call the ->run() method on a ConfigValidator object. The example below
shows how you could do this in a controller:
<?php
namespace App\Http\Controllers;
use AshAllenDesign\ConfigValidator\Services\ConfigValidator;
class TestController extends Controller
{
public function index()
{
$configValidator = new ConfigValidator();
$configValidator->run();
return response()->json(['success' => true]);
}
}Only Running on Selected Config Files
You might not always want to validate all of the config values in your application. So, you can specify the config files
that you want to validate by passing the config names to the ->run() method as the first parameter. As an example, if you only wanted to validate
the auth.php config file, you could use the following:
$configValidator = new ConfigValidator();
$configValidator->run(['auth']);Custom Folder Path
If you aren't storing your validation files in the default config/validation folder, you can pass a custom folder path
into the ->run() method as the second parameter. As an example, if you had the files stored in a app/Custom/Validation folder, you
could use the following:
$configValidator = new ConfigValidator();
$configValidator->run([], 'app/Custom/Validation');Using the Command
The library comes with a useful command that you can use to validate your config. To use it, you can run the following in the command line:
php artisan config:validateOnly Running on Selected Config Files (Command)
You might not always want to validate all of the config values in your application. So, you can specify the config files
that you want to validate in the command using the --files option. As an example, if you only wanted to validate
the auth.php config file, you could use the following:
php artisan config:validate --files=authAs a further example, if you wanted to validate the auth.php and app.php files, you could use the following:
php artisan config:validate --files=auth,appCustom Folder Path (Command)
If you aren't storing your validation files in the default config/validation folder, you can pass a custom folder path
into the --path option. As an example, if you had the files stored in a app/Custom/Validation folder, you
could use the following:
php artisan config:validate --path=app/Custom/ValidationUsing a Service Provider
You might want to run the config validator automatically on each request to ensure that you have the correct config. This
can be particularly useful if you are in a local environment and switching between Git branches often. However, you might
not want it to always run automatically in production for performance reasons. To run the validation automatically on each
request, you can add it to the boot method of a service provider.
The example below shows how to only run the validation in the local environment using the AppServiceProvider:
<?php
namespace App\Providers;
use AshAllenDesign\ConfigValidator\Services\ConfigValidator;
use Illuminate\Support\Facades\App;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
public function boot(ConfigValidator $configValidator)
{
if (App::environment() === 'local') {
$configValidator->run();
}
}
}Throwing and Preventing Exceptions
By default, the ConfigValidator will throw an InvalidConfigValueException exception if the validation fails. The exception will contain
the error message of the first config value that failed the validation. You can prevent the exception from being thrown and instead
rely on the boolean return value of the ->run() method by using the ->throwExceptionOnFailure() method.
By preventing any exceptions from being thrown, it makes it easier for you to get all the failed validation errors using the
->errors() method. This will return the errors as an array.
The example belows shows how you could prevent any exceptions from being thrown so that you can grab the errors:
$configValidator = new ConfigValidator();
$configValidator->throwExceptionOnFailure(false)
->run();
$errors = $configValidator->errors();Facade
If you prefer to use facades in Laravel, you can choose to use the provided ConfigValidator facade instead of instantiating the AshAllenDesign\ConfigValidator\Classes\ConfigValidator
class manually.
The example below shows an example of how you could use the facade to run the config validation:
<?php
namespace App\Http\Controllers;
use ConfigValidator;
class TestController extends Controller
{
public function index()
{
ConfigValidator::run();
return response()->json(['success' => true]);
}
}Security
If you find any security related issues, please contact me directly at [email protected] to report it.
Contribution
If you wish to make any changes or improvements to the package, feel free to make a pull request.
Note: A contribution guide will be added soon.
Changelog
Check the CHANGELOG to get more information about the latest changes.
Upgrading
Check the UPGRADE guide to get more information on how to update this library to newer versions.
License
The MIT License (MIT). Please see License File for more information.
Support Me
If you've found this package useful, please consider buying a copy of Battle Ready Laravel to support me and my work.
Every sale makes a huge difference to me and allows me to spend more time working on open-source projects and tutorials.
To say a huge thanks, you can use the code BATTLE20 to get a 20% discount on the book.
