fix(string): validate only URL-safe characters in Base64Variant::UrlSafe

- Restrict UrlSafe regex to [A-Za-z0-9\-_] instead of accepting standard +/ chars
- Add test asserting standard Base64 is rejected in UrlSafe mode
- Update string-validation guide, enum docblock, and changelog
- Remove resolved bug from ISSUES.md and renumber sections

Author: lemmon

CHANGELOG.md

@@ -13,6 +13,7 @@ All notable changes to this project will be documented in this file.
 - `satisfies()`, `satisfiesAll()`, `satisfiesAny()`, `satisfiesNone()`, and `ArrayValidator::contains()` now clone any `FieldValidator` operand at capture time and rebuild those operands when the outer validator is cloned, so later mutations or clone-local pipeline state do not leak across validator instances
 - `FieldValidator::tryValidate()` now resets transient type-tracking before and after every validation run, so validators that use `transform()`/`pipe()` remain repeatable across multiple calls and clones do not inherit stale runtime state
 - `default()` no longer deep-copies object values; object defaults are returned as-is (shared by handle). Use `defaultUsing()` when each validation run needs a fresh object instance
+- `Base64Variant::UrlSafe` now strictly validates URL-safe characters (`-_`) only; previously it was identical to `Base64Variant::Any` (accepted both standard and URL-safe)
 
 ### Added
 

ISSUES.md

@@ -0,0 +1,37 @@
+# Project Issues and Suggestions
+
+This document tracks identified bugs, architectural inconsistencies, and potential improvements for the Lemmon Validator library.
+
+## 1. Architectural Suggestions
+
+### IntValidator Coercion Precision
+
+`IntValidator` uses `is_numeric()` during coercion, which means a string like `"1.5"` is successfully coerced (truncated) to `1`. While "form-safe," this truncation can hide data precision issues. Consider providing a way to enforce strict integer strings or documenting this behavior clearly.
+
+### UnitEnum Support
+
+The `enum()` validator currently only supports `BackedEnum`. Adding support for basic `UnitEnum` (cases only) would increase utility for projects that do not use backed values for all enums.
+
+### Mixed Type Coercion in Combinators
+
+The static combinators `Validator::anyOf()`, `allOf()`, and `not()` return a "mixed" validator that does not support top-level coercion. Users expecting coercion must enable it on individual sub-validators.
+
+---
+
+## 2. Feature Suggestions
+
+### Built-in String Sanitizers
+
+Common operations like `trim()`, `lowercase()`, and `uppercase()` are currently implemented via `pipe('trim')`. Adding them as first-class methods (e.g., `->trim()`) would improve discoverability and follow the fluent API pattern of other validators.
+
+### Explicit nullable() Method
+
+Although fields are optional (allow null) by default, adding an explicit `->nullable()` method (as an alias for default behavior) can improve code readability and intent, especially when contrasted with `->required()`.
+
+### Instance Validation
+
+Add a validator for checking object instances (e.g., `Validator::isInstance(MyClass::class)`).
+
+### Error Message Templates
+
+Implement a more flexible way to configure global error message templates for core constraints (like `minLength` or `between`) to support localization and consistent branding across applications.

docs/guides/string-validation.md

@@ -183,10 +183,10 @@ $base64 = $standardValidator->validate('SGVsbG8gV29ybGQ='); // "Hello World"
 $base64 = $standardValidator->validate('dGVzdA=='); // "test"
 $base64 = $standardValidator->validate('YWJj'); // "abc" (no padding)
 
-// URL-safe Base64 (uses -, _, and accepts both variants)
+// URL-safe Base64 (uses - and _ instead of + and /, padding optional)
 $urlSafeValidator = Validator::isString()->base64(Base64Variant::UrlSafe);
-$base64 = $urlSafeValidator->validate('SGVsbG8gV29ybGQ'); // URL-safe format
-$base64 = $urlSafeValidator->validate('SGVsbG8gV29ybGQ='); // Standard format also accepted
+$base64 = $urlSafeValidator->validate('SGVsbG8gV29ybGQ'); // URL-safe format (no padding)
+$base64 = $urlSafeValidator->validate('PDw_Pz4-'); // URL-safe chars - and _
 
 // Any variant (accepts both standard and URL-safe)
 $anyValidator = Validator::isString()->base64(Base64Variant::Any);

src/Lemmon/Validator/Base64Variant.php

@@ -16,8 +16,7 @@ enum Base64Variant: string
     case Standard = 'standard';
 
     /**
-     * URL-safe Base64 encoding (uses -, _, and no padding).
-     * URL-safe parsers typically accept both standard and URL-safe variants.
+     * URL-safe Base64 encoding (uses - and _ instead of + and /, padding optional).
      */
     case UrlSafe = 'urlsafe';
 

src/Lemmon/Validator/StringValidator.php

@@ -222,11 +222,7 @@ public function base64(
                 Base64Variant::Standard => preg_match('/^[A-Za-z0-9+\/]*={0,2}$/', $value) === 1
                     && ($decoded = base64_decode($value, true)) !== false
                     && base64_encode($decoded) === $value,
-                Base64Variant::UrlSafe => preg_match('/^[A-Za-z0-9+\/]*={0,2}$/', $value) === 1 // Try standard Base64 first // URL-safe parsers accept both standard and URL-safe variants
-                && ($decoded = base64_decode($value, true)) !== false
-                && base64_encode($decoded) === $value
-                    // Or try URL-safe Base64
-                    || preg_match('/^[A-Za-z0-9\-_]*={0,2}$/', $value) === 1
+                Base64Variant::UrlSafe => preg_match('/^[A-Za-z0-9\-_]*={0,2}$/', $value) === 1
                     && base64_decode(strtr($value, '-_', '+/'), true) !== false,
                 Base64Variant::Any => preg_match('/^[A-Za-z0-9+\/]*={0,2}$/', $value) === 1 // Try standard Base64 first
                 && ($decoded = base64_decode($value, true)) !== false

tests/StringValidatorTest.php

@@ -228,19 +228,20 @@
 it('should validate URL-safe base64 strings', function () {
     $urlSafeValidator = Validator::isString()->base64(Base64Variant::UrlSafe);
 
-    // Valid URL-safe base64 strings (no padding, uses - and _)
     expect($urlSafeValidator->validate('SGVsbG8gV29ybGQ'))->toBe('SGVsbG8gV29ybGQ'); // "Hello World" (no padding)
     expect($urlSafeValidator->validate('dGVzdA'))->toBe('dGVzdA'); // "test" (no padding)
     expect($urlSafeValidator->validate('YWJj'))->toBe('YWJj'); // "abc"
-
-    // URL-safe parsers accept both standard and URL-safe variants
-    // So standard Base64 with + and / should also be accepted
-    expect($urlSafeValidator->validate('SGVsbG8gV29ybGQ='))->toBe('SGVsbG8gV29ybGQ='); // Standard Base64 accepted
+    expect($urlSafeValidator->validate('PDw_Pz4-'))->toBe('PDw_Pz4-'); // contains - and _ chars
 
     // Invalid: contains invalid characters
     $urlSafeValidator->validate('SGVsbG8gV29ybGQ!');
 })->throws(ValidationException::class, 'Value must be a valid URL-safe Base64 encoded string');
 
+it('should reject standard base64 characters in URL-safe mode', function () {
+    $urlSafeValidator = Validator::isString()->base64(Base64Variant::UrlSafe);
+    $urlSafeValidator->validate('PDw/Pz4+'); // standard Base64 with + and /
+})->throws(ValidationException::class, 'Value must be a valid URL-safe Base64 encoded string');
+
 it('should validate base64 with Any variant', function () {
     $anyValidator = Validator::isString()->base64(Base64Variant::Any);