Merge pull request #70 from programmatordev/1.x

1.2.0

.ddev/config.yaml

@@ -13,20 +13,22 @@ 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:
 
 # name: <projectname> # Name of the project, automatically provides
 #   http://projectname.ddev.site and https://projectname.ddev.site
 
-# type: <projecttype>  # 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: <projecttype>  # 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> # 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: <dbtype> # mysql, mariadb, postgres
-#   version: <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: <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>  # 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:

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:

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:

docs/03-rules.md

@@ -10,12 +10,14 @@
 
 ## Basic Rules
 
+- [Blank](03-rules_blank.md)
 - [Count](03-rules_count.md)
 - [NotBlank](03-rules_not-blank.md)
 - [Type](03-rules_type.md)
 
 ## String Rules
 
+- [CssColor](03-rules_css-color.md)
 - [Email](03-rules_email.md)
 - [Length](03-rules_length.md)
 - [PasswordStrength](03-rules_password-strength.md)

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 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

docs/03-rules_css-color.md

@@ -0,0 +1,126 @@
+# 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`](#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`
+
+#### `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

docs/03-rules_not-blank.md

@@ -1,6 +1,8 @@
 # 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.
 
 ```php
 NotBlank(
@@ -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
 ```
 

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,
@@ -39,6 +44,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

src/Exception/BlankException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Exception;
+
+class BlankException extends ValidationException {}

src/Exception/CssColorException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Exception;
+
+class CssColorException extends ValidationException {}