Merge pull request #14 from KaririCode-Framework/develop

walmir-silva · web-flow · commit a9949d32fe3b · 2026-03-05T14:18:20.000-03:00
Develop
diff --git a/.gitignore b/.gitignore
@@ -64,6 +64,8 @@ tests/lista_de_arquivos_test.php
 lista_de_arquivos.txt
 lista_de_arquivos_tests.txt
 add_static_to_providers.php
+patch_docblocks.php
+patch_docblocks.py
 
 # KaririCode Devkit — generated configs and build artifacts
 .kcode/
diff --git a/src/Rule/Brazilian/FormatCepRule.php b/src/Rule/Brazilian/FormatCepRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Formats a CEP: 63100000 → 63100-000.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class FormatCepRule implements SanitizationRule
 {
diff --git a/src/Rule/Brazilian/FormatCnpjRule.php b/src/Rule/Brazilian/FormatCnpjRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Formats a CNPJ number: 11222333000181 → 11.222.333/0001-81.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class FormatCnpjRule implements SanitizationRule
 {
diff --git a/src/Rule/Brazilian/FormatCpfRule.php b/src/Rule/Brazilian/FormatCpfRule.php
@@ -12,6 +12,10 @@
  *
  * If the input is already formatted, normalizes it.
  * If the digit count is not 11, returns as-is.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class FormatCpfRule implements SanitizationRule
 {
diff --git a/src/Rule/Date/NormalizeDateRule.php b/src/Rule/Date/NormalizeDateRule.php
@@ -11,6 +11,10 @@
  * Normalizes a date string to a standard format.
  *
  * Parameters: from (string, default 'd/m/Y'), to (string, default 'Y-m-d').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class NormalizeDateRule implements SanitizationRule
 {
diff --git a/src/Rule/Date/TimestampToDateRule.php b/src/Rule/Date/TimestampToDateRule.php
@@ -11,6 +11,10 @@
  * Converts a Unix timestamp to a formatted date string.
  *
  * Parameters: format (string, default 'Y-m-d H:i:s'), timezone (string, default 'UTC').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class TimestampToDateRule implements SanitizationRule
 {
diff --git a/src/Rule/Filter/AlphaOnlyRule.php b/src/Rule/Filter/AlphaOnlyRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Strips all non-letter characters (Unicode-aware via \pL).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class AlphaOnlyRule implements SanitizationRule
 {
diff --git a/src/Rule/Filter/AlphanumericOnlyRule.php b/src/Rule/Filter/AlphanumericOnlyRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Strips all non-alphanumeric characters (Unicode-aware).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class AlphanumericOnlyRule implements SanitizationRule
 {
diff --git a/src/Rule/Filter/DigitsOnlyRule.php b/src/Rule/Filter/DigitsOnlyRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Strips all non-digit characters from a string.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class DigitsOnlyRule implements SanitizationRule
 {
diff --git a/src/Rule/Filter/EmailFilterRule.php b/src/Rule/Filter/EmailFilterRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Sanitizes an email address: trims, lowercases, removes illegal chars.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class EmailFilterRule implements SanitizationRule
 {
diff --git a/src/Rule/Html/HtmlDecodeRule.php b/src/Rule/Html/HtmlDecodeRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Decodes HTML entities back to characters.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class HtmlDecodeRule implements SanitizationRule
 {
diff --git a/src/Rule/Html/HtmlEncodeRule.php b/src/Rule/Html/HtmlEncodeRule.php
@@ -11,6 +11,10 @@
  * Encodes HTML special characters for XSS prevention.
  *
  * Parameters: flags (int, default ENT_QUOTES|ENT_SUBSTITUTE), encoding (string, default 'UTF-8').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class HtmlEncodeRule implements SanitizationRule
 {
diff --git a/src/Rule/Html/HtmlPurifyRule.php b/src/Rule/Html/HtmlPurifyRule.php
@@ -12,6 +12,10 @@
  *
  * Applies: strip_tags → html_entity_decode → trim.
  * Parameters: allowed (string, tags to preserve).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class HtmlPurifyRule implements SanitizationRule
 {
diff --git a/src/Rule/Html/StripTagsRule.php b/src/Rule/Html/StripTagsRule.php
@@ -11,6 +11,10 @@
  * Strips HTML/PHP tags from a string.
  *
  * Parameters: allowed (string, e.g. '<b><i><a>').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class StripTagsRule implements SanitizationRule
 {
diff --git a/src/Rule/Html/UrlEncodeRule.php b/src/Rule/Html/UrlEncodeRule.php
@@ -11,6 +11,10 @@
  * URL-encodes a string value.
  *
  * Parameters: raw (bool, default false). If true, uses rawurlencode (RFC 3986).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class UrlEncodeRule implements SanitizationRule
 {
diff --git a/src/Rule/Numeric/ClampRule.php b/src/Rule/Numeric/ClampRule.php
@@ -11,6 +11,10 @@
  * Clamps a numeric value to [min, max] bounds.
  *
  * Parameters: min (int|float), max (int|float).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class ClampRule implements SanitizationRule
 {
diff --git a/src/Rule/Numeric/RoundRule.php b/src/Rule/Numeric/RoundRule.php
@@ -11,6 +11,10 @@
  * Rounds a numeric value to specified decimal places.
  *
  * Parameters: precision (int, default 2), mode ('round'|'ceil'|'floor', default 'round').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class RoundRule implements SanitizationRule
 {
diff --git a/src/Rule/Numeric/ToFloatRule.php b/src/Rule/Numeric/ToFloatRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Casts a value to float. Non-castable values return as-is.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class ToFloatRule implements SanitizationRule
 {
diff --git a/src/Rule/Numeric/ToIntRule.php b/src/Rule/Numeric/ToIntRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Casts a value to integer. Non-castable values return 0.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class ToIntRule implements SanitizationRule
 {
diff --git a/src/Rule/String/CapitalizeRule.php b/src/Rule/String/CapitalizeRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Capitalizes the first letter of each word (mb-safe).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class CapitalizeRule implements SanitizationRule
 {
diff --git a/src/Rule/String/LowerCaseRule.php b/src/Rule/String/LowerCaseRule.php
@@ -7,6 +7,13 @@
 use KaririCode\Sanitizer\Contract\SanitizationContext;
 use KaririCode\Sanitizer\Contract\SanitizationRule;
 
+/**
+ * Converts a string to lowercase (mb-safe, UTF-8).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
+ */
 final readonly class LowerCaseRule implements SanitizationRule
 {
     #[\Override]
diff --git a/src/Rule/String/NormalizeLineEndingsRule.php b/src/Rule/String/NormalizeLineEndingsRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Normalizes line endings to Unix LF.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class NormalizeLineEndingsRule implements SanitizationRule
 {
diff --git a/src/Rule/String/NormalizeWhitespaceRule.php b/src/Rule/String/NormalizeWhitespaceRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Collapses multiple whitespace characters into a single space.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class NormalizeWhitespaceRule implements SanitizationRule
 {
diff --git a/src/Rule/String/PadRule.php b/src/Rule/String/PadRule.php
@@ -11,6 +11,10 @@
  * Pads a string to a given length.
  *
  * Parameters: length (int), pad (string, default ' '), side ('left'|'right'|'both', default 'right').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class PadRule implements SanitizationRule
 {
diff --git a/src/Rule/String/RegexReplaceRule.php b/src/Rule/String/RegexReplaceRule.php
@@ -11,6 +11,10 @@
  * Regex-based search-and-replace.
  *
  * Parameters: pattern (string), replacement (string, default '').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class RegexReplaceRule implements SanitizationRule
 {
diff --git a/src/Rule/String/ReplaceRule.php b/src/Rule/String/ReplaceRule.php
@@ -11,6 +11,10 @@
  * Simple string search-and-replace.
  *
  * Parameters: search (string), replace (string, default '').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class ReplaceRule implements SanitizationRule
 {
diff --git a/src/Rule/String/SlugRule.php b/src/Rule/String/SlugRule.php
@@ -12,6 +12,10 @@
  *
  * Transliterates common accented characters, lowercases,
  * replaces non-alphanumeric with hyphens, collapses multiple hyphens.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class SlugRule implements SanitizationRule
 {
diff --git a/src/Rule/String/StripNonPrintableRule.php b/src/Rule/String/StripNonPrintableRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Removes non-printable control characters (preserves \n, \r, \t).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class StripNonPrintableRule implements SanitizationRule
 {
diff --git a/src/Rule/String/TrimRule.php b/src/Rule/String/TrimRule.php
@@ -7,6 +7,13 @@
 use KaririCode\Sanitizer\Contract\SanitizationContext;
 use KaririCode\Sanitizer\Contract\SanitizationRule;
 
+/**
+ * Trims leading and trailing characters from a string.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
+ */
 final readonly class TrimRule implements SanitizationRule
 {
     #[\Override]
diff --git a/src/Rule/String/TruncateRule.php b/src/Rule/String/TruncateRule.php
@@ -11,6 +11,10 @@
  * Truncates a string to a maximum length.
  *
  * Parameters: max (int, default 255), suffix (string, default '...').
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class TruncateRule implements SanitizationRule
 {
diff --git a/src/Rule/String/UpperCaseRule.php b/src/Rule/String/UpperCaseRule.php
@@ -7,6 +7,13 @@
 use KaririCode\Sanitizer\Contract\SanitizationContext;
 use KaririCode\Sanitizer\Contract\SanitizationRule;
 
+/**
+ * Converts a string to uppercase (mb-safe, UTF-8).
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
+ */
 final readonly class UpperCaseRule implements SanitizationRule
 {
     #[\Override]
diff --git a/src/Rule/Type/ToArrayRule.php b/src/Rule/Type/ToArrayRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Wraps a non-array value into a single-element array.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class ToArrayRule implements SanitizationRule
 {
diff --git a/src/Rule/Type/ToBoolRule.php b/src/Rule/Type/ToBoolRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Casts to boolean. Recognizes '1','true','yes','on' as true, '0','false','no','off' as false.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class ToBoolRule implements SanitizationRule
 {
diff --git a/src/Rule/Type/ToStringRule.php b/src/Rule/Type/ToStringRule.php
@@ -9,6 +9,10 @@
 
 /**
  * Casts scalars to string. Non-scalar values return as-is.
+ *
+ * @author  Walmir Silva <walmir.silva@kariricode.org>
+ *
+ * @since   3.1.0 ARFA 1.3
  */
 final readonly class ToStringRule implements SanitizationRule
 {

Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,10 @@`
`12`	`12`	`*`
`13`	`13`	`* If the input is already formatted, normalizes it.`
`14`	`14`	`* If the digit count is not 11, returns as-is.`
	`15`	`+ *`
	`16`	`+ * @author Walmir Silva <walmir.silva@kariricode.org>`
	`17`	`+ *`
	`18`	`+ * @since 3.1.0 ARFA 1.3`
`15`	`19`	`*/`
`16`	`20`	`final readonly class FormatCpfRule implements SanitizationRule`
`17`	`21`	`{`
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,10 @@`
`11`	`11`	`* Normalizes a date string to a standard format.`
`12`	`12`	`*`
`13`	`13`	`* Parameters: from (string, default 'd/m/Y'), to (string, default 'Y-m-d').`
	`14`	`+ *`
	`15`	`+ * @author Walmir Silva <walmir.silva@kariricode.org>`
	`16`	`+ *`
	`17`	`+ * @since 3.1.0 ARFA 1.3`
`14`	`18`	`*/`
`15`	`19`	`final readonly class NormalizeDateRule implements SanitizationRule`
`16`	`20`	`{`