Add initphp/encryption package info, require PHP 8.1 in README.md

Author: muhammetsafak

README.md

@@ -1,132 +1,241 @@
-# Encryption
-PHP OpenSSL/Sodium Encryption and Decryption
+# initphp/encryption
 
-[![Latest Stable Version](http://poser.pugx.org/initphp/encryption/v)](https://packagist.org/packages/initphp/encryption) [![Total Downloads](http://poser.pugx.org/initphp/encryption/downloads)](https://packagist.org/packages/initphp/encryption) [![Latest Unstable Version](http://poser.pugx.org/initphp/encryption/v/unstable)](https://packagist.org/packages/initphp/encryption) [![License](http://poser.pugx.org/initphp/encryption/license)](https://packagist.org/packages/initphp/encryption) [![PHP Version Require](http://poser.pugx.org/initphp/encryption/require/php)](https://packagist.org/packages/initphp/encryption)
+Secure, modern symmetric encryption for PHP on top of OpenSSL and libsodium.
+
+[![Latest Stable Version](https://poser.pugx.org/initphp/encryption/v)](https://packagist.org/packages/initphp/encryption)
+[![Total Downloads](https://poser.pugx.org/initphp/encryption/downloads)](https://packagist.org/packages/initphp/encryption)
+[![License](https://poser.pugx.org/initphp/encryption/license)](https://packagist.org/packages/initphp/encryption)
+[![PHP Version Require](https://poser.pugx.org/initphp/encryption/require/php)](https://packagist.org/packages/initphp/encryption)
+
+## Why
+
+PHP's encryption primitives are powerful but unforgiving. Pick the wrong cipher,
+mix up IV and HMAC ordering, forget constant-time comparison, or hand libsodium
+a 14-byte "key" and you ship a vulnerability — or, more often, a silent failure
+that "works on my machine".
+
+This package wraps `ext-openssl` and `ext-sodium` behind a small, opinionated
+API:
+
+- Authenticated by default. OpenSSL uses encrypt-then-MAC; Sodium uses the
+  built-in AEAD construction.
+- Keys of any non-empty length are accepted and derived to the size the
+  primitive actually requires.
+- Ciphertexts are self-describing: a 2-byte header (version + serializer flag)
+  lets the library reject malformed or out-of-date input with a clear error
+  instead of returning garbage.
+- A single `EncryptionException` covers every failure mode, so a `try` /
+  `catch` is enough to handle all error paths.
+- JSON is the default payload serializer, so the historical
+  `unserialize()`-on-attacker-controlled-bytes pitfall is closed by default.
 
 ## Requirements
 
-- PHP 7.4 or higher
-- MB_String extension
-- Depending on usage: 
-  - OpenSSL extesion
-  - Sodium extension
+- PHP **8.1** or higher
+- `ext-openssl` for the OpenSSL handler
+- `ext-sodium` for the Sodium handler
 
+Both extensions ship with mainstream PHP distributions, but the package only
+loads the one you actually instantiate — you can use one handler without the
+other being available.
 
 ## Installation
 
-```
+```bash
 composer require initphp/encryption
 ```
 
-## Configuration
+## Quickstart
 
-```php 
-$options = [
-    'algo'      => 'SHA256',
-    'cipher'    => 'AES-256-CTR',
-    'key'       => null,
-    'blocksize' => 16,
-];
-```
+```php
+<?php
 
-- `algo` : Used by OpenSSL handler only. The algorithm to use to sign the data.
-- `cipher` : Used by OpenSSL handler only. The encryption algorithm that will be used to encrypt the data.
-- `key` : The top secret key string to use for encryption.
-- `blocksize` : It is used for sodium handler only. It is used in the `sodium_pad()` and `sodium_unpad()` functions.
+require __DIR__ . '/vendor/autoload.php';
 
+use InitPHP\Encryption\Encrypt;
+use InitPHP\Encryption\OpenSSL;
 
-## Usage
+$handler = Encrypt::use(OpenSSL::class, [
+    'key' => getenv('APP_ENCRYPTION_KEY'),
+]);
 
-```php 
-require_once "vendor/autoload.php";
-use \InitPHP\Encryption\Encrypt;
+$ciphertext = $handler->encrypt(['user_id' => 42, 'role' => 'admin']);
+// → "02006f1c…": hex string, safe to store in cookies / DBs / URL params
 
-// OpenSSL Handler
-/** @var $openssl \InitPHP\Encryption\HandlerInterface */
-$openssl = Encrypt::use(\InitPHP\Encryption\OpenSSL::class, [
-    'algo'      => 'SHA256',
-    'cipher'    => 'AES-256-CTR',
-    'key'       => 'TOP_Secret_Key',
-]);
+$plaintext = $handler->decrypt($ciphertext);
+// → ['user_id' => 42, 'role' => 'admin']
+```
+
+The Sodium handler has the same surface:
+
+```php
+use InitPHP\Encryption\Encrypt;
+use InitPHP\Encryption\Sodium;
 
-// Sodium Handler
-/** @var $sodium \InitPHP\Encryption\HandlerInterface */
-$sodium = Encrypt::use(\InitPHP\Encryption\Sodium::class, [
-    'key'       => 'TOP_Secret_Key',
-    'blocksize' => 16,
+$handler = Encrypt::use(Sodium::class, [
+    'key' => getenv('APP_ENCRYPTION_KEY'),
 ]);
+
+$ciphertext = $handler->encrypt('a secret message');
+$plaintext  = $handler->decrypt($ciphertext);
 ```
 
-### Methods
+## Configuration
 
-#### `encrypt()`
+Every option is optional except `key`. Unknown keys are ignored. Keys are
+case-insensitive on input (`'CIPHER'` and `'cipher'` are the same option).
 
-```php 
-public function encrypt(mixed $data, array $options = []): string;
-```
+| Option       | Used by   | Default        | Description |
+| ------------ | --------- | -------------- | ----------- |
+| `key`        | both      | _required_     | The user-supplied secret. Any non-empty string; the handler derives a key of the correct length internally. |
+| `cipher`     | OpenSSL   | `AES-256-CTR`  | Any algorithm from `openssl_get_cipher_methods()`. |
+| `algo`       | OpenSSL   | `SHA256`       | Any algorithm from `hash_hmac_algos()`. Used both for HKDF key derivation and for the HMAC tag. |
+| `blocksize`  | Sodium    | `16`           | Block size for `sodium_pad()` / `sodium_unpad()`. Must be a positive integer. |
+| `serializer` | both      | `'json'`       | One of `'json'`, `'php_serialize'`, `'php'`, `'serialize'`. See [Serialization](#serialization). |
+
+Options can be set in three places, in order of precedence (highest wins):
 
-#### `decrypt()`
+```php
+// 1) Per-call override
+$handler->encrypt($data, ['cipher' => 'AES-256-GCM']);
 
-```php 
-public function decrypt(string $data, array $options = []): mixed;
+// 2) Mutated on the handler
+$handler->setOption('cipher', 'AES-256-GCM');
+$handler->setOptions(['cipher' => 'AES-256-GCM', 'algo' => 'SHA512']);
+
+// 3) Constructor / factory
+$handler = Encrypt::use(OpenSSL::class, ['cipher' => 'AES-256-GCM']);
 ```
 
-## Writing Your Own Handler
+Per-call options do **not** mutate the handler — they are merged into a fresh
+array for that single call only.
 
-```php 
-namespace App;
+## Serialization
 
-use \InitPHP\Encryption\{HandlerInterface, BaseHandler};
+`encrypt()` accepts `mixed` and round-trips the value through a serializer
+chosen via the `serializer` option. The flag is embedded in the ciphertext, so
+`decrypt()` always restores the original type without you having to track the
+choice yourself.
 
-class MyHandler extends BaseHandler implements HandlerInterface
-{
-    public function encrypt($data, array $options = []): string
-    {
-        $options = $this->options($options);
-        // ... process
-    }
+| `serializer` value | On-the-wire flag | Behaviour |
+| --- | --- | --- |
+| `'json'` (default) | `0x00` | Uses `json_encode`/`json_decode` with `JSON_THROW_ON_ERROR`. Safe: no PHP class is ever instantiated during decoding. Cannot carry raw binary bytes — use `php_serialize` if you need that. |
+| `'php_serialize'`, `'php'`, `'serialize'` | `0x01` | Uses `serialize()`/`unserialize()` with `['allowed_classes' => false]`. Round-trips scalars, arrays and binary strings; custom objects degrade to `__PHP_Incomplete_Class` on decode. |
 
-    public function decrypt($data, array $options = [])
-    {
-        $options = $this->options($options);
-        // ... process
-    }
-}
-```
+The PHP serializer is opt-in for one reason only: even though we always pass
+`allowed_classes:false`, the safer default lets you not have to think about
+object-injection vectors at all.
 
-```php 
-use \InitPHP\Encryption\Encrypt;
+## Writing a Custom Handler
 
-$myhandler = Encrypt::use(\App\MyHandler::class);
-```
+Extend `BaseHandler` (not `OpenSSL` / `Sodium` — those are `final`) and
+implement `encrypt()` and `decrypt()`:
 
-## Getting Help
+```php
+namespace App\Crypto;
 
-If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.
+use InitPHP\Encryption\BaseHandler;
+use InitPHP\Encryption\Exceptions\EncryptionException;
+
+final class MyHandler extends BaseHandler
+{
+    public function encrypt(mixed $data, array $options = []): string
+    {
+        $options       = $this->resolveOptions($options);
+        $key           = $this->requireKey($options);
+        $serializerFlag = $this->serializerFlag($options);
 
-## Getting Involved
+        $payload = $this->serializePayload($data, $serializerFlag);
+        // ... apply your primitive of choice, return a hex-encoded string ...
+    }
 
-> All contributions to this project will be published under the MIT License. By submitting a pull request or filing a bug, issue, or feature request, you are agreeing to comply with this waiver of copyright interest.
+    public function decrypt(string $data, array $options = []): mixed
+    {
+        $options       = $this->resolveOptions($options);
+        $key           = $this->requireKey($options);
 
-There are two primary ways to help:
+        // ... reverse the encoding, return $this->unserializePayload($plain, $flag) ...
+    }
+}
 
-- Using the issue tracker, and
-- Changing the code-base.
-    
-### Using the issue tracker
+// Use it via the factory just like the built-in handlers:
+$handler = \InitPHP\Encryption\Encrypt::use(\App\Crypto\MyHandler::class, [
+    'key' => 'secret',
+]);
+```
 
-Use the issue tracker to suggest feature requests, report bugs, and ask questions. This is also a great way to connect with the developers of the project as well as others who are interested in this solution.
+`BaseHandler` gives you `resolveOptions()`, `requireKey()`,
+`serializerFlag()`, `serializePayload()` and `unserializePayload()` for free,
+so you only write the cryptographic glue.
 
-Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in the issue that you will take on that effort, then follow the Changing the code-base guidance below.
+## Error Handling
 
-### Changing the code-base
+Every failure path raises `InitPHP\Encryption\Exceptions\EncryptionException`
+(which extends `\RuntimeException`). A single `catch` covers everything:
 
-Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull request. All new code should have associated unit tests that validate implemented features and the presence or lack of defects. Additionally, the code should follow any stylistic and architectural guidelines prescribed by the project. In the absence of such guidelines, mimic the styles and patterns in the existing code-base.
+```php
+use InitPHP\Encryption\Exceptions\EncryptionException;
 
-## Credits
+try {
+    $plaintext = $handler->decrypt($incoming);
+} catch (EncryptionException $e) {
+    // Bad input, tampered ciphertext, missing key, unsupported format
+    // version, unknown cipher or hash algorithm, …
+    $logger->warning('decrypt failed', ['reason' => $e->getMessage()]);
+}
+```
 
-- [Muhammet ŞAFAK](https://www.muhammetsafak.com.tr)
+Notable messages you may see:
+
+- `Unsupported ciphertext format version 0x01; expected 0x02. Ciphertexts produced by 1.x are not readable by 2.x.`
+- `HMAC verification failed; ciphertext is corrupted or has been tampered with.`
+- `Sodium decryption failed; ciphertext is corrupted or has been tampered with.`
+- `The "key" option is required and must be a non-empty string.`
+- `Unknown OpenSSL cipher "…".`
+
+## Security Notes
+
+- **Key management is your job.** Store the key outside the code repository —
+  environment variable, secret manager, KMS, etc. — and rotate it like any
+  other secret.
+- **Key strength matters.** The handler accepts any non-empty user key and
+  derives one of the right length, but it cannot add entropy that the input
+  does not contain. Use a random 256-bit string (`bin2hex(random_bytes(32))`)
+  in production rather than a passphrase.
+- **Authentication is always on.** OpenSSL ciphertexts include an HMAC of the
+  header, IV, and ciphertext; Sodium uses its built-in AEAD. There is no
+  "encrypt without authenticate" mode.
+- **Format is versioned.** The first byte of every ciphertext identifies the
+  format. A future major release that changes the layout will bump this byte
+  and reject older ciphertexts with a clear error.
+- **Found something concerning?** See [SECURITY.md](./SECURITY.md) — please do
+  not open a public issue for vulnerabilities.
+
+## Upgrading from 1.x
+
+Version 2.0 is a hard reset of the public surface and the on-wire format:
+
+- Minimum PHP version is now **8.1**.
+- Ciphertexts produced by 1.x **cannot be decrypted by 2.x.** Plan a
+  re-encryption migration before upgrading.
+- The default payload serializer is JSON (was `serialize`). Pass
+  `'serializer' => 'php_serialize'` to keep the old behaviour.
+- `Encrypt::create()` has been removed; use `Encrypt::use()`.
+- The Sodium handler no longer requires a 32-byte key — any non-empty string
+  is now accepted and derived internally.
+- `ext-mbstring` is no longer required.
+
+A full migration walk-through lives in
+[`docs/08-migration-v1-to-v2.md`](./docs/08-migration-v1-to-v2.md) (shipped
+with the package; see also the [docs/](./docs/) index).
+
+## Contributing
+
+PRs are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) first — it
+covers the local quality gates (`composer test`, `composer phpstan`,
+`composer cs-check`) and the security-review process for changes touching the
+cryptographic primitives.
 
 ## License
 
-Copyright &copy; 2022 [MIT License](./LICENSE)
+MIT — see [LICENSE](./LICENSE).