Modernize code

Uses types where possible and improves array handling.
The default challenge options now use sane defaults and optional
parameters.

Improves validation of user input.

Author: aleho

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