Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add validation documentation #132

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/.vuepress/config/locales/en/sidebar.js
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ module.exports = {
'search',
'settings',
'testing',
'validation',
]
},
// {
Expand Down
179 changes: 179 additions & 0 deletions docs/extend/validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
# Validation

When users create or update data, you'll want to make sure it is valid; for instance, emails should follow a certain format, passwords have a minimum length, and the title field of discussions must be provided when starting a discussion.

Flarum's validation system is just a wrapper around [Laravel Validation](https://laravel.com/docs/6.x/validation#manually-creating-validators). We recommend familiarizing yourself with the basics of that before proceeding.

## Using a Validator

Using a Flarum validator is very simple: all you need to do is inject an instance of the validator you need, and use its `assertValid` method on the data you are validating.

Please note that the data you pass into a validator should be an associative array of keys to values, not an Eloquent model instance. For example:

```php
use Flarum\Group\GroupValidator;


class SomeClass
{
protected $validator;
public function __construct(GroupValidator $validator) {
$this->validator = $validator;
}

public function someMethod() {
$this->validator->assertValid($group->getDirty());
}
}
```

If it fails validation, a `Illuminate\Validation\ValidationException` will be thrown with the validation errors, so that Flarum's error handling system can optimally present them to the user.

Remember that you can turn an Eloquent instance into an associative array of attributes via:

- The `$instance->getAttributes()` method if the instance hasn't been saved.
- The `$instance->getDirty()` method if the instance has been saved.
askvortsov1 marked this conversation as resolved.
Show resolved Hide resolved

We can also create a Laravel validator instance directly by injecting a `Illuminate\Contracts\Validation\Factory` instance. For example:

```php
use Illuminate\Contracts\Validation\Factory;
use Illuminate\Validation\ValidationException;


class SomeClass
{
protected $validatorFactory;
public function __construct(Factory $validatorFactory) {
$this->validatorFactory = $validatorFactory;
}

public function someMethod() {
$validator = $this->validatorFactory->make($input, ['password' => 'required|confirmed']);

if ($validator->fails()) {
throw new ValidationException($validator);
}
}
}
```

## Custom Validators

To create a custom Flarum validator, just make a class extending `Flarum\Foundation\AbstractValidator`. You'll typically want to implement 2 methods:

- `getRules()`, which returns an associative array of [Laravel validation rules](https://laravel.com/docs/6.x/validation#available-validation-rules).
- `getMessages()`, which returns an associative array of custom error messages for when particular attributes fail particular tests. Remember to use [translation](i18n.md): all validators have access to a `Symfony\Component\Translation\TranslatorInterface` instance via `$this->translator`.

Let's take a look at Flarum's `Flarum\User\UserValidator` as an example:

```php
<?php

namespace Flarum\User;

use Flarum\Foundation\AbstractValidator;

class UserValidator extends AbstractValidator
{
protected $user;

public function getUser()
{
return $this->user;
}

public function setUser(User $user)
{
$this->user = $user;
}

/**
* {@inheritdoc}
*/
protected function getRules()
{
$idSuffix = $this->user ? ','.$this->user->id : '';

return [
'username' => [
'required',
'regex:/^[a-z0-9_-]+$/i',
'unique:users,username'.$idSuffix,
'min:3',
'max:30'
],
'email' => [
'required',
'email:filter',
'unique:users,email'.$idSuffix
],
'password' => [
'required',
'min:8'
]
];
}

/**
* {@inheritdoc}
*/
protected function getMessages()
{
return [
'username.regex' => $this->translator->trans('core.api.invalid_username_message')
];
}
}
```

## Extending Validators

Your extension might want to modify a validator defined in core or another extension. You can do this by listening to the `Flarum\Foundation\Event\Validating` event, which allows extensions to mutate the underlying Laravel validator instance before validation runs. You can use this to change validation rules, messages, or even more advanced features like validator extensions and replacers.

For example:

```php
// extend.php
<?php

use Flarum\Extend;
use Flarum\Foundation\Event\Validating;
use Flarum\User\UserValidator;
use Illuminate\Support\Str;

return [
// Register extenders here
(new Extend\Event)->listen(Validating::class, function(Dispatcher $events) {
$events->listen(Validating::class, function(Validating $event) {
// This modification should only apply to UserValidator
askvortsov1 marked this conversation as resolved.
Show resolved Hide resolved
if ($event->type instanceof UserValidator) {
$rules = $event->validator->getRules();

// In this case, we are tweaking validation logic for the username attribute,
// so if that key isn't present in rules, there's nothing we need to do.
if (!array_key_exists('username', $rules)) {
return;
}

// Tweak username validation with a custom regex,
// and increase min length to 10 characters.
$rules['username'] = array_map(function(string $rule) {
if (Str::startsWith($rule, 'regex:')) {
return 'regex:/^[.a-z0-9_-]+$/i';
}

if (Str::startsWith($rule, 'min:')) {
return 'min:10';
}

return $rule;
}, $rules['username']);

// Update the validator instance with modified rules.
$event->validator->setRules($rules);
}
});
}),
];
```