melhorias e adição de novas funcionalidades

Author: brunocontecooper

README.md

@@ -9,6 +9,21 @@ A complete library, with PSR standard and guarantee of all methods unit tested b
 - Validate Data in General
 - Validate Upload Files
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Data Validation](#data-validation-example)
+- [File Upload Validation](#validating-files-upload)
+- [Validation Types](#validation-types-validators)
+- [Custom Messages](#defining-custom-message)
+- [Formatting](#formatting-examples)
+- [Comparisons](#comparisons-examples)
+- [Validations Methods](#validations-in-the-form-of-methods)
+- [Generation Utilities](#generation-utilities)
+- [Arrays Manipulation](#manipulate-arrays)
+- [Utilities](#utilities)
+- [CI/CD Coverage](#check-the-minimum-coverage-of-cicd-unit-tests-using-phpunit)
+
 ## Installation
 
 Install using Composer:
@@ -20,7 +35,7 @@ composer require brunoconte3/dev-utils
 Or add to your `composer.json`:
 
 ```json
-"brunoconte3/dev-utils": "2.12.0"
+"brunoconte3/dev-utils": "2.13.0"
 ```
 
 ## Data Validation Example
@@ -460,14 +475,55 @@ ValidateString::minWords('Bruno Conte', 2) //Return boolean
 ValidateString::maxWords('Bruno Conte', 2) //Return boolean
 ```
 
+## Generation Utilities
+
+### UUID v7 - Generate and Validate
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+
+use DevUtils\Uuid;
+
+// Generate UUID v7 (timestamp-based, sortable, unique)
+$uuid = Uuid::generate(); // ==> 01890f87-4f0b-7f6b-8b1d-9f4f9d7c3b5a
+
+// Validate any UUID version (v1 to v8)
+Uuid::isValid('550e8400-e29b-41d4-a716-446655440000'); // ==> true
+
+// Validate specific version
+Uuid::isValid('01890f87-4f0b-7f6b-8b1d-9f4f9d7c3b5a', 7); // ==> true
+
+```
+
+### Password Generation
+
+```php
+<?php
+
+use DevUtils\Utility;
+
+/*
+Generate secure passwords
+int $size       ==> Number of characters (Required)
+bool $uppercase ==> Include uppercase letters (default: true)
+bool $lowercase ==> Include lowercase letters (default: true)
+bool $numbers   ==> Include numbers (default: true)
+bool $symbols   ==> Include symbols (default: true)
+*/
+Utility::generatePassword(10); // ==> aB3$xY9!zK
+Utility::generatePassword(16, true, true, true, false); // Without symbols
+```
+
 ## Manipulate Arrays
 
 ```php
 <?php
 
 require 'vendor/autoload.php';
 
-use DevUtils\Array;
+use DevUtils\Arrays;
 
 $array = ['primeiro' => 15, 'segundo' => 25];
 var_dump(Arrays::searchKey($array, 'primeiro'));   // Search for key in array, and Return position ==> returns 0
@@ -533,16 +589,6 @@ use DevUtils\Utility;
 
 Utility::captureClientIp(); // Return user IP, capture per layer available, eg 201.200.25.40
 
-/*
-Return an automatically generated password, there are 5 parameters, only the first one is mandatory
-int $size       ==> Number of characters in the password (Required)
-bool $uppercase ==> If there will be capital letters
-bool $lowercase ==> If there will be lowercase letters
-bool $numbers   ==> if there will be numbers
-bool $symbols   ==> if there will be symbols
-*/
-Utility::generatePassword(10);
-
 /*
 * @return string -> Full URL string
 * @param string $host -> system domain

src/Arrays.php

@@ -6,6 +6,8 @@
 
 class Arrays
 {
+    private const XML_ATTR_KEY = '@attr';
+
     public static function searchKey(array $array, string $key): ?int
     {
         $position = array_search($key, array_keys($array), true);
@@ -92,12 +94,12 @@ public static function findIndexByValue(array $array, string | int | bool $searc
     public static function convertArrayToXml(array $array, \SimpleXMLElement &$xml): void
     {
         foreach ($array as $key => $value) {
-            if (is_numeric($key) && is_array($value) && isset($value['@attr'])) {
-                $key = $value['@attr'];
+            if (is_numeric($key) && is_array($value) && isset($value[self::XML_ATTR_KEY])) {
+                $key = $value[self::XML_ATTR_KEY];
             }
 
             if (is_array($value)) {
-                unset($value['@attr']);
+                unset($value[self::XML_ATTR_KEY]);
                 $subnode = $xml->addChild((string) $key);
                 self::convertArrayToXml($value, $subnode);
                 continue;

src/Uuid.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DevUtils;
+
+class Uuid
+{
+    private static function formatUuid(string $hex): string
+    {
+        return sprintf(
+            '%s-%s-%s-%s-%s',
+            substr($hex, 0, 8),
+            substr($hex, 8, 4),
+            substr($hex, 12, 4),
+            substr($hex, 16, 4),
+            substr($hex, 20, 12)
+        );
+    }
+
+    private static function setVersionAndVariant(string $hex, int $version): string
+    {
+        $timeHi = hexdec(substr($hex, 12, 4));
+        $timeHi = ($timeHi & 0x0fff) | ($version << 12);
+
+        $clockSeq = hexdec(substr($hex, 16, 4));
+        $clockSeq = ($clockSeq & 0x3fff) | 0x8000;
+
+        return substr($hex, 0, 12)
+            . str_pad(dechex($timeHi), 4, '0', STR_PAD_LEFT)
+            . str_pad(dechex($clockSeq), 4, '0', STR_PAD_LEFT)
+            . substr($hex, 20);
+    }
+
+    private static function validateFormat(string $uuid): bool
+    {
+        return preg_match(
+            '/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i',
+            $uuid
+        ) === 1;
+    }
+
+    private static function extractVersion(string $uuid): ?int
+    {
+        if (!self::validateFormat($uuid)) {
+            return null;
+        }
+
+        $versionHex = substr($uuid, 14, 1);
+        $version = (int) hexdec($versionHex);
+
+        return ($version >= 1 && $version <= 8) ? $version : null;
+    }
+
+    public static function generate(): string
+    {
+        $timestamp = (int) (microtime(true) * 1000);
+        $timestampHex = str_pad(dechex($timestamp), 12, '0', STR_PAD_LEFT);
+
+        $randomBytes = random_bytes(10);
+        $randomHex = bin2hex($randomBytes);
+
+        $hex = $timestampHex . $randomHex;
+        $hex = self::setVersionAndVariant($hex, 7);
+
+        return self::formatUuid($hex);
+    }
+
+    public static function isValid(string $uuid, ?int $version = null): bool
+    {
+        $detectedVersion = self::extractVersion($uuid);
+
+        if ($detectedVersion === null) {
+            return false;
+        }
+
+        if ($version === null) {
+            return in_array($detectedVersion, [1, 2, 3, 4, 5, 6, 7, 8], true);
+        }
+
+        return $detectedVersion === $version;
+    }
+}

src/ValidateUuid.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DevUtils;
+
+class ValidateUuid
+{
+    private const UUID_V4_V7_REGEX = '/^[0-9a-f]{8}-[0-9a-f]{4}-[47][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i';
+
+    private static function matchesUuidV4OrV7(string $uuid): bool
+    {
+        return preg_match(self::UUID_V4_V7_REGEX, $uuid) === 1;
+    }
+
+    public static function isValid(string $uuid): bool
+    {
+        if (empty($uuid)) {
+            return false;
+        }
+
+        return self::matchesUuidV4OrV7($uuid);
+    }
+}

tests/UnitArrayTest.php

@@ -11,6 +11,8 @@
 
 class UnitArrayTest extends TestCase
 {
+    private const VEGETABLE_RUCULA = 'Rúcula';
+
     private array $fruitArray;
     private array $simpleArray;
 
@@ -34,7 +36,7 @@ private function assertXmlFrutas(SimpleXMLElement $xml): void
 
     private function assertXmlVerduras(SimpleXMLElement $xml): void
     {
-        self::assertSame('Rúcula', (string) $xml->verduras->verdura_1);
+        self::assertSame(self::VEGETABLE_RUCULA, (string) $xml->verduras->verdura_1);
         self::assertSame('Acelga', (string) $xml->verduras->verdura_2);
         self::assertSame('Alface', (string) $xml->verduras->verdura_3);
         self::assertCount(3, $xml->verduras->children());
@@ -49,7 +51,7 @@ protected function setUp(): void
                 'fruta_3' => 'fruta',
                 'fruta_4' => 'Uva',
             ],
-            'verduras' => ['verdura_1' => 'Rúcula', 'verdura_2' => 'Acelga', 'verdura_3' => 'Alface'],
+            'verduras' => ['verdura_1' => self::VEGETABLE_RUCULA, 'verdura_2' => 'Acelga', 'verdura_3' => 'Alface'],
             'legume' => 'Tomate',
         ];
 
@@ -82,7 +84,7 @@ public function testFindValueByKey(): void
 
     public function testFindIndexByValue(): void
     {
-        self::assertIsArray(Arrays::findIndexByValue($this->fruitArray, 'Rúcula'));
+        self::assertIsArray(Arrays::findIndexByValue($this->fruitArray, self::VEGETABLE_RUCULA));
     }
 
     public function testConvertArrayToXml(): void
@@ -107,13 +109,13 @@ public function testConvertArrayToXml(): void
     public function testConvertJsonIndexToArray(): void
     {
         $array = $this->fruitArray;
-        $array['verduras'] = '{"verdura_1": "Rúcula", "verdura_2": "Acelga", "verdura_3": "Alface"}';
+        $array['verduras'] = '{"verdura_1": "' . self::VEGETABLE_RUCULA . '", "verdura_2": "Acelga", "verdura_3": "Alface"}';
 
         Arrays::convertJsonIndexToArray($array);
 
         self::assertIsArray($array);
         self::assertIsArray($array['verduras']);
-        self::assertSame('Rúcula', $array['verduras']['verdura_1']);
+        self::assertSame(self::VEGETABLE_RUCULA, $array['verduras']['verdura_1']);
     }
 
     public function testCheckExistsIndexArrayRecursive(): void