ashallendesign / laravel-config-validator
A package for validating your Laravel app's config.
Fund package maintenance!
ash-jc-allen
Installs: 146 488
Dependents: 2
Suggesters: 0
Security: 0
Stars: 200
Watchers: 3
Forks: 11
Open Issues: 1
Requires
- php: ^8.0
- ext-json: *
- illuminate/console: ^8.0|^9.0|^10.0|^11.0
- illuminate/container: ^8.0|^9.0|^10.0|^11.0
- illuminate/validation: ^8.0|^9.0|^10.0|^11.0
- illuminate/view: ^8.0|^9.0|^10.0|^11.0
- nunomaduro/termwind: ^1.6|^2.0
Requires (Dev)
- mockery/mockery: ^1.0
- nunomaduro/larastan: ^1.0.0||^2.0.0
- orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
- phpunit/phpunit: ^9.0|^10.5
README
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-validator
Publishing 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-defaults
The 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 app
Running 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');
Running the Validator with Inline Rules
There may be times when you want to run the validator with inline rules instead of using the rules defined in your config validation files. This can be useful if you want to run a one-off validation check, or validate the config values inside a package you maintain.
To do this, you can use the runInline
method like so:
use AshAllenDesign\ConfigValidator\Services\ConfigValidator; use AshAllenDesign\ConfigValidator\Services\Rule; $configValidator = new ConfigValidator(); $configValidator->runInline([ 'app' => [ Rule::make('env')->rules(['in:local,production']), Rule::make('debug')->rules(['boolean']), ], 'mail' => [ Rule::make('driver')->rules(['in:smtp,sendmail,mailgun,ses,postmark,log,array']), ], ]);
In the example above, we're running the validator with inline rules for the app
and mail
config files. The rules are the same as the ones we would define in the config validation files.
The behaviour of the runInline
method is the same as the run
method. It will throw an exception if the validation fails, or return a boolean value if the throwExceptionOnFailure
method has been set to false
.
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:validate
Only 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=auth
As 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,app
Custom 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/Validation
Using 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 mail@ashallendesign.co.uk 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.