@orieljs/framework 0.1.0-alpha.6 → 0.1.0-alpha.7

package/docs/validation.md

@@ -0,0 +1,1792 @@
+# Validation
+
+Oriel checks the data your app receives with Laravel's validation rules, and types the validated data from the rules
+you write.
+
+## Introduction
+
+Oriel validates in three ways: `request().validate()` in a route or a controller, form request classes, and
+validators you make yourself with `Validator.make()`. Each takes the same rules, with Laravel's names, such as
+`required|email|max:255`, and fails with Laravel's messages. When validation fails, the user goes back to the form
+with the errors, or an API client receives them as JSON.
+
+## Validation quickstart
+
+Here is a complete example: a form that creates a blog post, validated, with its errors shown to the user.
+
+### Defining the routes
+
+Two routes in `routes/web.ts`: a `GET` route shows the form, and a `POST` route stores the post:
+
+```ts title="routes/web.ts"
+// @filename: app/Http/Controllers/PostController.ts
+export declare class PostController {
+  create(): unknown
+  store(): Promise<unknown>
+}
+// ---cut---
+import { Route } from '@orieljs/framework'
+import { PostController } from '../app/Http/Controllers/PostController'
+
+Route.get('/post/create', [PostController, 'create'])
+Route.post('/post', [PostController, 'store'])
+```
+
+### Creating the controller
+
+The controller shows the form and stores the post. `store()` is empty for now:
+
+```ts title="app/Http/Controllers/PostController.ts"
+import { redirect, view } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class PostController extends Controller {
+  /** Show the form to create a new blog post. */
+  create() {
+    return view('post.create')
+  }
+
+  /** Store a new blog post. */
+  async store() {
+    // Validate and store the blog post...
+
+    return redirect('/posts')
+  }
+}
+```
+
+### Writing the validation logic
+
+`request().validate()` takes the rules for each field. When the input passes, it returns the validated data and your
+code goes on. When it fails, it throws, and Oriel sends the response:
+
+- to a browser's form, a redirect back to the previous page, with the errors and the input flashed to the session;
+- to a request that expects JSON, a 422 response with the errors (see the
+  [error response format](#validation-error-response-format)).
+
+```ts title="app/Http/Controllers/PostController.ts"
+import { redirect, request } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class PostController extends Controller {
+  /** Store a new blog post. */
+  async store() {
+    const validated = await request().validate({
+      title: 'required|unique:posts|max:255',
+      body: 'required',
+    })
+
+    // The blog post is valid...
+
+    return redirect('/posts')
+  }
+}
+```
+
+The rules are a string with `|` between them, or a list. A list can also hold [rule objects](#rule-objects):
+
+```ts
+const validated = await request().validate({
+  title: ['required', 'unique:posts', 'max:255'],
+  body: ['required'],
+})
+```
+
+The validated data is typed from the rules. Here `title` and `body` are always there but `unknown`, since no rule
+says what they are; with `string` among their rules, both are typed `string`. [Working with validated
+input](#working-with-validated-input) covers the types.
+
+A rule name Oriel doesn't know, such as a misspelt one, is an error when it runs on a field the request sends, and the
+request ends with a 500:
+`Validation rule "requird" is not registered. Register it with ValidationFactory.extend() first.` On a field the request
+leaves out or sends blank, the rule doesn't run: a misspelt `required` lets a missing field through.
+
+#### Stopping on first validation failure
+
+`bail` stops a field's rules at its first failure. Without it, every rule of the field runs and each failure adds a
+message:
+
+```ts
+const validated = await request().validate({
+  title: 'bail|required|unique:posts|max:255',
+  body: 'required',
+})
+```
+
+Here a failing `unique` skips `max`. Rules run in the order you write them. A failing `required`, or another rule
+that runs on a missing field, always stops its field.
+
+#### A note on nested attributes
+
+Fields the request sends nested, as JSON or as `author[name]` in a form, are named with dots:
+
+```ts
+const validated = await request().validate({
+  title: 'required|unique:posts|max:255',
+  'author.name': 'required',
+  'author.description': 'required',
+})
+```
+
+Laravel escapes a dot that belongs to a field's name with a backslash, as `v1\.0`; Oriel has no such escape.
+
+### Displaying the validation errors
+
+When validation fails, the user is sent back to the form, with the errors and the input flashed to the session.
+`errors()` reads the errors in your views:
+
+```tsx title="resources/views/post/create.tsx"
+import { errors } from '@orieljs/framework'
+
+export default function Create() {
+  const messages = errors()
+
+  return (
+    <main>
+      <h1>Create Post</h1>
+
+      {!messages.isEmpty() && (
+        <div class="alert alert-danger">
+          <ul>
+            {messages.all().map((message) => (
+              <li>{message}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Create Post Form */}
+    </main>
+  )
+}
+```
+
+`errors()` returns an empty bag when there are no errors, so a view can call it at any time.
+
+#### Customizing the error messages
+
+Each rule has Laravel's English message, such as "The title field is required.". Give your own to a
+[form request](#customizing-the-error-messages-1) or to a [validator](#customizing-the-error-messages-2).
+
+#### XHR requests and validation
+
+A request that expects JSON, as a script's `fetch()` with `Accept: application/json` does, gets no redirect: a
+failed validation answers with a 422 and the errors as JSON. [Error handling](errors.md) covers how Oriel tells the
+two kinds of request apart.
+
+#### Showing a field's errors
+
+`errors().first('title')` returns a field's first message, or `undefined`, so a field can show its own error:
+
+```tsx title="resources/views/post/create.tsx"
+import { errors } from '@orieljs/framework'
+
+export default function Create() {
+  const error = errors().first('title')
+
+  return (
+    <form method="post" action="/post">
+      <label for="title">Post Title</label>
+      <input id="title" type="text" name="title" class={{ 'is-invalid': error !== undefined }} />
+
+      {error && <div class="alert alert-danger">{error}</div>}
+    </form>
+  )
+}
+```
+
+With [named error bags](#named-error-bags), `errors('post').first('title')` reads the `post` bag.
+
+### Repopulating forms
+
+The input of a failed validation is flashed with the errors, except the `password`, `password_confirmation` and
+`current_password` fields. `old()` reads it on the next request, so a form shows what the user typed:
+
+```tsx
+const input = <input type="text" name="title" value={old('title', '')} />
+```
+
+Without old input for the field, `old()` returns the default you give it. [Requests](requests.md#old-input) has
+more on old input.
+
+### A note on optional fields
+
+The `TrimStrings` and `ConvertEmptyStringsToNull` middleware tidy every request's input, so a field left empty
+arrives as `null`. Mark an optional field `nullable`, so `null` passes its other rules:
+
+```ts
+const validated = await request().validate({
+  title: 'required|unique:posts|max:255',
+  body: 'required',
+  publish_at: 'nullable|date',
+})
+```
+
+Without `nullable`, `null` fails the `date` rule.
+
+### Validation error response format
+
+A failed validation answers a request that expects JSON with a 422, a `message` (the first error, and how many more
+there are) and `errors`, by field. Nested fields are named with dots:
+
+```json
+{
+  "message": "The team name field must be a string. (and 4 more errors)",
+  "errors": {
+    "team_name": ["The team name field must be a string.", "The team name field must be at least 1 characters."],
+    "authorization.role": ["The selected authorization.role is invalid."],
+    "users.0.email": ["The users.0.email field is required."],
+    "users.2.email": ["The users.2.email field must be a valid email address."]
+  }
+}
+```
+
+### Displaying errors in Inertia pages
+
+In the Inertia starter kits, a failed validation sends the user back to the page, and the errors reach it as the
+`errors` prop: one message per field. Each adapter's `useForm()` holds them in `errors`:
+
+```tsx tab="React" title="resources/js/pages/Auth/ForgotPassword.tsx"
+import { route, useForm } from '@orieljs/inertia-react'
+import type { FormEvent } from 'react'
+
+export default function ForgotPassword() {
+  const { data, setData, post, processing, errors } = useForm<{ email: string }>({
+    email: '',
+  })
+
+  const submit = (event: FormEvent) => {
+    event.preventDefault()
+    post(route('password.email'))
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <input type="email" value={data.email} onChange={(event) => setData('email', event.target.value)} />
+      {errors.email && <p className="error">{errors.email}</p>}
+
+      <button type="submit" disabled={processing}>
+        Email password reset link
+      </button>
+    </form>
+  )
+}
+```
+```vue tab="Vue" title="resources/js/pages/Auth/ForgotPassword.vue"
+<script setup lang="ts">
+import { route, useForm } from '@orieljs/inertia-vue'
+
+const form = useForm({
+  email: '',
+})
+
+const submit = () => {
+  form.post(route('password.email'))
+}
+</script>
+
+<template>
+  <form @submit.prevent="submit">
+    <input v-model="form.email" type="email" />
+    <p v-if="form.errors.email" class="error">{{ form.errors.email }}</p>
+
+    <button type="submit" :disabled="form.processing">Email password reset link</button>
+  </form>
+</template>
+```
+```svelte tab="Svelte" title="resources/js/pages/Auth/ForgotPassword.svelte"
+<script lang="ts">
+  import { route, useForm } from '@orieljs/inertia-svelte'
+
+  const form = useForm({
+    email: '',
+  })
+
+  function submit(event: SubmitEvent) {
+    event.preventDefault()
+    form.post(route('password.email'))
+  }
+</script>
+
+<form onsubmit={submit}>
+  <input type="email" bind:value={form.email} />
+  {#if form.errors.email}
+    <p class="error">{form.errors.email}</p>
+  {/if}
+
+  <button type="submit" disabled={form.processing}>Email password reset link</button>
+</form>
+```
+```tsx tab="Solid" title="resources/js/pages/Auth/ForgotPassword.tsx"
+import { route, useForm } from '@orieljs/inertia-solid'
+import { Show } from 'solid-js'
+
+export default function ForgotPassword() {
+  const form = useForm<{ email: string }>({
+    email: '',
+  })
+
+  const submit = (event: SubmitEvent) => {
+    event.preventDefault()
+    form.post(route('password.email'))
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <input type="email" value={form.data.email} onInput={(event) => form.setData('email', event.currentTarget.value)} />
+      <Show when={form.errors.email}>
+        <p class="error">{form.errors.email}</p>
+      </Show>
+
+      <button type="submit" disabled={form.processing}>
+        Email password reset link
+      </button>
+    </form>
+  )
+}
+```
+```ts tab="Angular" title="resources/js/pages/Auth/ForgotPassword.component.ts"
+import { Component } from '@angular/core'
+import { route, useForm } from '@orieljs/inertia-angular'
+
+@Component({
+  selector: 'forgot-password-page',
+  template: `
+    <form (submit)="submit($event)">
+      <input #emailInput type="email" [value]="form.data.email" (input)="form.setData('email', emailInput.value)" />
+      @if (form.errors.email) {
+        <p class="error">{{ form.errors.email }}</p>
+      }
+
+      <button type="submit" [disabled]="form.processing">Email password reset link</button>
+    </form>
+  `,
+})
+export default class ForgotPassword {
+  protected readonly form = useForm<{ email: string }>({ email: '' })
+
+  protected submit(event: SubmitEvent): void {
+    event.preventDefault()
+    this.form.post(route('password.email'))
+  }
+}
+```
+
+[Inertia](inertia.md#forms) covers forms in more depth.
+
+#### Precognition
+
+A route with the `precognitive` middleware can validate a form while the user fills it in: the React, Vue and
+Svelte forms send a precognitive request, which runs the action up to its first validation and answers with the
+errors, or a 204 when the data passes. [Precognitive requests](middleware.md#precognitive-requests) describes the
+requests. The Solid and Angular forms don't offer Precognition yet.
+
+> [!WARNING]
+> Validate first. Laravel validates a form request before it calls the action; Oriel validates when the action calls
+> `validate()`, so on a precognitive request, what the action does before its validation runs too. On a route with
+> the `precognitive` middleware, put the validation at the top of the action.
+
+### Displaying errors in Live components
+
+A Live component validates its own properties with `this.validate()`. A failed validation stops the action, and the
+component renders again with its errors in `this.errors`:
+
+```tsx title="app/Live/CreatePost.tsx"
+import { Component, request, Str } from '@orieljs/framework'
+import type { User } from '../Models/User'
+
+export default class CreatePost extends Component {
+  title = ''
+
+  async save(): Promise<void> {
+    const data = await this.validate({ title: 'required|string|max:255' })
+
+    const user = (await request().user<User>())!
+
+    await user.posts().create({ title: data.title, slug: Str.slug(data.title), body: '' })
+  }
+
+  render() {
+    return (
+      <form o:submit="save">
+        <input type="text" o:model="title" />
+        {this.errors.has('title') && <p class="error">{this.errors.first('title')}</p>}
+
+        <button type="submit">Save</button>
+      </form>
+    )
+  }
+}
+```
+
+`await request().user()` returns the signed-in user, or `undefined` for a guest. The page's route has the `auth`
+middleware, which each update runs again, so here there is always one. [Live](live.md#validation) covers validation in
+components.
+
+## Form request validation
+
+### Creating form requests
+
+A form request is a class that holds the rules of one form, and the check that the user may send it. `make:request`
+writes one in `app/Http/Requests`:
+
+```sh
+node oriel make:request StorePostRequest
+```
+
+The class it writes has two methods: `authorize()`, which decides whether the signed-in user may make the request,
+and `rules()`, which returns the rules:
+
+```ts title="app/Http/Requests/StorePostRequest.ts"
+import { FormRequest } from '@orieljs/framework'
+
+export class StorePostRequest extends FormRequest {
+  override authorize(): boolean {
+    return true
+  }
+
+  /** Get the validation rules that apply to the request. */
+  rules() {
+    return {
+      title: 'required|string|unique:posts|max:255',
+      body: 'required|string',
+    } as const
+  }
+}
+```
+
+The action validates the request by calling the class's `validate()`, which returns the validated data:
+
+```ts title="app/Http/Controllers/PostController.ts"
+// @filename: app/Http/Requests/StorePostRequest.ts
+import { FormRequest } from '@orieljs/framework'
+export class StorePostRequest extends FormRequest {
+  rules() {
+    return { title: 'required|string|unique:posts|max:255', body: 'required|string' } as const
+  }
+}
+// ---cut---
+import { redirect, request, Str } from '@orieljs/framework'
+import type { User } from '../../Models/User'
+import { StorePostRequest } from '../Requests/StorePostRequest'
+import { Controller } from './Controller'
+
+export class PostController extends Controller {
+  /** Store a new blog post. */
+  async store() {
+    const validated = await StorePostRequest.validate()
+
+    const user = (await request().user<User>())!
+    const post = await user.posts().create({ ...validated, slug: Str.slug(validated.title) })
+
+    return redirect().route('posts.show', post)
+  }
+}
+```
+
+The route to `store()` has the `auth` middleware, so `await request().user()` is the signed-in user. A failure is
+answered as `request().validate()`'s is: a redirect back with the errors, or a 422 with the errors as JSON.
+
+> [!NOTE]
+> Laravel validates a form request before the action runs, when the action type-hints it. TypeScript types are gone
+> when your app runs, so Oriel can't see the hint: the action calls `StorePostRequest.validate()` itself, which is
+> also why a [precognitive](#precognition) action validates first.
+
+> [!WARNING]
+> Write `rules()` without a return type and with `as const`. `as const` keeps each rule string's text, which types the
+> validated data: without it, every field is optional and `unknown`. A return type of `Rules` makes the data
+> `Record<string, unknown>`.
+
+```ts
+class WithoutAsConstRequest extends FormRequest {
+  rules() {
+    return { title: 'required|string' }
+  }
+}
+
+const data = await WithoutAsConstRequest.validate()
+
+// @ts-expect-error: without as const, title is unknown and may be missing
+const title: string = data.title
+```
+
+`request().validate()` needs neither: it reads the rules' text from the call.
+
+### Authorizing form requests
+
+`authorize()` decides whether the user may make the request. It may be async, as checking a policy is. When it returns
+`false`, `validate()` throws before validating, and the request ends with a 403, "This action is unauthorized.":
+
+```ts title="app/Http/Requests/UpdatePostRequest.ts"
+import { Auth, FormRequest, request } from '@orieljs/framework'
+import type { Post } from '../../Models/Post'
+import type { User } from '../../Models/User'
+
+export class UpdatePostRequest extends FormRequest {
+  override async authorize(): Promise<boolean> {
+    const post = request().route<Post>('post')
+    const user = await Auth.user<User>()
+
+    return user !== undefined && (await user.can('update', post))
+  }
+
+  rules() {
+    return { title: 'required|string|max:255' } as const
+  }
+}
+```
+
+`request().route('post')` returns the route's `post` parameter, after [model binding](routing.md#route-model-binding),
+and `Auth.user()` the signed-in user, or `undefined` for a guest. Without an `authorize()`, every request may proceed.
+Gates and policies are covered on the [Authorization](authorization.md#via-form-requests) page.
+
+### Customizing the error messages
+
+`messages()` returns messages for a field's rule, and `attributes()` the names that replace `:attribute` in them:
+
+```ts title="app/Http/Requests/StorePostRequest.ts"
+import { FormRequest } from '@orieljs/framework'
+
+export class StorePostRequest extends FormRequest {
+  rules() {
+    return {
+      title: 'required|string|max:255',
+      body: 'required|string',
+    } as const
+  }
+
+  override messages(): Record<string, string> {
+    return {
+      'title.required': 'A title is required',
+      'body.required': 'A message is required',
+    }
+  }
+
+  override attributes(): Record<string, string> {
+    return {
+      body: 'post body',
+    }
+  }
+}
+```
+
+Laravel's form requests also have `after()`, `stopOnFirstFailure`, `$redirect`, `prepareForValidation()` and
+`passedValidation()`, which Oriel's don't. Change the input before you validate with `request().merge()`, and check
+more with a [validator of your own](#performing-additional-validation).
+
+## Manually creating validators
+
+The `Validator` [facade](facades.md) makes a validator from any data and rules, when you want to decide what a failure
+does:
+
+```ts title="app/Http/Controllers/PostController.ts"
+import { redirect, request, Validator } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class PostController extends Controller {
+  /** Store a new blog post. */
+  async store() {
+    const validator = Validator.make(request().all(), {
+      title: 'required|unique:posts|max:255',
+      body: 'required',
+    })
+
+    if (await validator.fails()) {
+      return redirect('/post/create').withErrors(validator.errors()).withInput()
+    }
+
+    // Retrieve the validated input...
+    const validated = await validator.validated()
+
+    // Store the blog post...
+
+    return redirect('/posts')
+  }
+}
+```
+
+`make()` takes the data to validate, the rules, and then custom messages and attribute names. `passes()` and
+`fails()` run the rules once, and `errors()` returns the messages afterwards. `validated()` returns the data that has
+rules, and throws when it fails. Its data is typed from the rules, as `request().validate()`'s is.
+
+> [!NOTE]
+> Laravel's `passes()`, `fails()` and `validated()` return their answer. Oriel's return promises, to await: some rules
+> wait for a database query (`unique`, `exists`), a file's bytes (`image`, `mimes`) or the network (`active_url`),
+> and a Node process can't block on them.
+
+### Automatic redirection
+
+A failing `validated()` throws the same error as `request().validate()`, so the redirect back, or the 422, is sent
+for you:
+
+```ts
+const validated = await Validator.make(request().all(), {
+  title: 'required|unique:posts|max:255',
+  body: 'required',
+}).validated()
+```
+
+### Named error bags
+
+A page with several forms keeps each form's errors apart in a named error bag. `withErrors()` takes the bag's name
+as its second argument:
+
+```ts
+declare const validator: import('@orieljs/framework/contracts').Validator
+// ---cut---
+const res = redirect('/register').withErrors(validator.errors(), 'login')
+```
+
+The view reads it with `errors('login')`:
+
+```tsx
+const message = <p>{errors('login').first('email')}</p>
+```
+
+To send a failure to a named bag from anywhere, throw a `ValidationException` with the bag's name; a third argument
+redirects somewhere other than back:
+
+```ts
+throw new ValidationException({ email: ['These credentials do not match our records.'] }, 'login')
+```
+
+`ValidationException.withMessages({ email: 'These credentials do not match our records.' })` fails the request
+with your own messages, in the default bag, as the starter kits' login does. Laravel's `validateWithBag()` isn't in
+Oriel.
+
+### Customizing the error messages
+
+The third argument of `make()` replaces the messages of rules. `:attribute` is the field's name:
+
+```ts
+declare const input: Record<string, unknown>
+declare const rules: Rules
+// ---cut---
+const validator = Validator.make(input, rules, {
+  required: 'The :attribute field is required.',
+})
+```
+
+A message can use the placeholders its rule fills: `:other` for the field `same` compares with, `:size`, `:min`,
+`:max`, `:values` and so on, as Laravel's messages do.
+
+#### Specifying a custom message for a given attribute
+
+Name the field, then the rule, to change one field's message. A wildcard names every item of a list:
+
+```ts
+const messages = {
+  'email.required': 'We need to know your email address!',
+  'users.*.email.unique': 'Each user must have a unique email address',
+}
+```
+
+#### Specifying custom attribute values
+
+The fourth argument names fields in the messages, in place of their key:
+
+```ts
+declare const input: Record<string, unknown>
+declare const rules: Rules
+declare const messages: Record<string, string>
+// ---cut---
+const validator = Validator.make(input, rules, messages, {
+  email: 'email address',
+})
+```
+
+Without one, a key is written in words: `first_name` is "first name", `productName` "product name", and
+`users.0.email` stays as it is.
+
+### Performing additional validation
+
+`after()` runs a function once the rules have run, to check more. The function receives the validator, whose
+`fail()` adds a message:
+
+```ts
+declare const somethingElseIsInvalid: () => boolean
+// ---cut---
+const validator = Validator.make(request().all(), { title: 'required' })
+
+validator.after((v) => {
+  if (somethingElseIsInvalid()) {
+    v.fail('field', 'Something is wrong with this field!')
+  }
+})
+
+if (await validator.fails()) {
+  // ...
+}
+```
+
+The function may be async, and runs whether the rules passed or not. Each call to `after()` adds a function and
+returns the validator, so the calls chain.
+
+## Working with validated input
+
+`validate()` and `validated()` return only the fields that have rules, nested as the request sent them: a key without
+rules is left out, and so is a key the request didn't send.
+
+```ts
+const validated = await request().validate({ name: 'required|string', email: 'required|email' })
+
+const { name, email } = validated
+```
+
+The data is a plain object. Laravel's `safe()`, with `only()`, `except()` and `merge()`, isn't in Oriel: pick the
+keys you want from the object.
+
+### The validated data's type
+
+Each field's type comes from its rules. The type rules decide what a value is, and the presence rules whether the key
+is there:
+
+```ts
+const data = await request().validate({
+  title: 'required|string|max:255',
+  votes: 'nullable|integer',
+  status: 'required|in:draft,published',
+  tags: 'array|in:php,laravel',
+  'author.name': 'required|string',
+})
+
+const title: string = data.title
+const votes: NumericValue | null | undefined = data.votes
+const status: 'draft' | 'published' = data.status
+const tags: Array<'php' | 'laravel'> | undefined = data.tags
+const author: string = data.author.name
+```
+
+- `string`, `email`, `url`, `date` and the other text rules make a `string`; `file` and `image` an `UploadedFile`.
+- `required`, `accepted` and `declined` put the key in the data and rule out `null`; `present` puts the key in.
+  Without one of them, the key is optional.
+- `nullable` adds `null`, unless one of those rules, or `filled`, rules it out.
+- `in:a,b` lets the listed values through, and with `array` makes a list of them.
+- `array` is a list, `unknown[]`, and `array:name,email` an object with those optional keys.
+- Dotted keys nest: `author.name` is `{ author: { name } }`.
+- Rules that only check a value, such as `max`, `confirmed` or `unique`, change nothing, and a field without a type
+  rule is `unknown`.
+
+> [!NOTE]
+> Laravel returns the input as the request sent it, and so does Oriel: nothing is cast. A form sends text, so a
+> field that passes `integer` is `5` from JSON and `'5'` from a form, and is typed `` number | `${number}` ``, which
+> `NumericValue` names. Convert it where you need a number, with `Number(data.votes)`. In the same way `boolean` is
+> `boolean | 0 | 1 | '0' | '1'`. The types say what passed, so they never promise a number a form didn't send.
+
+A few rules make a key optional, or keep it from being typed as a list:
+
+- `sometimes` skips a missing field, and `exclude_if`, `exclude_unless`, `exclude_with` and `exclude_without` can take
+  a field out: with any of them the key is optional, even with `required`.
+- `prohibited` passes a missing or empty field, so its value is typed `null | string | [] | Record<string, never>`.
+- A `*` level whose parent has no `array` or `list` rule is typed `V[] | Record<string, V>`: the request may send an
+  object there, and a sparse match keeps its indexes as keys. Give the parent `array` to make it a list:
+
+```ts
+const data = await request().validate({
+  items: 'required|array',
+  'items.*.qty': 'required|integer',
+})
+
+const quantities: NumericValue[] = data.items.map((item) => item.qty)
+```
+
+Rule strings TypeScript only knows as `string`, such as a form request's `rules()` without `as const`, give
+optional `unknown` fields.
+
+## Working with error messages
+
+A validator's `errors()` returns its messages, by field. `errors()` in a view returns the same kind of bag, read from
+the session:
+
+```ts
+declare const validator: import('@orieljs/framework/contracts').Validator
+// ---cut---
+const errors = validator.errors()
+
+const first = errors.first('email')
+```
+
+#### Retrieving all error messages for a field
+
+`get()` returns a field's messages, or an empty list. Fields under a wildcard are named by their index, as
+`attachments.0`:
+
+```ts
+declare const errors: import('@orieljs/framework/contracts').MessageBag
+// ---cut---
+for (const message of errors.get('email')) {
+  // ...
+}
+```
+
+#### Retrieving all error messages for all fields
+
+```ts
+declare const errors: import('@orieljs/framework/contracts').MessageBag
+// ---cut---
+for (const message of errors.all()) {
+  // ...
+}
+```
+
+#### Determining if messages exist for a field
+
+```ts
+declare const errors: import('@orieljs/framework/contracts').MessageBag
+// ---cut---
+if (errors.has('email')) {
+  // ...
+}
+```
+
+`isEmpty()` and `count()` tell you whether there are messages at all and how many, and `toObject()` returns them
+as `{ field: [messages] }`.
+
+Laravel reads its messages, custom messages and attribute names from `lang/en/validation.php`. Oriel has Laravel's
+English messages built in and no validation language file: give your own messages to the validator or the form
+request.
+
+## Available validation rules
+
+The rules by what they check, then each rule in alphabetical order.
+
+#### Booleans
+
+[`accepted`](#accepted), [`accepted_if`](#accepted_if), [`boolean`](#boolean), [`declined`](#declined),
+[`declined_if`](#declined_if)
+
+#### Strings
+
+[`active_url`](#active_url), [`alpha`](#alpha), [`alpha_dash`](#alpha_dash), [`alpha_num`](#alpha_num),
+[`ascii`](#ascii), [`confirmed`](#confirmed), [`current_password`](#current_password), [`different`](#different),
+[`doesnt_start_with`](#doesnt_start_with), [`doesnt_end_with`](#doesnt_end_with), [`email`](#email),
+[`ends_with`](#ends_with), [`enum`](#enum), [`hex_color`](#hex_color), [`in`](#in), [`ip`](#ip), [`ipv4`](#ipv4),
+[`ipv6`](#ipv6), [`json`](#json), [`lowercase`](#lowercase), [`mac_address`](#mac_address), [`max`](#max),
+[`min`](#min), [`not_in`](#not_in), [`regex`](#regex), [`not_regex`](#not_regex), [`same`](#same), [`size`](#size),
+[`starts_with`](#starts_with), [`string`](#string), [`uppercase`](#uppercase), [`url`](#url), [`ulid`](#ulid),
+[`uuid`](#uuid)
+
+#### Numbers
+
+[`between`](#between), [`decimal`](#decimal), [`different`](#different), [`digits`](#digits),
+[`digits_between`](#digits_between), [`gt`](#gt), [`gte`](#gte), [`integer`](#integer), [`lt`](#lt),
+[`lte`](#lte), [`max`](#max), [`max_digits`](#max_digits), [`min`](#min), [`min_digits`](#min_digits),
+[`multiple_of`](#multiple_of), [`numeric`](#numeric), [`same`](#same), [`size`](#size)
+
+#### Arrays
+
+[`array`](#array), [`between`](#between), [`contains`](#contains), [`doesnt_contain`](#doesnt_contain),
+[`distinct`](#distinct), [`in_array`](#in_array), [`in_array_keys`](#in_array_keys), [`list`](#list),
+[`max`](#max), [`min`](#min), [`size`](#size)
+
+#### Dates
+
+[`after`](#after), [`after_or_equal`](#after_or_equal), [`before`](#before),
+[`before_or_equal`](#before_or_equal), [`date`](#date), [`date_equals`](#date_equals),
+[`date_format`](#date_format), [`different`](#different), [`timezone`](#timezone)
+
+#### Files
+
+[`between`](#between), [`dimensions`](#dimensions), [`extensions`](#extensions), [`file`](#file),
+[`image`](#image), [`max`](#max), [`min`](#min), [`mimetypes`](#mimetypes), [`mimes`](#mimes), [`size`](#size)
+
+#### Database
+
+[`exists`](#exists), [`unique`](#unique)
+
+#### Utilities
+
+[`bail`](#bail), [`exclude`](#exclude), [`exclude_if`](#exclude_if), [`exclude_unless`](#exclude_unless),
+[`exclude_with`](#exclude_with), [`exclude_without`](#exclude_without), [`filled`](#filled),
+[`missing`](#missing), [`missing_if`](#missing_if), [`missing_unless`](#missing_unless),
+[`missing_with`](#missing_with), [`missing_with_all`](#missing_with_all), [`nullable`](#nullable),
+[`present`](#present), [`present_if`](#present_if), [`present_unless`](#present_unless),
+[`present_with`](#present_with), [`present_with_all`](#present_with_all), [`prohibited`](#prohibited),
+[`prohibited_if`](#prohibited_if), [`prohibited_if_accepted`](#prohibited_if_accepted),
+[`prohibited_if_declined`](#prohibited_if_declined), [`prohibited_unless`](#prohibited_unless),
+[`prohibits`](#prohibits), [`required`](#required), [`required_if`](#required_if),
+[`required_if_accepted`](#required_if_accepted), [`required_if_declined`](#required_if_declined),
+[`required_unless`](#required_unless), [`required_with`](#required_with),
+[`required_with_all`](#required_with_all), [`required_without`](#required_without),
+[`required_without_all`](#required_without_all), [`required_array_keys`](#required_array_keys),
+[`sometimes`](#sometimes)
+
+Most rules don't run on a field that is missing or blank text, so they pass it. Only `required`, `accepted`,
+`declined`, `filled`, `present` and `missing`, their `_if`, `_unless`, `_with` and `_without` forms, and the exclude
+rules run on one.
+
+#### accepted
+
+The field is `'yes'`, `'on'`, `1`, `'1'`, `true` or `'true'`, as a ticked "terms of service" checkbox sends. A
+missing field fails.
+
+#### accepted_if
+
+`accepted_if:anotherfield,value,...`: the field is accepted when the other field holds one of the values.
+
+#### active_url
+
+The URL's host has an address. The value is read as a URL, and its host looked up.
+
+> [!NOTE]
+> Laravel asks DNS for the host's `A` or `AAAA` records. Oriel asks the system's resolver with `dns.lookup()`, the
+> lookup Node makes to connect to a host, so the rule passes a host your app could reach by name: one only your
+> machine knows, such as `localhost` or one in `/etc/hosts`, passes too. The lookup has no timeout of its own.
+
+#### after
+
+`after:date`: a date after the one given. The parameter is another field's name, `now`, `today`, `tomorrow`,
+`yesterday`, an offset such as `+1 week` or `-3 days`, or a date. With `date_format` on the field, the value and the
+date are read with that format. A parameter that is neither, and doesn't look like a field's name, is an error in
+your rules (a 500). Laravel reads any phrase PHP's `strtotime()` knows; Oriel reads only these, and takes another
+word, such as `monday`, for a field's name. A number passes as a timestamp, as in Laravel, so the value is typed
+`string | number`, or `string` with `date` among the rules; the other date comparisons are typed the same way.
+
+#### after_or_equal
+
+`after_or_equal:date`: a date after or equal to the one given, read as `after` reads it.
+
+#### alpha
+
+Only the letters `A` to `Z` and `a` to `z`. Laravel's accepts letters of any script unless you write `alpha:ascii`;
+Oriel's accepts these letters only.
+
+#### alpha_dash
+
+Only the letters `A` to `Z` and `a` to `z`, digits, `-` and `_`.
+
+#### alpha_num
+
+Only the letters `A` to `Z` and `a` to `z`, and digits.
+
+#### array
+
+A list: a JavaScript array. `array:name,email` is an object whose keys are all among those named, as is
+`Rule.array(['name', 'email'])`:
+
+```ts
+const data = await request().validate({ user: 'required|array:name,username' })
+```
+
+> [!NOTE]
+> Laravel's `array` also accepts an associative array, which is what a JSON object becomes in PHP. In JavaScript an
+> object isn't a list, so Oriel's `array` refuses one and types the field `unknown[]`: typing an object as a list
+> would lie. Check an object's keys with `array:a,b` or `Rule.array([...])`. Both refuse an empty list, `[]`, which
+> some clients send for an empty object.
+
+#### ascii
+
+Only printable ASCII characters, tabs and line breaks: text or a number.
+
+#### bail
+
+Stops the field's rules at its first failure (see
+[stopping on first validation failure](#stopping-on-first-validation-failure)).
+
+#### before
+
+`before:date`: a date before the one given, read as `after` reads it.
+
+#### before_or_equal
+
+`before_or_equal:date`: a date before or equal to the one given, read as `after` reads it.
+
+#### between
+
+`between:min,max`: a size between `min` and `max`, both included. Sizes are measured as [`size`](#size) measures them.
+
+#### boolean
+
+`true`, `false`, `1`, `0`, `'1'` or `'0'`. `boolean:strict` accepts only `true` and `false`. The text `'true'` fails,
+as in Laravel.
+
+#### confirmed
+
+The field equals `<field>_confirmation`: `password` is compared with `password_confirmation`.
+`confirmed:repeat_password` names the other field.
+
+#### contains
+
+`contains:foo,bar`: an array that holds every value given. `1` and `'1'` count as the same value. `Rule.contains([...])`
+does the same.
+
+#### current_password
+
+The signed-in user's password. `current_password:api` checks the user of that guard. A guest fails.
+
+#### date
+
+Text that reads as a date: an ISO date, with or without a time, a date such as `10/19/2026`, month first, or one
+with a month name. A `YYYY-MM-DD` date without a time must be a real day.
+
+#### date_equals
+
+`date_equals:date`: the same date as the one given, read as `after` reads it.
+
+#### date_format
+
+`date_format:format,...`: a date in one of the formats, written with PHP's format characters, as
+`date_format:Y-m-d`. The value must read with the format and write back the same, so `2026-02-30` fails. Oriel
+reads the characters `d j D l S F M m n Y y a A g h G H i s v u O P p U`, and `\` to escape one; a format with one of
+PHP's other characters, such as `T` or `z`, is an error in your rules (a 500). Commas separate the formats, so a
+format can't hold one.
+
+#### decimal
+
+`decimal:min,max`: a number with `min` decimal places, or between `min` and `max`: `decimal:2` takes `1.25`.
+
+#### declined
+
+The field is `'no'`, `'off'`, `0`, `'0'`, `false` or `'false'`. A missing field fails.
+
+#### declined_if
+
+`declined_if:anotherfield,value,...`: the field is declined when the other field holds one of the values.
+
+#### different
+
+`different:field`: the field's value isn't the other field's. The values are compared exactly, so `1` and `'1'` are
+different.
+
+#### digits
+
+`digits:value`: only digits, exactly `value` of them.
+
+#### digits_between
+
+`digits_between:min,max`: only digits, between `min` and `max` of them.
+
+#### dimensions
+
+`dimensions:min_width=100,min_height=200`: an image whose size meets the constraints. The constraints are `width`,
+`height`, `min_width`, `max_width`, `min_height`, `max_height` and `ratio`, written `3/2` or `1.5`. The size is read
+from the image's header, for JPEG, PNG, GIF, WebP, AVIF and BMP; an SVG fails. `Rule.dimensions()` builds the rule:
+
+```ts
+const rule = Rule.dimensions().maxWidth(1000).maxHeight(500).ratio(3 / 2)
+```
+
+#### distinct
+
+On a list's items, none holds the same value as another: `'tags.*': 'distinct'`. `1` and `'1'` count as the same;
+`distinct:strict` compares exactly, and `distinct:ignore_case` ignores case.
+
+#### doesnt_contain
+
+`doesnt_contain:foo,bar`: an array that holds none of the values. `Rule.doesntContain([...])` does the same.
+
+#### doesnt_end_with
+
+`doesnt_end_with:foo,bar`: text or a number that doesn't end with any of the values.
+
+#### doesnt_start_with
+
+`doesnt_start_with:foo,bar`: text or a number that doesn't start with any of the values.
+
+#### email
+
+An email address: one `@` with text before it, no spaces, and a dot inside the part after it.
+
+> [!NOTE]
+> Laravel's `email` checks the address against RFC 5322 with PHP's `egulias/email-validator`, and its styles (`rfc`,
+> `strict`, `dns`, `spoof`, `filter`, `filter_unicode`) choose the checks. Those are PHP libraries' checks, so
+> Oriel's `email` is one pattern: it accepts the styles as parameters and doesn't act on them.
+
+#### ends_with
+
+`ends_with:foo,bar`: text or a number that ends with one of the values.
+
+#### enum
+
+One of an enum's values, with `Rule.enum()`. It takes a TypeScript enum, or an object of values `as const`, and
+types the field with the enum's values:
+
+```ts
+enum ServerStatus {
+  Active = 'active',
+  Inactive = 'inactive',
+}
+
+const data = await request().validate({
+  status: ['required', Rule.enum(ServerStatus)],
+})
+
+const status: ServerStatus = data.status
+```
+
+`only()` and `except()` narrow the values:
+
+```ts
+enum ServerStatus {
+  Active = 'active',
+  Inactive = 'inactive',
+}
+// ---cut---
+Rule.enum(ServerStatus).only([ServerStatus.Active])
+```
+
+A numeric enum takes its numbers, or exactly their text, `'1'` but not `'01'`, and its field is typed as either.
+
+#### exclude
+
+The field is left out of the validated data, and the rules after it don't run.
+
+#### exclude_if
+
+`exclude_if:anotherfield,value`: the field is left out when the other field holds the value, and nothing happens
+while the other field is missing. Write the exclude rules first: the rules before one run before it decides.
+
+```ts
+declare const data: Record<string, unknown>
+// ---cut---
+const validator = Validator.make(data, {
+  has_appointment: 'required|boolean',
+  appointment_date: 'exclude_if:has_appointment,false|required|date',
+  doctor_name: 'exclude_if:has_appointment,false|required|string',
+})
+```
+
+#### exclude_unless
+
+`exclude_unless:anotherfield,value`: the field is left out unless the other field holds the value.
+
+#### exclude_with
+
+`exclude_with:anotherfield`: the field is left out when the other field's key is there.
+
+#### exclude_without
+
+`exclude_without:anotherfield,...`: the field is left out when one of the others is missing or empty.
+
+#### exists
+
+`exists:table,column`: a row of the table holds the value in the column. Without a column, the field's name is the
+column, or its last part for a list's items (`email` for `users.*.email`). The query runs on the default
+connection. `Rule.exists('users', 'email')` does the same. Laravel's rule also takes a model's class, a
+`connection.table` and extra `where` conditions, which Oriel's doesn't.
+
+#### extensions
+
+`extensions:jpg,png`: an uploaded file whose name ends with one of the extensions. It checks the name only: pair it
+with `mimes` or `image`.
+
+#### file
+
+An uploaded file.
+
+#### filled
+
+When the key is there, its value isn't empty. A missing key passes.
+
+#### gt
+
+`gt:field`: greater than the other field. Numbers, and the text of numbers, compare by value, and two values of one
+kind (text, lists, files) by size; values of different kinds fail. `gt:10` compares a numeric value with the number,
+and any other value fails.
+
+#### gte
+
+`gte:field`: greater than or equal to the other field, compared as `gt` compares.
+
+#### hex_color
+
+A hexadecimal colour: `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`.
+
+#### image
+
+An image, by its bytes: JPEG, PNG, GIF, WebP, AVIF or BMP. `image:allow_svg` accepts SVG too, which can carry
+scripts.
+
+#### in
+
+`in:foo,bar`: the value's text is one of those listed, so `in:1,2` takes `1` and `'1'`. `Rule.in([...])` does the
+same, and types the field with its values. An object fails, and so does an array unless the field also has `array`;
+then every item must be listed:
+
+```ts
+const data = await request().validate({
+  zones: 'required|array|in:first-zone,second-zone',
+})
+```
+
+A comma always separates the values: Laravel's quoted values (`in:"a,b",c`) aren't read.
+
+#### in_array
+
+`in_array:anotherfield.*`: the value is one of the other field's values.
+
+#### in_array_keys
+
+`in_array_keys:foo,bar`: an object with at least one of the keys.
+
+#### integer
+
+A whole number: `5`, or text of digits with an optional minus, `'5'` or `'-3'`. `integer:strict` refuses text. The
+field is typed `NumericValue` (`number` with `:strict`), and nothing is converted.
+
+#### ip
+
+An IPv4 or IPv6 address.
+
+#### ipv4
+
+An IPv4 address.
+
+#### ipv6
+
+An IPv6 address.
+
+#### json
+
+Text that is valid JSON: `'{"name":"Taylor"}'` or `'5'`.
+
+> [!NOTE]
+> Laravel's `json` also passes a number, or `true`, as PHP turns them into JSON text first. A number, a boolean or an
+> object in a JSON body has already been read from JSON, so Oriel's `json` takes text only.
+
+#### list
+
+A list: a JavaScript array.
+
+#### lowercase
+
+Text or a number with no upper case letters.
+
+#### lt
+
+`lt:field`: less than the other field, compared as `gt` compares.
+
+#### lte
+
+`lte:field`: less than or equal to the other field, compared as `gt` compares.
+
+#### mac_address
+
+A MAC address: six pairs of hexadecimal digits joined all by `-` or all by `:`, or three groups of four joined by `.`.
+
+#### max
+
+`max:value`: a size of `value` or less, measured as [`size`](#size) measures it.
+
+#### max_digits
+
+`max_digits:value`: only digits, at most `value` of them.
+
+#### mimes
+
+`mimes:jpg,pdf`: an uploaded file of one of the types; `jpg` and `jpeg` are one. Oriel recognizes JPEG, PNG, GIF,
+WebP, AVIF, BMP, SVG, PDF, HTML and XML by their bytes, and a file of one of these kinds passes only by its own type.
+Plain text, also read from the bytes, passes `txt`, or its name's extension, such as `csv` or `yaml`, when the list
+names it and it isn't one of the kinds above. A file of a kind the bytes don't show, such as a `docx` or an `mp4`,
+passes by its name's extension, unless that extension names one of the kinds above or a text format such as `csv`.
+An empty file fails.
+
+#### mimetypes
+
+`mimetypes:text/plain,video/*`: an uploaded file whose type, read from its bytes, is listed, or matches a `type/*`. A
+file of a kind Oriel doesn't recognize is `application/octet-stream`.
+
+#### min
+
+`min:value`: a size of `value` or more, measured as [`size`](#size) measures it.
+
+#### min_digits
+
+`min_digits:value`: only digits, at least `value` of them.
+
+#### missing
+
+The key isn't there. A key holding `null` is there.
+
+#### missing_if
+
+`missing_if:anotherfield,value,...`: the key isn't there when the other field holds one of the values.
+
+#### missing_unless
+
+`missing_unless:anotherfield,value`: the key isn't there unless the other field holds the value.
+
+#### missing_with
+
+`missing_with:foo,bar`: the key isn't there when one of the other keys is.
+
+#### missing_with_all
+
+`missing_with_all:foo,bar`: the key isn't there when all of the other keys are.
+
+#### multiple_of
+
+`multiple_of:value`: a multiple of the number, in exact decimals: `0.3` is a multiple of `0.1`.
+
+#### not_in
+
+`not_in:foo,bar`: the value's text isn't one of those listed. `Rule.notIn([...])` does the same. An array or an object
+passes, unless the field has `array`; then it fails only when every item is listed. Pair `not_in` with `string` to
+refuse a list, or use `doesnt_contain` to refuse a list holding any of the values.
+
+#### not_regex
+
+`not_regex:pattern`: text or a number the pattern doesn't match.
+
+#### nullable
+
+`null` passes the field's other rules. See [a note on optional fields](#a-note-on-optional-fields).
+
+#### numeric
+
+A number, or text of one, as PHP's `is_numeric()` reads it: a sign, digits, a decimal point and an exponent, with
+spaces around. Hexadecimal text and `Infinity` fail. `numeric:strict` refuses text. The field is typed
+`NumericValue`, and nothing is converted.
+
+#### present
+
+The key is there, whatever its value, `null` and empty text included.
+
+#### present_if
+
+`present_if:anotherfield,value,...`: the key is there when the other field holds one of the values.
+
+#### present_unless
+
+`present_unless:anotherfield,value`: the key is there unless the other field holds the value.
+
+#### present_with
+
+`present_with:foo,bar`: the key is there when one of the other keys is.
+
+#### present_with_all
+
+`present_with_all:foo,bar`: the key is there when all of the other keys are.
+
+#### prohibited
+
+The field is missing or empty: `null`, blank text, `[]` or `{}`.
+
+#### prohibited_if
+
+`prohibited_if:anotherfield,value,...`: the field is missing or empty when the other field holds one of the values.
+`Rule.prohibitedIf(condition)` prohibits the field when the condition, or the function you give, is true.
+
+#### prohibited_if_accepted
+
+`prohibited_if_accepted:anotherfield`: the field is missing or empty when the other field is accepted.
+
+#### prohibited_if_declined
+
+`prohibited_if_declined:anotherfield`: the field is missing or empty when the other field is declined.
+
+#### prohibited_unless
+
+`prohibited_unless:anotherfield,value,...`: the field is missing or empty unless the other field holds one of the
+values.
+
+#### prohibits
+
+`prohibits:anotherfield,...`: when the field has a value, the others are missing or empty.
+
+#### regex
+
+`regex:pattern`: text the pattern matches, written as a JavaScript regular expression, with or without slashes and
+flags: `regex:/^[a-z]+$/i`. A pattern with a `|` must go in a list of rules, as a rule string splits on `|`.
+
+#### required
+
+The field is there and not empty: not `null`, not text made only of spaces, not `[]` and not `{}`. `0` and `false`
+pass. `Rule.requiredIf(condition)` requires the field when the condition, or the function you give, is true.
+
+#### required_array_keys
+
+`required_array_keys:foo,bar`: an object with every one of the keys. A list fails, `[]` included.
+
+#### required_if
+
+`required_if:anotherfield,value,...`: required when the other field holds one of the values. `true` and `false`
+match a boolean, and `'1'` and `'0'` too when the other field has the `boolean` rule; `null` matches a `null` field.
+Nothing is required while the other field is missing.
+
+#### required_if_accepted
+
+`required_if_accepted:anotherfield`: required when the other field is accepted.
+
+#### required_if_declined
+
+`required_if_declined:anotherfield`: required when the other field is declined.
+
+#### required_unless
+
+`required_unless:anotherfield,value,...`: required unless the other field holds one of the values.
+
+#### required_with
+
+`required_with:foo,bar`: required when one of the other fields has a value.
+
+#### required_with_all
+
+`required_with_all:foo,bar`: required when all of the other fields have a value.
+
+#### required_without
+
+`required_without:foo,bar`: required when one of the other fields is missing or empty.
+
+#### required_without_all
+
+`required_without_all:foo,bar`: required when all of the other fields are missing or empty.
+
+#### same
+
+`same:field`: the same value as the other field, compared exactly.
+
+#### size
+
+`size:value`: a size of exactly `value`. What a size is depends on the field:
+
+- with `numeric`, `integer` or `decimal` among its rules, the number itself;
+- for a list, its number of items, and for an object, its number of keys;
+- for an uploaded file, its size in kilobytes;
+- for anything else, its length in characters. A number without a numeric rule is measured by its text: `150` is 3.
+
+#### sometimes
+
+The field's rules run only when its key is there: `email: 'sometimes|required|email'` checks an email that is sent,
+and lets a request leave it out.
+
+#### starts_with
+
+`starts_with:foo,bar`: text or a number that starts with one of the values.
+
+#### string
+
+A string.
+
+#### timezone
+
+A time zone name, in its own case: `Europe/London`, not `europe/london`. Without a parameter, a zone in one of PHP's
+regions, or `UTC`. `timezone:Europe` takes that region's zones, `timezone:utc` only UTC, `timezone:all_with_bc` any
+name the runtime knows (`US/Eastern` too), and `timezone:per_country,US` the zones of a country.
+
+> [!NOTE]
+> Laravel checks the name against PHP's list of zones. PHP's lists can't be read from Node or Bun, so Oriel checks it
+> against the time zone data built into the runtime. Old names that the data keeps as links, such as
+> `Asia/Calcutta`, pass as zones. On Node, a link that the data reads as another zone is checked by its shape only, so
+> its case isn't checked: `Asia/ISTANBUL` passes on Node and fails on Bun.
+
+#### ulid
+
+A ULID.
+
+#### unique
+
+`unique:table,column`: no row of the table holds the value in the column. Without a column, the field's name is the
+column, or its last part for a list's items. To ignore one row, the user's own when they update their profile, use
+`Rule.unique()`:
+
+```ts
+declare const user: User
+// ---cut---
+const data = await request().validate({
+  email: ['required', 'email', Rule.unique('users').ignore(user)],
+})
+```
+
+`ignore()` takes a model or an id, and the id's column as its second argument. The string rule takes them as
+`unique:users,email,5,id`. The query runs on the default connection. Laravel's rule also takes a model's class, a
+`connection.table` and extra `where` conditions, which Oriel's doesn't.
+
+#### uppercase
+
+Text or a number with no lower case letters.
+
+#### url
+
+A URL: one of Laravel's schemes followed by `://` and a host, so `javascript:` and `mailto:` URLs fail.
+`url:http,https` allows only those schemes.
+
+#### uuid
+
+A UUID of any version. `uuid:4` takes version 4 only; the versions are `1` to `8`, `nil` (or `0`) and `max`.
+
+## Conditionally adding rules
+
+#### Skipping validation when fields have certain values
+
+`exclude_if` and `exclude_unless` leave a field out of validation, and of the validated data, depending on another
+field (see [`exclude_if`](#exclude_if)).
+
+#### Validating when present
+
+`sometimes` validates a field only when the request sends it:
+
+```ts
+declare const data: Record<string, unknown>
+// ---cut---
+const validator = Validator.make(data, {
+  email: 'sometimes|required|email',
+})
+```
+
+#### Complex conditional validation
+
+`Rule.when()` chooses a field's rules from the data: its function receives the data, and the rules apply when it
+returns `true`. A third argument gives the rules for `false`, and `Rule.unless()` is the opposite:
+
+```ts
+const data = await request().validate({
+  games: 'required|integer|min:0',
+  reason: [Rule.when((input) => Number(input.games) >= 100, 'required|max:500', 'nullable')],
+})
+```
+
+Laravel's validator also has a `sometimes()` method that adds rules after the validator is made. Oriel's doesn't:
+give the field a `Rule.when()`.
+
+## Validating arrays
+
+`array` with keys, `array:name,username`, checks that an object has only the keys you name. Without one, an object
+fails `array` (see [`array`](#array)):
+
+```ts
+declare const input: Record<string, unknown>
+// ---cut---
+const validator = Validator.make(input, {
+  user: 'array:name,username',
+})
+```
+
+### Validating nested array input
+
+Dots name the fields inside an object, and `*` every item of a list or every value of an object:
+
+```ts
+declare const input: Record<string, unknown>
+// ---cut---
+const validator = Validator.make(input, {
+  'photos.profile': 'required|image',
+  'users.*.email': 'email|unique:users',
+  'users.*.first_name': 'required_with:users.*.last_name',
+})
+```
+
+Here `required_with` fills the `*` of `users.*.last_name` with the item's index, so each user's `first_name` is
+checked against the same user's `last_name`. The rules that compare two fields, such as `same`, `gt`, `after` and the
+`_if` and `_with` rules, do the same; `in_array` reads every item. Errors are named by the item, as `users.2.email`.
+Laravel's `:index` and `:position` placeholders, and `Rule::forEach()`, aren't in Oriel.
+
+## Validating files
+
+The file rules check an uploaded file: `file`, `image`, `mimes`, `mimetypes`, `extensions` and `dimensions`, with
+`size`, `min`, `max` and `between` in kilobytes:
+
+```ts
+const data = await request().validate({
+  photo: ['required', 'image', 'max:2048', Rule.dimensions().maxWidth(1000).maxHeight(500)],
+})
+```
+
+`image`, `mimes` and `mimetypes` judge a file by its bytes, not by the type the browser sent; `mimes` reads the
+name only for plain text and for the kinds the bytes don't show (see [`mimes`](#mimes)). A file named like a PHP
+script, such as `.php` or `.phtml`, fails `image`, and fails `mimes`, `mimetypes` and `extensions` unless they list
+`php`. A body larger than the [body size limit](requests.md#body-size-limits) is refused before your rules run.
+Laravel's `File::types()` builder isn't in Oriel: write the rules.
+
+## Validating passwords
+
+`Rule.password()` checks a password against your app's password rule: by default, text of at least 8 characters.
+`PasswordRule` builds a stricter one:
+
+```ts
+// Require at least 8 characters...
+PasswordRule.min(8)
+
+// Require at least one letter...
+PasswordRule.min(8).letters()
+
+// Require at least one uppercase and one lowercase letter...
+PasswordRule.min(8).mixedCase()
+
+// Require at least one number...
+PasswordRule.min(8).numbers()
+
+// Require at least one symbol...
+PasswordRule.min(8).symbols()
+```
+
+`max()` sets a maximum length. Each check that fails adds its own message.
+
+#### Defining default password rules
+
+`PasswordRule.defaults()` sets the rule `Rule.password()` returns. Call it in a service provider's `boot()`:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { app, PasswordRule, ServiceProvider } from '@orieljs/framework'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    PasswordRule.defaults(() => {
+      const rule = PasswordRule.min(8)
+
+      return app().environment('production') ? rule.mixedCase().numbers() : rule
+    })
+  }
+}
+```
+
+Then `Rule.password()` returns that rule wherever you use it, as the starter kits do:
+
+```ts
+const data = await request().validate({
+  password: ['required', 'confirmed', Rule.password()],
+})
+```
+
+Laravel's rule is the `Password` class; Oriel's `Password` is the password broker, so the rule is `PasswordRule`.
+Laravel's `uncompromised()`, which asks an outside service whether a password has leaked, and `rules()` aren't in
+Oriel.
+
+## Custom validation rules
+
+### Rule objects
+
+A rule object is a class with a `validate()` method. `make:rule` writes one in `app/Rules`:
+
+```sh
+node oriel make:rule Uppercase
+```
+
+`validate()` receives the field's name, its value, a `fail()` function to call with a message, and all of the data
+under validation:
+
+```ts title="app/Rules/Uppercase.ts"
+import type { ValidationRule } from '@orieljs/framework/contracts'
+
+export class Uppercase implements ValidationRule {
+  validate(attribute: string, value: unknown, fail: (message: string) => void): void {
+    if (typeof value !== 'string' || value.toUpperCase() !== value) {
+      fail(`The ${attribute} field must be uppercase.`)
+    }
+  }
+}
+```
+
+Put an instance in the field's list of rules:
+
+```ts
+// @filename: app/Rules/Uppercase.ts
+export declare class Uppercase {
+  validate(attribute: string, value: unknown, fail: (message: string) => void): void
+}
+// ---cut---
+import { Uppercase } from './app/Rules/Uppercase'
+
+const data = await request().validate({
+  name: ['required', 'string', new Uppercase()],
+})
+```
+
+`validate()` may be async. `:attribute` in the message becomes the field's name, as in the built-in messages, and
+your custom attribute names apply to it. Each call to `fail()` adds a message. The fourth argument, the data,
+replaces Laravel's `DataAwareRule`.
+
+A rule object doesn't change the field's type unless it says what passes. Declare a `__typing` field, which is
+never set:
+
+```ts title="app/Rules/Uppercase.ts"
+import type { TypedValidationRule } from '@orieljs/framework/contracts'
+
+export class Uppercase implements TypedValidationRule<{ value: string }> {
+  declare readonly __typing?: { value: string }
+
+  validate(attribute: string, value: unknown, fail: (message: string) => void): void {
+    if (typeof value !== 'string' || value.toUpperCase() !== value) {
+      fail(`The ${attribute} field must be uppercase.`)
+    }
+  }
+}
+```
+
+### Using closures
+
+A rule you need once can be an object with a `validate()` method, written in place:
+
+```ts
+const validator = Validator.make(request().all(), {
+  title: [
+    'required',
+    'max:255',
+    {
+      validate(attribute: string, value: unknown, fail: (message: string) => void) {
+        if (value === 'foo') {
+          fail(`The ${attribute} is invalid.`)
+        }
+      },
+    },
+  ],
+})
+```
+
+Laravel takes a closure in the list of rules; Oriel's list takes strings and rule objects, so the closure becomes an
+object's `validate()`.
+
+### Registering string rules
+
+`Validator.extend()` registers a rule you write as a string, with its message, in a service provider's `boot()`. Its
+function receives the field's name, its value, the rule's parameters and the data, and returns whether the value
+passes:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { ServiceProvider, Validator } from '@orieljs/framework'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Validator.extend(
+      'slug',
+      (attribute, value) => typeof value === 'string' && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value),
+      'The :attribute field must be a slug.',
+    )
+  }
+}
+```
+
+The rule's message fills `:attribute`, and custom messages replace it as they replace a built-in rule's. A rule
+registered with a built-in rule's name replaces the built-in rule. To type the fields that pass the rule, add it to
+`ValidationRuleTypes` in a declaration file:
+
+```ts title="types/validation.d.ts"
+import type {} from '@orieljs/framework/contracts'
+
+declare module '@orieljs/framework/contracts' {
+  interface ValidationRuleTypes<Parameters extends string = string> {
+    slug: { value: string }
+  }
+}
+
+export {}
+```
+
+### Implicit rules
+
+Rule objects and the rules of `Validator.extend()` don't run on a field that is missing or blank text, as most
+built-in rules don't. Laravel's implicit rules, which run on such a field too, aren't in Oriel: combine your rule with
+`required`.
+
+## Rules that don't apply to Node
+
+Some of Laravel's rules check what PHP does, and have no counterpart on Node and Bun:
+
+- **`email`'s styles**: `rfc`, `strict`, `spoof`, `filter` and `filter_unicode` are the checks of PHP's
+  `egulias/email-validator` and `filter_var()`. Oriel's `email` accepts them and doesn't act on them (see
+  [`email`](#email)).
+- **The `uploaded` failure**: Laravel fails a file PHP's own body parser couldn't receive whole. Oriel reads the body
+  itself, so a file that arrives is whole.
+- **`mimes` and `mimetypes`**: they judge the bytes with Oriel's own detector, not PHP's `finfo`. A file of a kind
+  Oriel doesn't recognize passes `mimes` by its name's extension, and is `application/octet-stream` to `mimetypes`
+  (see [`mimes`](#mimes)).
+
+Others apply, with the runtime's data:
+
+- **`timezone`** checks against the runtime's time zone data, not PHP's lists (see [`timezone`](#timezone)).
+- **`active_url`** asks the system's resolver (see [`active_url`](#active_url)).
+- **`date_format`** reads the format characters listed in [`date_format`](#date_format); PHP's others are an error.
+
+And some aren't in Oriel yet: `email:dns`, `encoding`, `Password::uncompromised()`, Laravel's quoted parameters
+(`in:"a,b",c`), and the builders `Rule::forEach()`, `Rule::date()`, `Rule::email()`, `Rule::numeric()`,
+`Rule::file()`, `Rule::imageFile()`, `Rule::anyOf()` and `Rule::can()`.