From 258cdd739ff2b528dab7a29c14e06f948217b993 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Wed, 10 Jul 2024 16:22:50 +0100 Subject: [PATCH 1/8] chore: updated ddev config --- .ddev/config.yaml | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/.ddev/config.yaml b/.ddev/config.yaml index 7b177d7..65b9c6d 100644 --- a/.ddev/config.yaml +++ b/.ddev/config.yaml @@ -13,6 +13,7 @@ omit_containers: [db] use_dns_when_possible: true composer_version: "2" web_environment: [] +corepack_enable: false disable_upload_dirs_warning: true # Key features of DDEV's config.yaml: @@ -20,13 +21,14 @@ disable_upload_dirs_warning: true # name: # Name of the project, automatically provides # http://projectname.ddev.site and https://projectname.ddev.site -# type: # backdrop, craftcms, django4, drupal6/7/8/9/10, laravel, magento, magento2, php, python, shopware6, silverstripe, typo3, wordpress -# See https://ddev.readthedocs.io/en/latest/users/quickstart/ for more +# type: # backdrop, craftcms, django4, drupal, drupal6, drupal7, laravel, magento, magento2, php, python, shopware6, silverstripe, typo3, wordpress +# See https://ddev.readthedocs.io/en/stable/users/quickstart/ for more # information on the different project types +# "drupal" covers recent Drupal 8+ # docroot: # Relative path to the directory containing index.php. -# php_version: "8.1" # PHP version to use, "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2", "8.3" +# php_version: "8.2" # PHP version to use, "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2", "8.3" # You can explicitly specify the webimage but this # is not recommended, as the images are often closely tied to DDEV's' behavior, @@ -36,8 +38,9 @@ disable_upload_dirs_warning: true # database: # type: # mysql, mariadb, postgres -# version: # database version, like "10.4" or "8.0" -# MariaDB versions can be 5.5-10.8 and 10.11, MySQL versions can be 5.5-8.0 +# version: # database version, like "10.11" or "8.0" +# MariaDB versions can be 5.5-10.8, 10.11, and 11.4. +# MySQL versions can be 5.5-8.0. # PostgreSQL versions can be 9-16. # router_http_port: # Port to be used for http (defaults to global configuration, usually 80) @@ -77,7 +80,7 @@ disable_upload_dirs_warning: true # Alternatively, an explicit Composer version may be specified, for example "2.2.18". # To reinstall Composer after the image was built, run "ddev debug refresh". -# nodejs_version: "18" +# nodejs_version: "20" # change from the default system Node.js version to any other version. # Numeric version numbers can be complete (i.e. 18.15.0) or # incomplete (18, 17.2, 16). 'lts' and 'latest' can be used as well along with @@ -86,6 +89,9 @@ disable_upload_dirs_warning: true # Note that you can continue using 'ddev nvm' or nvm inside the web container # to change the project's installed node version if you need to. +# corepack_enable: false +# Change to 'true' to 'corepack enable' and gain access to latest versions of yarn/pnpm + # additional_hostnames: # - somename # - someothername @@ -143,8 +149,8 @@ disable_upload_dirs_warning: true # - "mutagen": enables Mutagen for this project. # - "nfs": enables NFS for this project. # -# See https://ddev.readthedocs.io/en/latest/users/install/performance/#nfs -# See https://ddev.readthedocs.io/en/latest/users/install/performance/#mutagen +# See https://ddev.readthedocs.io/en/stable/users/install/performance/#nfs +# See https://ddev.readthedocs.io/en/stable/users/install/performance/#mutagen # fail_on_hook_fail: False # Decide whether 'ddev start' should be interrupted by a failing hook @@ -197,7 +203,7 @@ disable_upload_dirs_warning: true # disable_settings_management: false # If true, DDEV will not create CMS-specific settings files like -# Drupal's settings.php/settings.ddev.php or TYPO3's AdditionalConfiguration.php +# Drupal's settings.php/settings.ddev.php or TYPO3's additional.php # In this case the user must provide all such settings. # You can inject environment variables into the web container with: From d260e6cb4a7b9fea69bfeca2a5a3e667d450af31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Thu, 11 Jul 2024 16:29:58 +0100 Subject: [PATCH 2/8] feat: added cssColor rule --- src/ChainedValidatorInterface.php | 5 ++ src/Exception/CssColorException.php | 5 ++ src/Rule/CssColor.php | 114 ++++++++++++++++++++++++++++ src/StaticValidatorInterface.php | 5 ++ tests/CssColorTest.php | 60 +++++++++++++++ 5 files changed, 189 insertions(+) create mode 100644 src/Exception/CssColorException.php create mode 100644 src/Rule/CssColor.php create mode 100644 tests/CssColorTest.php diff --git a/src/ChainedValidatorInterface.php b/src/ChainedValidatorInterface.php index c6c11bc..23b2116 100644 --- a/src/ChainedValidatorInterface.php +++ b/src/ChainedValidatorInterface.php @@ -39,6 +39,11 @@ public function country( ?string $message = null ): ChainedValidatorInterface&Validator; + public function cssColor( + ?array $formats = null, + ?string $message = null + ): ChainedValidatorInterface&Validator; + public function dateTime( string $format = 'Y-m-d H:i:s', ?string $message = null diff --git a/src/Exception/CssColorException.php b/src/Exception/CssColorException.php new file mode 100644 index 0000000..f532179 --- /dev/null +++ b/src/Exception/CssColorException.php @@ -0,0 +1,5 @@ + self::PATTERN_HEX_LONG, + self::FORMAT_HEX_LONG_WITH_ALPHA => self::PATTERN_HEX_LONG_WITH_ALPHA, + self::FORMAT_HEX_SHORT => self::PATTERN_HEX_SHORT, + self::FORMAT_HEX_SHORT_WITH_ALPHA => self::PATTERN_HEX_SHORT_WITH_ALPHA, + self::FORMAT_BASIC_NAMED_COLORS => self::PATTERN_BASIC_NAMED_COLORS, + self::FORMAT_EXTENDED_NAMED_COLORS => self::PATTERN_EXTENDED_NAMED_COLORS, + self::FORMAT_SYSTEM_COLORS => self::PATTERN_SYSTEM_COLORS, + self::FORMAT_KEYWORDS => self::PATTERN_KEYWORDS, + self::FORMAT_RGB => self::PATTERN_RGB, + self::FORMAT_RGBA => self::PATTERN_RGBA, + self::FORMAT_HSL => self::PATTERN_HSL, + self::FORMAT_HSLA => self::PATTERN_HSLA + ]; + + private array $formats; + private string $message = 'The {{ name }} value is not a valid CSS color.'; + + public function __construct( + ?array $formats = null, + ?string $message = null + ) + { + $this->formats = $formats ?? self::COLOR_FORMATS; + $this->message = $message ?? $this->message; + } + + public function assert(mixed $value, ?string $name = null): void + { + foreach ($this->formats as $format) { + if (!\in_array($format, self::COLOR_FORMATS, true)) { + throw new UnexpectedOptionException('format', self::COLOR_FORMATS, $format); + } + } + + if (!\is_string($value)) { + throw new UnexpectedTypeException('string', get_debug_type($value)); + } + + foreach ($this->formats as $format) { + $pattern = self::COLOR_PATTERNS[$format]; + + // it is valid if at least one pattern matches + if (\preg_match($pattern, $value)) { + return; + } + } + + throw new CssColorException( + message: $this->message, + parameters: [ + 'value' => $value, + 'name' => $name, + 'formats' => $this->formats + ] + ); + } +} \ No newline at end of file diff --git a/src/StaticValidatorInterface.php b/src/StaticValidatorInterface.php index 74d0992..ca9c931 100644 --- a/src/StaticValidatorInterface.php +++ b/src/StaticValidatorInterface.php @@ -38,6 +38,11 @@ public static function country( ?string $message = null ): ChainedValidatorInterface&Validator; + public static function cssColor( + ?array $formats = null, + ?string $message = null + ): ChainedValidatorInterface&Validator; + public static function dateTime( string $format = 'Y-m-d H:i:s', ?string $message = null diff --git a/tests/CssColorTest.php b/tests/CssColorTest.php new file mode 100644 index 0000000..604bac0 --- /dev/null +++ b/tests/CssColorTest.php @@ -0,0 +1,60 @@ + [new CssColor(formats: ['invalid']), '#123456', $unexpectedOptionMessage]; + yield 'invalid type' => [new CssColor(), 1, $unexpectedTypeMessage]; + } + + public static function provideRuleFailureConditionData(): \Generator + { + $exception = CssColorException::class; + $message = '/The (.*) value is not a valid CSS color\./'; + + yield 'format' => [new CssColor(), 'invalid', $exception, $message]; + } + + public static function provideRuleSuccessConditionData(): \Generator + { + yield 'hex-long' => [new CssColor(formats: ['hex-long']), '#0f0f0f']; + yield 'hex-long-with-alpha' => [new CssColor(formats: ['hex-long-with-alpha']), '#0f0f0f50']; + yield 'hex-short' => [new CssColor(formats: ['hex-short']), '#0f0']; + yield 'hex-short-with-alpha' => [new CssColor(formats: ['hex-short-with-alpha']), '#0f05']; + yield 'basic-named-colors' => [new CssColor(formats: ['basic-named-colors']), 'black']; + yield 'extended-names-colors' => [new CssColor(formats: ['extended-named-colors']), 'darkgoldenrod']; + yield 'system-colors' => [new CssColor(formats: ['system-colors']), 'AccentColor']; + yield 'keywords' => [new CssColor(formats: ['keywords']), 'transparent']; + yield 'rgb' => [new CssColor(formats: ['rgb']), 'rgb(0, 255, 0)']; + yield 'rgba' => [new CssColor(formats: ['rgba']), 'rgba(0, 255, 0, 0)']; + yield 'hsl' => [new CssColor(formats: ['hsl']), 'hsl(0, 50%, 50%)']; + yield 'hsla' => [new CssColor(formats: ['hsla']), 'hsla(0, 50%, 50%, 0)']; + } + + public static function provideRuleMessageOptionData(): \Generator + { + yield 'message' => [ + new CssColor(message: '{{ name }} | {{ value }} | {{ formats }}'), + 'invalid', + 'test | "invalid" | ["hex-long", "hex-long-with-alpha", "hex-short", "hex-short-with-alpha", "basic-named-colors", "extended-named-colors", "system-colors", "keywords", "rgb", "rgba", "hsl", "hsla"]' + ]; + } +} \ No newline at end of file From d170e521ac67df4523b13fb5412b367dde528ce6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Thu, 11 Jul 2024 17:25:26 +0100 Subject: [PATCH 3/8] docs: added cssColor rule documentation --- docs/03-rules.md | 1 + docs/03-rules_css-color.md | 113 +++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 docs/03-rules_css-color.md diff --git a/docs/03-rules.md b/docs/03-rules.md index f127121..c168671 100644 --- a/docs/03-rules.md +++ b/docs/03-rules.md @@ -16,6 +16,7 @@ ## String Rules +- [CssColor](03-rules_css-color.md) - [Email](03-rules_email.md) - [Length](03-rules_length.md) - [PasswordStrength](03-rules_password-strength.md) diff --git a/docs/03-rules_css-color.md b/docs/03-rules_css-color.md new file mode 100644 index 0000000..a6873f2 --- /dev/null +++ b/docs/03-rules_css-color.md @@ -0,0 +1,113 @@ +# CssColor + +Validates that a value is a valid CSS color. + +```php +CssColor( + ?array $formats = null, + ?string $message = null +); +``` + +## Basic Usage + +```php +// by default, all possible ways to define a CSS color are considered valid +Validator::cssColor()->validate('#0f0f0f'); // true +Validator::cssColor()->validate('black'); // true +Validator::cssColor()->validate('rgb(0, 255, 0'); // true +// ... + +// restrict allowed formats +Validator::cssColor(formats: ['hex-long'])->validate('#0f0f0f'); // true +Validator::cssColor(formats: ['hex-long'])->validate('rgb(0, 255, 0)'); // false +Validator::cssColor(formats: ['hex-long', 'rgb'])->validate('rgb(0, 255, 0)'); // true +``` + +> [!NOTE] +> An `UnexpectedValueException` will be thrown when a `formats` option is invalid. + +## Options + +### `formats` + +type: `?array` default: `null` + +By default, all possible ways to define a CSS color are considered valid. +Use this options to restrict the allowed CSS formats. + +Available options are: + +#### `hex-long` + +Examples: `#0f0f0f`, `#0F0F0F` + +#### `hex-long-with-alpha` + +Examples: `#0f0f0f50`, `#0F0F0F50` + +#### `hex-short` + +Examples: `#0f0`, `#0F0` + +#### `hex-short-with-alpha` + +Examples: `#0f05`, `#0F05` + +#### `basic-named-colors` + +Colors names defined in the [W3C list of basic names colors](https://www.w3.org/wiki/CSS/Properties/color/keywords#Basic_Colors). + +Examples: `black`, `green` + +#### `extended-named-colors` + +Colors names defined in the [W3C list of extended names colors](https://www.w3.org/wiki/CSS/Properties/color/keywords#Extended_colors). + +Examples: `black`, `aqua`, `darkgoldenrod`, `green` + +#### `system-colors` + +Colors names defined in the [CSS WG list of system colors](https://drafts.csswg.org/css-color/#css-system-colors). + +Examples: `AccentColor`, `VisitedText` + +#### `keywords` + +Colors names defined in the [CSS WG list of keywords](https://drafts.csswg.org/css-color/#transparent-color). + +Examples: `transparent`, `currentColor` + +#### `rgb` + +Examples: `rgb(0, 255, 0)`, `rgb(0,255,0)` + +#### `rgba` + +Examples: `rgba(0, 255, 0, 50)`, `rgba(0,255,0,50)` + +#### `hsl` + +Examples: `hsl(0, 50%, 50%)`, `hsl(0,50%,50%)` + +#### `hsla` + +Examples: `hsla(0, 50%, 50%, 0.5)`, `hsla(0,50%,50%,0.5)` + +### `message` + +type: `?string` default: `The {{ name }} value is not a valid CSS color.` + +Message that will be shown if the input value is not a valid CSS color. + +The following parameters are available: + +| Parameter | Description | +|-----------------|---------------------------| +| `{{ value }}` | The current invalid value | +| `{{ name }}` | Name of the invalid value | +| `{{ formats }}` | Selected formats | + +## Changelog + +- `1.2.0` Created \ No newline at end of file From 0a13832572410397322282a57bbea333c01d5b75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Thu, 11 Jul 2024 17:32:06 +0100 Subject: [PATCH 4/8] docs: added formats options nav --- docs/03-rules_css-color.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/03-rules_css-color.md b/docs/03-rules_css-color.md index a6873f2..9e885b7 100644 --- a/docs/03-rules_css-color.md +++ b/docs/03-rules_css-color.md @@ -15,7 +15,7 @@ CssColor( // by default, all possible ways to define a CSS color are considered valid Validator::cssColor()->validate('#0f0f0f'); // true Validator::cssColor()->validate('black'); // true -Validator::cssColor()->validate('rgb(0, 255, 0'); // true +Validator::cssColor()->validate('rgb(0, 255, 0)'); // true // ... // restrict allowed formats @@ -38,7 +38,20 @@ Use this options to restrict the allowed CSS formats. Available options are: -#### `hex-long` +- [`hex-long`](#hex-long) +- [`hex-long-with-alpha`](#hex-long-with-alpha) +- [`hex-short`](#hex-short) +- [`hex-short-with-alpha`](#hex-short-with-alpha) +- [`basic-named-colors`](#basic-named-colors) +- [`extended-named-colors`](#extended-named-colors) +- [`system-colors`](#system-colors) +- [`keywords`](#keywords) +- [`rgb`](#rgb) +- [`rgba`](#rgba) +- [`hsl`](#hsl) +- [`hsla`](#hsla) + +#### `hex-long` Examples: `#0f0f0f`, `#0F0F0F` From 28ef0801d83550f5f13cdd7f56b8730e2854c26c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Thu, 11 Jul 2024 17:36:45 +0100 Subject: [PATCH 5/8] chore: initialize formats --- src/Rule/CssColor.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Rule/CssColor.php b/src/Rule/CssColor.php index a96af29..ac2e1bf 100644 --- a/src/Rule/CssColor.php +++ b/src/Rule/CssColor.php @@ -69,7 +69,7 @@ class CssColor extends AbstractRule implements RuleInterface self::FORMAT_HSLA => self::PATTERN_HSLA ]; - private array $formats; + private array $formats = self::COLOR_FORMATS; private string $message = 'The {{ name }} value is not a valid CSS color.'; public function __construct( @@ -77,7 +77,7 @@ public function __construct( ?string $message = null ) { - $this->formats = $formats ?? self::COLOR_FORMATS; + $this->formats = $formats ?? $this->formats; $this->message = $message ?? $this->message; } From be82cf0d198e81ad57ee33e67acf23bd80fc04cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Fri, 12 Jul 2024 15:55:42 +0100 Subject: [PATCH 6/8] feat: added blank rule --- src/ChainedValidatorInterface.php | 5 +++ src/Exception/BlankException.php | 5 +++ src/Rule/Blank.php | 38 +++++++++++++++++++++ src/Rule/NotBlank.php | 11 ++---- src/StaticValidatorInterface.php | 5 +++ tests/BlankTest.php | 56 +++++++++++++++++++++++++++++++ 6 files changed, 111 insertions(+), 9 deletions(-) create mode 100644 src/Exception/BlankException.php create mode 100644 src/Rule/Blank.php create mode 100644 tests/BlankTest.php diff --git a/src/ChainedValidatorInterface.php b/src/ChainedValidatorInterface.php index 23b2116..c7b286b 100644 --- a/src/ChainedValidatorInterface.php +++ b/src/ChainedValidatorInterface.php @@ -7,6 +7,11 @@ interface ChainedValidatorInterface { + public function blank( + ?callable $normalizer = null, + ?string $message = null + ): ChainedValidatorInterface&Validator; + public function choice( array $constraints, bool $multiple = false, diff --git a/src/Exception/BlankException.php b/src/Exception/BlankException.php new file mode 100644 index 0000000..0a238bf --- /dev/null +++ b/src/Exception/BlankException.php @@ -0,0 +1,5 @@ +normalizer = $normalizer; + $this->message = $message ?? $this->message; + } + + public function assert(mixed $value, ?string $name = null): void + { + if ($this->normalizer !== null) { + $value = ($this->normalizer)($value); + } + + if ($value !== null && $value !== false && $value !== '' && $value !== []) { + throw new BlankException( + message: $this->message, + parameters: [ + 'value' => $value, + 'name' => $name + ] + ); + } + } +} \ No newline at end of file diff --git a/src/Rule/NotBlank.php b/src/Rule/NotBlank.php index c5e2b3d..112965b 100644 --- a/src/Rule/NotBlank.php +++ b/src/Rule/NotBlank.php @@ -3,6 +3,7 @@ namespace ProgrammatorDev\Validator\Rule; use ProgrammatorDev\Validator\Exception\NotBlankException; +use ProgrammatorDev\Validator\Validator; class NotBlank extends AbstractRule implements RuleInterface { @@ -19,17 +20,9 @@ public function __construct( $this->message = $message ?? $this->message; } - /** - * @throws NotBlankException - */ public function assert(mixed $value, ?string $name = null): void { - if ($this->normalizer !== null) { - $value = ($this->normalizer)($value); - } - - // Do not allow null, false, [] and '' - if ($value === false || (empty($value) && $value != '0')) { + if (Validator::blank(normalizer: $this->normalizer)->validate($value) === true) { throw new NotBlankException( message: $this->message, parameters: [ diff --git a/src/StaticValidatorInterface.php b/src/StaticValidatorInterface.php index ca9c931..691032e 100644 --- a/src/StaticValidatorInterface.php +++ b/src/StaticValidatorInterface.php @@ -6,6 +6,11 @@ interface StaticValidatorInterface { + public static function blank( + ?callable $normalizer = null, + ?string $message = null + ): ChainedValidatorInterface&Validator; + public static function choice( array $constraints, bool $multiple = false, diff --git a/tests/BlankTest.php b/tests/BlankTest.php new file mode 100644 index 0000000..998cbfc --- /dev/null +++ b/tests/BlankTest.php @@ -0,0 +1,56 @@ + [new Blank(), true, $exception, $message]; + + yield 'string' => [new Blank(), 'string', $exception, $message]; + yield 'whitespace string' => [new Blank(), ' ', $exception, $message]; + yield 'zero string' => [new Blank(), '0', $exception, $message]; + + yield 'array' => [new Blank(), ['string'], $exception, $message]; + yield 'blank string array' => [new Blank(), [''], $exception, $message]; + yield 'whitespace array' => [new Blank(), [' '], $exception, $message]; + yield 'zero array' => [new Blank(), [0], $exception, $message]; + + yield 'number' => [new Blank(), 10, $exception, $message]; + yield 'zero number' => [new Blank(), 0, $exception, $message]; + } + + public static function provideRuleSuccessConditionData(): \Generator + { + yield 'null' => [new Blank(), null]; + yield 'false' => [new Blank(), false]; + yield 'blank string' => [new Blank(), '']; + yield 'blank array' => [new Blank(), []]; + + yield 'normalizer whitespace' => [new Blank(normalizer: 'trim'), ' ']; + yield 'normalizer whitespace function' => [new Blank(normalizer: fn($value) => trim($value)), ' ']; + } + + public static function provideRuleMessageOptionData(): \Generator + { + yield 'message' => [ + new Blank(message: '{{ name }} | {{ value }}'), + 'string', + 'test | "string"' + ]; + } +} \ No newline at end of file From 770c1d939d4f0ef2040cea41203493e974eb3414 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Fri, 12 Jul 2024 16:13:10 +0100 Subject: [PATCH 7/8] docs: added blank documentation --- README.md | 8 +----- docs/01-get-started.md | 8 +----- docs/03-rules.md | 1 + docs/03-rules_blank.md | 56 ++++++++++++++++++++++++++++++++++++++ docs/03-rules_not-blank.md | 7 ++--- 5 files changed, 62 insertions(+), 18 deletions(-) create mode 100644 docs/03-rules_blank.md diff --git a/README.md b/README.md index 48b1c96..85fb275 100644 --- a/README.md +++ b/README.md @@ -12,18 +12,12 @@ PHP validator with expressive error messages. ## Installation -You can install the library via [Composer](https://getcomposer.org/): +Install the library via [Composer](https://getcomposer.org/): ```bash composer require programmatordev/yet-another-php-validator ``` -To use the library, use Composer's [autoload](https://getcomposer.org/doc/01-basic-usage.md#autoloading): - -```php -require_once 'vendor/autoload.php'; -``` - ## Basic Usage Simple usage looks like: diff --git a/docs/01-get-started.md b/docs/01-get-started.md index e7bc45d..9304c18 100644 --- a/docs/01-get-started.md +++ b/docs/01-get-started.md @@ -10,18 +10,12 @@ ## Installation -You can install the library via [Composer](https://getcomposer.org/): +Install the library via [Composer](https://getcomposer.org/): ```bash composer require programmatordev/yet-another-php-validator ``` -To use the library, use Composer's [autoload](https://getcomposer.org/doc/01-basic-usage.md#autoloading): - -```php -require_once 'vendor/autoload.php'; -``` - ## Basic Usage Simple usage looks like: diff --git a/docs/03-rules.md b/docs/03-rules.md index c168671..58474c3 100644 --- a/docs/03-rules.md +++ b/docs/03-rules.md @@ -10,6 +10,7 @@ ## Basic Rules +- [Blank](03-rules_blank.md) - [Count](03-rules_count.md) - [NotBlank](03-rules_not-blank.md) - [Type](03-rules_type.md) diff --git a/docs/03-rules_blank.md b/docs/03-rules_blank.md new file mode 100644 index 0000000..00b17d8 --- /dev/null +++ b/docs/03-rules_blank.md @@ -0,0 +1,56 @@ +# Blank + +Validates that a value is equal to an empty string, empty array, `false` or `null`. + +Check the [NotBlank](03-rules_not-blank.md) rule for the opposite validation. + +```php +Blank( + ?callable $normalizer = null, + ?string $message = null +); +``` + +## Basic Usage + +Bellow are the *only* cases where the rule will succeed by default, +everything else is considered invalid (you may want to check the [`normalizer`](#normalizer) option for a different behaviour): + +```php +Validator::blank()->validate(''); // true +Validator::blank()->validate([]); // true +Validator::blank()->validate(false); // true +Validator::blank()->validate(null); // true +``` + +## Options + +### `normalizer` + +type: `?callable` default: `null` + +Allows to define a `callable` that will be applied to the value before checking if it is valid. + +For example, use `trim`, or pass your own function, to not allow a string with whitespaces only: + +```php +Validator::blank(normalizer: 'trim')->validate(' '); // true +Validator::blank(normalizer: fn($value) => trim($value))->validate(' '); // true +``` + +### `message` + +type: `?string` default: `The {{ name }} value should be blank, {{ value }} given.` + +Message that will be shown if the value is not blank. + +The following parameters are available: + +| Parameter | Description | +|---------------|---------------------------| +| `{{ value }}` | The current invalid value | +| `{{ name }}` | Name of the invalid value | + +## Changelog + +- `1.2.0` Created \ No newline at end of file diff --git a/docs/03-rules_not-blank.md b/docs/03-rules_not-blank.md index 1e30c55..15e7bb8 100644 --- a/docs/03-rules_not-blank.md +++ b/docs/03-rules_not-blank.md @@ -2,6 +2,8 @@ Validates that a value is not equal to a blank string, blank array, `false` or `null`. +Check the [Blank](03-rules_blank.md) rule for the opposite validation. + ```php NotBlank( ?callable $normalizer = null, @@ -25,17 +27,14 @@ Validator::notBlank()->validate(null); // false ### `normalizer` -type: `callable` default: `null` +type: `?callable` default: `null` Allows to define a `callable` that will be applied to the value before checking if it is valid. For example, use `trim`, or pass your own function, to not allow a string with whitespaces only: ```php -// Existing PHP callables Validator::notBlank(normalizer: 'trim')->validate(' '); // false - -// Function Validator::notBlank(normalizer: fn($value) => trim($value))->validate(' '); // false ``` From 41a2a3222ac7c39adbc3e2ff25d9cfd01ff1e76e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Fri, 12 Jul 2024 16:17:06 +0100 Subject: [PATCH 8/8] docs: few changes for coherence --- docs/03-rules_blank.md | 2 +- docs/03-rules_not-blank.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/03-rules_blank.md b/docs/03-rules_blank.md index 00b17d8..0635b6a 100644 --- a/docs/03-rules_blank.md +++ b/docs/03-rules_blank.md @@ -31,7 +31,7 @@ type: `?callable` default: `null` Allows to define a `callable` that will be applied to the value before checking if it is valid. -For example, use `trim`, or pass your own function, to not allow a string with whitespaces only: +For example, use `trim`, or pass your own function, to allow a string with whitespaces only: ```php Validator::blank(normalizer: 'trim')->validate(' '); // true diff --git a/docs/03-rules_not-blank.md b/docs/03-rules_not-blank.md index 15e7bb8..9278282 100644 --- a/docs/03-rules_not-blank.md +++ b/docs/03-rules_not-blank.md @@ -1,6 +1,6 @@ # NotBlank -Validates that a value is not equal to a blank string, blank array, `false` or `null`. +Validates that a value is not equal to an empty string, empty array, `false` or `null`. Check the [Blank](03-rules_blank.md) rule for the opposite validation.