Merge pull request #9 from aleho/main

Modernize code

README.md

@@ -36,9 +36,10 @@ use AltchaOrg\Altcha\Altcha;
 $hmacKey = 'secret hmac key';
 
 // Create a new challenge
-$options = new ChallengeOptions([
-    'hmacKey'   => $hmacKey,
-    'maxNumber' => 50000, // the maximum random number
+$options = new ChallengeOptions(
+    $hmacKey,
+    ChallengeOptions::DEFAULT_ALGORITHM,
+    50000, // the maximum random number
 ]);
 
 $challenge = Altcha::createChallenge($options);
@@ -65,46 +66,37 @@ if ($ok) {
 
 ## API
 
-### `Altcha::createChallenge(array $options): array`
+### `Altcha::createChallenge(ChallengeOptions $options): Challenge`
 
 Creates a new challenge for ALTCHA.
 
-**Parameters:**
+**Returns:** `Challenge`
 
-- `options array`:
-  - `algorithm string`: Hashing algorithm to use (`SHA-1`, `SHA-256`, `SHA-512`, default: `SHA-256`).
-  - `maxNumber int`: Maximum number for the random number generator (default: 1,000,000).
-  - `saltLength int`: Length of the random salt (default: 12 bytes).
-  - `hmacKey string`: Required HMAC key.
-  - `salt string`: Optional salt string. If not provided, a random salt will be generated.
-  - `number int`: Optional specific number to use. If not provided, a random number will be generated.
-  - `expires \DateTime`: Optional expiration time for the challenge.
-  - `params array`: Optional URL-encoded query parameters.
+#### `ChallengeOptions`
 
-**Returns:** `array`
+```php
+$options = new ChallengeOptions(
+    $hmacKey,
+    ChallengeOptions::DEFAULT_ALGORITHM,
+    ChallengeOptions::DEFAULT_MAX_NUMBER,
+    (new \DateTimeImmutable())->add(new \DateInterval('PT10S')),
+    ['query_param' => '123'],
+    ChallengeOptions::DEFAULT_SALT_LENGTH
+]);
+```
 
-### `Altcha::verifySolution(array $payload, string $hmacKey, bool $checkExpires): bool`
+### `Altcha::verifySolution(array|string $payload, string $hmacKey, bool $checkExpires): bool`
 
 Verifies an ALTCHA solution.
 
 **Parameters:**
 
-- `payload array`: The solution payload to verify.
+- `data array|string`: The solution payload to verify.
 - `hmacKey string`: The HMAC key used for verification.
 - `checkExpires bool`: Whether to check if the challenge has expired.
 
 **Returns:** `bool`
 
-### `Altcha::extractParams(array $payload): array`
-
-Extracts URL parameters from the payload's salt.
-
-**Parameters:**
-
-- `payload array`: The payload containing the salt.
-
-**Returns:** `array`
-
 ### `Altcha::verifyFieldsHash(array $formData, array $fields, string $fieldsHash, string $algorithm): bool`
 
 Verifies the hash of form fields.
@@ -118,18 +110,18 @@ Verifies the hash of form fields.
 
 **Returns:** `bool`
 
-### `Altcha::verifyServerSignature($payload, string $hmacKey): array`
+### `Altcha::verifyServerSignature(array|string $payload, string $hmacKey): ServerSignatureVerification`
 
 Verifies the server signature.
 
 **Parameters:**
 
-- `payload mixed`: The payload to verify (string or `ServerSignaturePayload` array).
+- `data array|string`: The payload to verify (string or `ServerSignaturePayload` array).
 - `hmacKey string`: The HMAC key used for verification.
 
-**Returns:** `array`
+**Returns:** `ServerSignatureVerification`
 
-### `Altcha::solveChallenge(string $challenge, string $salt, string $algorithm, int $max, int $start, $stopChan = null): array`
+### `Altcha::solveChallenge(string $challenge, string $salt, string $algorithm, int $max, int $start = 0): array`
 
 Finds a solution to the given challenge.
 
@@ -141,7 +133,7 @@ Finds a solution to the given challenge.
 - `max int`: Maximum number to iterate to.
 - `start int`: Starting number.
 
-**Returns:** `array`
+**Returns:** `null|Solution`
 
 
 ## Tests
@@ -152,4 +144,4 @@ vendor/bin/phpunit --bootstrap src/Altcha.php tests/AltchaTest.php
 
 ## License
 
-MIT
+MIT

composer.json

@@ -14,9 +14,18 @@
         }
     ],
     "require": {
-        "php": ">=7.4"
+        "php": ">=7.4",
+        "ext-json": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": "^11.5"
+        "phpunit/phpunit": "^11.5",
+        "phpstan/phpstan": "^2.1",
+        "phpstan/phpstan-phpunit": "^2.0",
+        "phpstan/extension-installer": "^1.4"
+    },
+    "config": {
+        "allow-plugins": {
+            "phpstan/extension-installer": true
+        }
     }
 }

phpstan-baseline.neon

@@ -0,0 +1,7 @@
+parameters:
+	ignoreErrors:
+		-
+			message: '#^Dead catch \- ValueError is never thrown in the try block\.$#'
+			identifier: catch.neverThrown
+			count: 1
+			path: src/Altcha.php

phpstan.neon

@@ -0,0 +1,8 @@
+includes:
+    - phpstan-baseline.neon
+
+parameters:
+    level: max
+    paths:
+        - src
+        - tests

src/Algorithm.php

@@ -1,10 +1,12 @@
 <?php
 
+declare(strict_types=1);
+
 namespace AltchaOrg\Altcha;
 
 class Algorithm
 {
-    const SHA1 = 'SHA-1';
-    const SHA256 = 'SHA-256';
-    const SHA512 = 'SHA-512';
+    public const SHA1 = 'SHA-1';
+    public const SHA256 = 'SHA-256';
+    public const SHA512 = 'SHA-512';
 }