2.x

.github/workflows/ci.yml

@@ -0,0 +1,106 @@
+name: CI
+
+on:
+  push:
+    branches: [main, 2.x, 1.x]
+  pull_request:
+    branches: [main, 2.x, 1.x]
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: PHP ${{ matrix.php }} / ${{ matrix.dependencies }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.1', '8.2', '8.3', '8.4']
+        dependencies: [highest]
+        include:
+          - php: '8.1'
+            dependencies: lowest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: openssl, sodium
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate composer.json
+        run: composer validate --strict
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache composer dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-php-${{ matrix.php }}-${{ matrix.dependencies }}-${{ hashFiles('**/composer.json') }}
+          restore-keys: |
+            ${{ runner.os }}-php-${{ matrix.php }}-${{ matrix.dependencies }}-
+
+      - name: Install dependencies (highest)
+        if: matrix.dependencies == 'highest'
+        run: composer update --no-interaction --no-progress --prefer-dist
+
+      - name: Install dependencies (lowest)
+        if: matrix.dependencies == 'lowest'
+        run: composer update --no-interaction --no-progress --prefer-dist --prefer-lowest
+
+      - name: Run tests
+        run: composer test
+
+  static-analysis:
+    name: Static analysis
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: openssl, sodium
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer update --no-interaction --no-progress --prefer-dist
+
+      - name: PHPStan
+        run: composer phpstan
+
+  coding-style:
+    name: Coding style
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: openssl, sodium
+          coverage: none
+          tools: composer:v2, php-cs-fixer
+
+      - name: Install dependencies
+        run: composer update --no-interaction --no-progress --prefer-dist
+
+      - name: Check style
+        run: composer cs-check

.github/workflows/security.yml

@@ -0,0 +1,35 @@
+name: Security
+
+on:
+  push:
+    branches: [main, 2.x, 1.x]
+  pull_request:
+    branches: [main, 2.x, 1.x]
+  schedule:
+    - cron: '17 6 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  composer-audit:
+    name: composer audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: openssl, sodium
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer update --no-interaction --no-progress --prefer-dist
+
+      - name: Run composer audit
+        run: composer audit --no-dev --locked || composer audit

.gitignore

@@ -2,4 +2,10 @@
 /.vs/
 /.vscode/
 /vendor/
-/composer.lock
+/composer.lock
+/build/
+/coverage/
+/.phpunit.cache/
+/.phpunit.result.cache
+/.php-cs-fixer.cache
+/.phpstan.cache

.php-cs-fixer.dist.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+$finder = (new PhpCsFixer\Finder())
+    ->in([__DIR__ . '/src', __DIR__ . '/tests'])
+    ->name('*.php')
+    ->ignoreDotFiles(true)
+    ->ignoreVCS(true);
+
+return (new PhpCsFixer\Config())
+    ->setRiskyAllowed(true)
+    ->setFinder($finder)
+    ->setCacheFile(__DIR__ . '/.php-cs-fixer.cache')
+    ->setRules([
+        '@PSR12' => true,
+        '@PSR12:risky' => true,
+        'declare_strict_types' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'ordered_imports' => [
+            'sort_algorithm' => 'alpha',
+            'imports_order' => ['class', 'function', 'const'],
+        ],
+        'no_unused_imports' => true,
+        'single_quote' => true,
+        'trailing_comma_in_multiline' => ['elements' => ['arrays', 'arguments', 'parameters']],
+        'no_trailing_whitespace' => true,
+        'no_whitespace_in_blank_line' => true,
+        'no_extra_blank_lines' => ['tokens' => ['extra', 'throw', 'use']],
+        'blank_line_after_opening_tag' => true,
+        'blank_line_before_statement' => ['statements' => ['return', 'throw', 'try']],
+        'cast_spaces' => ['space' => 'single'],
+        'concat_space' => ['spacing' => 'one'],
+        'native_function_invocation' => [
+            'include' => ['@compiler_optimized'],
+            'scope' => 'namespaced',
+            'strict' => true,
+        ],
+    ]);

CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to `initphp/encryption` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned for 2.0.0
+
+This is the first development entry of the upcoming 2.0 release. The 2.x line is
+a deliberate hard reset of the public surface; ciphertexts produced by 1.x cannot
+be decrypted by 2.x and vice versa. A migration guide will ship with the final
+release.
+
+#### Added
+
+- Tooling: PHPUnit 10, PHPStan level 8, PHP-CS-Fixer (PSR-12), GitHub Actions CI
+  matrix across PHP 8.1–8.4, `composer audit` workflow.
+- `composer.json` scripts: `test`, `test-coverage`, `phpstan`, `cs-check`,
+  `cs-fix`, `qa`.
+- Package-level `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`.
+
+#### Changed
+
+- **BREAKING:** Minimum PHP version raised to `^8.1`.
+
+#### To be done (tracked, not yet shipped)
+
+- **BREAKING:** New self-describing ciphertext format (versioned header) — v1
+  ciphertexts will not be readable by 2.x.
+- **BREAKING:** Default payload serialization switches from `serialize()`/
+  `unserialize()` to JSON. PHP serialization remains available as an opt-in.
+- Sodium handler derives a 32-byte key from any-length user-supplied key
+  material via `sodium_crypto_generichash`, fixing the silent failure when a
+  short key was provided.
+- OpenSSL handler uses `random_bytes()` for IV generation.
+- OpenSSL handler computes the HMAC length from the actual hash output instead
+  of parsing the algorithm name as a numeric suffix.
+- Mandatory key validation with a descriptive `EncryptionException` instead of
+  obscure `TypeError`s deep inside the extensions.
+- Drop runtime dependency on `ext-mbstring`.
+- PSR-12 compliance across the codebase.
+- Removal of `Encrypt::create()` (alias of `Encrypt::use()`).
+
+## [1.0.0] - 2022
+
+Initial release.

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to `initphp/encryption`
+
+This package follows the [InitPHP org-wide contribution guide](https://github.com/InitPHP/.github/blob/main/CONTRIBUTING.md).
+Please read it first — everything below is in addition to that guide, not a
+replacement for it.
+
+## Local Development
+
+```bash
+git clone https://github.com/InitPHP/Encryption.git
+cd Encryption
+composer install
+```
+
+Required PHP extensions for the test suite:
+
+- `ext-openssl`
+- `ext-sodium`
+
+## Quality Gates
+
+The CI pipeline runs three checks. Run them locally before pushing — every PR
+must pass all three.
+
+| Command | What it does |
+| --- | --- |
+| `composer test` | Run the PHPUnit suite. |
+| `composer phpstan` | Static analysis at level 8. |
+| `composer cs-check` | Verify PSR-12 compliance (read-only). |
+| `composer cs-fix` | Apply PSR-12 fixes automatically. |
+| `composer qa` | Run cs-check, phpstan and tests in sequence. |
+
+## Writing Tests
+
+- Unit tests live in `tests/Unit/` and must not require any I/O or extension
+  state beyond what `ext-openssl` and `ext-sodium` provide.
+- Integration tests live in `tests/Integration/` and may pin golden
+  ciphertexts for backwards-compatibility verification.
+- A bug fix PR must include a regression test that fails on `main` and passes
+  with the fix applied.
+- Cover both the happy path and the failure paths (tampered ciphertext,
+  invalid configuration, missing key, etc.).
+
+## Security-Sensitive Changes
+
+Any change that affects cryptographic primitives, key derivation, ciphertext
+format, or the trust boundary between an attacker and the plaintext requires:
+
+1. An explicit reviewer note in the PR description describing the threat model.
+2. A test that exercises the failure path (e.g. tampered HMAC must be rejected).
+3. A `CHANGELOG.md` entry under the appropriate section.
+
+If you believe you have found a vulnerability, **do not open a public issue or
+PR.** Follow the [security policy](./SECURITY.md) instead.
+
+## Commit Messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/). Typical
+scopes for this repository:
+
+- `openssl` — changes to `OpenSSL` handler
+- `sodium` — changes to `Sodium` handler
+- `base` — changes to `BaseHandler`
+- `factory` — changes to `Encrypt`
+- `docs`, `test`, `ci`, `chore` — as in the org guide
+
+Example:
+
+```
+fix(openssl): handle openssl_decrypt failure before unserialize
+
+openssl_decrypt() returns false on failure, which then caused
+unserialize(false) to throw a TypeError on PHP 8.x. Detect the false
+return and throw EncryptionException with a meaningful message.
+
+Closes #NN
+```