PHPackages                             rsthn/rose-ext-shield - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. rsthn/rose-ext-shield

ActiveRose-extension[Validation & Sanitization](/categories/validation)

rsthn/rose-ext-shield
=====================

Shield Validation Extension

v3.0.8(1w ago)17663Apache-2.0PHP

Since May 16Pushed 1w ago1 watchersCompare

[ Source](https://github.com/rsthn/rose-ext-shield)[ Packagist](https://packagist.org/packages/rsthn/rose-ext-shield)[ RSS](/packages/rsthn-rose-ext-shield/feed)WikiDiscussions master Synced yesterday

READMEChangelogDependencies (4)Versions (64)Used By (3)

Shield Validation Extension
===========================

[](#shield-validation-extension)

Shield provides a set of functions to validate data in a very robust way.

Installation
============

[](#installation)

```
composer require rsthn/rose-ext-shield
```

Functions
=========

[](#functions)

### (`shield:method-required` <method...>)

[](#shieldmethod-required-method)

Ensures the request was made using the specified method(s) or fails with 405/@messages.method\_not\_allowed.

### (`shield:body-required` \[false|true|content-type...\])

[](#shieldbody-required-falsetruecontent-type)

Ensures the request's content-type is one of the specified types. Fails with 422/@messages.request\_body\_missing if there is no request body, or with 422/@messages.invalid\_content\_type if the content-type is not valid. If no content type is provided then it is assumed to be `application/json`. Use value `true` to allow any content type.

### (`shield:body-min-size` <min-size>)

[](#shieldbody-min-size-min-size)

Ensures the request's body is at least the specified number of bytes. Fails with 422/@messages.request\_body\_too\_small if not.

### (`shield:body-max-size` <max-size>)

[](#shieldbody-max-size-max-size)

Ensures the request's body does not exceed the specified number of bytes. Fails with 422/@messages.request\_body\_too\_large when so.

### (`shield:ruleset` \[ruleset-name\] <rules...>)

[](#shieldruleset-ruleset-name-rules)

Registers a set of validation rules with the given name. This can later be used by name from the `use \` rule.

```
(shield:ruleset "email"
  max-length 256
  pattern email
)
```

### (`shield:model` \[name\] <data-descriptor>)

[](#shieldmodel-name-data-descriptor)

Registers a validation model with the given name to be used later with `shield:validate`.

```
(shield:model "Model1"
   (object
      "username" (string)
      "password" (string)
      "email" (rules
          required true
          pattern email
          use "verify-unique"
       )
   )
)
```

### (`shield:validate` <input-object> <model-names>...)

[](#shieldvalidate-input-object-model-names)

Validates the input data using the specified models. If any validation error occurs an exception will be thrown.

```
(shield:validate (gateway.body) "Model1")
```

### (`shield:validate-ctx` <context-object> <input-object> <model-names>...)

[](#shieldvalidate-ctx-context-object-input-object-model-names)

Validates the input data using the specified models and passes the provided context as "$ctx" variable to all validators. Returns the validated object and its context. If any validation error occurs an exception will be thrown.

```
(shield:validate-ctx {} (gateway.body) "Model1")
; {"data":{},"ctx":{}}
```

### (`shield:begin`)

[](#shieldbegin)

Begins quiet validation mode. All validation errors will be accumulated, and should later be retrieved by calling `shield:end`, this is useful to batch multiple validation blocks at once.

### (`shield:end` \[automatic=true\])

[](#shieldend-automatictrue)

Ends quiet validation mode, if there are any errors and `automatic` is set to `true` (default), then Wind::R\_VALIDATION\_ERROR will be thrown, otherwise, the error map will just be returned.

Validation Rules
================

[](#validation-rules)

Rules are listed inside a `(rules ...)` block, a `(shield:ruleset ...)` definition or directly within field descriptors. They run top-to-bottom and each rule receives the current value through the `$` variable, the input object through `$in`, the output object through `$out` and the context object (when using `shield:validate-ctx`) through `$ctx`.

When a rule fails, an error message is reported using the rule's identifier (e.g. `@messages.required:true`, `@messages.min-length:3`). You can override that identifier by appending `:@your-key` to the rule name (e.g. `check:@invalid`, `fail:@error-message`, `enum:@invalid-value`). The `@`-prefixed identifier is looked up directly under `@messages`, without the rule-name prefix.

Presence and Required
---------------------

[](#presence-and-required)

### (`required` <true|false|"true|null"|"true|empty">)

[](#required-truefalsetruenulltrueempty)

Validates that the trimmed value is not empty. Behavior depends on the argument:

- `true` — value must be a non-empty string, otherwise fails with `required:true`.
- `false` — if value is empty the field is dropped from the output (no error).
- `"true|null"` — if value is empty, set it to `null` and stop subsequent rules.
- `"true|empty"` — if value is empty, set it to `""` and stop subsequent rules.

```
(shield:ruleset "name" required true max-length 64)
```

### (`presence` <true|false|"true|null"|"true|empty">)

[](#presence-truefalsetruenulltrueempty)

Same semantics as `required`, but checks whether the field key is present in the input rather than whether the value is non-empty. Useful to allow empty strings while still requiring the key to exist.

```
(shield:model (object name (rules presence true)))
```

Length and Size
---------------

[](#length-and-size)

### (`min-length` <n>)

[](#min-length-n)

Ensures the string length is `>= n`. Fails with `min-length:n`. Throws if the value is not a string.

### (`max-length` <n>)

[](#max-length-n)

Ensures the string length is `= n`. Throws if the value is not numeric.

### (`max-value` <n>)

[](#max-value-n)

Ensures the numeric value is ` ($) 0)
```

### (`fail` <bool>)

[](#fail-bool)

Inverse of `check` — fails when the expression evaluates to `true`. Use `fail:@my-msg true` to abort with a custom error.

### (`ignore` <bool>)

[](#ignore-bool)

When the argument is `true`, drops the current field from the output and stops further rules. Useful inside `(array ...)` to skip elements based on a predicate (`ignore (in? ["red"] ($))`).

### (`stop` <bool>)

[](#stop-bool)

When the argument is `true`, stops further rules in the current ruleset, keeping the current value as-is.

### (`requires` <"field"|"field|error"|"field|stop">)

[](#requires-fieldfielderrorfieldstop)

Ensures another field has already been validated and emitted to the output. The action after `|`:

- (omitted) — if the field is missing, drop the current field silently (`IgnoreField`).
- `error` — if missing, fails with `requires:`.
- `stop` — if missing, stop further rules but keep the current value.

```
(shield:model (object
    ref? (int)
    name (rules requires "ref|error" required true)
))
```

### (`case-when` <cond>) / (`case-else`) / (`case-end`)

[](#case-when-cond--case-else--case-end)

Conditional execution of subsequent rules until the next `case-when`, `case-else` or `case-end`. The first matching `case-when`runs its block; remaining branches are skipped until `case-end`.

```
(shield:ruleset __inline__
    case-when (in? ($) "hello")  set "found_hello"
    case-when (in? ($) "bye")    set "found_bye"
    case-else                    set "none"
    case-end
)
```

> Note: nested `case-when` blocks are not supported.

Composition
-----------

[](#composition)

### (`use` <ruleset-or-model-name>)

[](#use-ruleset-or-model-name)

Runs a previously registered ruleset or model against the current value, threading errors back into the current path. Allows sharing rule pipelines.

```
(shield:ruleset "email" required true pattern "email")
(shield:model (object email (rules use "email")))
```

### (`block` <expressions...>)

[](#block-expressions)

Executes one or more expressions purely for their side effects, without affecting the current value. Useful to write computed fields to `$out` or to perform extra logic.

```
block (
    set $out.full-name (concat $out.first " " $out.last)
)
```

File Uploads
------------

[](#file-uploads)

### (`file-type` <comma-separated-extensions>)

[](#file-type-comma-separated-extensions)

Validates that an uploaded file (a Rose file map) has a name with one of the given extensions. Fails when the upload has an error or the extension does not match.

```
(rules file-type "jpg,jpeg,png")
```

### (`max-file-size` <bytes>)

[](#max-file-size-bytes)

Validates that an uploaded file's size is `