Kalkan Laravel Package

Getting Started

• For v2.0.0, start with PHP 8.3+ and Laravel 12+. Laravel 13 and PHP 8.5 are supported. If the app is on Laravel 10 or 11, stay on mitwork/kalkan:^1.2 until the framework is upgraded.
• Install with Composer, run the package install command (php artisan kalkan:install), and review the published/configurable NCANode connection settings first. Look at the package README, especially the “Обновление с 1.x” migration section, then the config file and NcanodeHttpClient.
• First practical use case: sign a document through NCANode. Pass the document content, key material, password, and desired TSA policy to signCms(), store the returned CMS, then use verify() and extract() for downstream checks. Note that signCms() now defaults to TSA_GOST2015_POLICY.

Implementation Patterns

• Wrap signing, verification, and extraction in a small application service/action rather than scattering calls through controllers. This keeps key/password handling, JsonException handling, and audit logging in one place.
• Prefer dependency injection of the package client/service in queued jobs and domain services. Use the facade only for small scripts or prototypes.
• Treat NCANode calls as remote I/O: configure sensible HTTP timeouts/retries, run bulk signing in queued jobs, and avoid holding web requests open for large batches.
• Because NcanodeHttpClient now uses Laravel’s HTTP client, tests should use Http::fake() and Http::assertSent() rather than Guzzle mock handlers. This also makes Http::preventStrayRequests() useful in CI.
• When customizing the HTTP client, expect a PendingRequest, not GuzzleHttp\Client. Use Laravel HTTP client methods for headers, timeouts, retries, and middleware-style behavior.
• For validation flows, pass explicit field lists as arrays to validate(). The v2 fix for Collection handling removes a sharp edge, but explicit arrays remain clearer.
• When storing signing requests with files, always pass a document id explicitly. The “missing id” bug is fixed, but explicit ids make persistence, retries, and audit trails more predictable.
• For TSA usage, set policy deliberately. New signing should use TSA_GOST2015_POLICY; only opt into the deprecated older policies for legacy compatibility with a clear migration plan.
• Use extract() for inspecting CMS contents and verify() for validation before trusting signed documents. Keep verification paths read-only and idempotent.

Gotchas and Tips

• Upgrade blockers: v2 drops Laravel 10 and 11. Confirm PHP and Laravel constraints before upgrading; otherwise pin 1.2.*.
• HTTP client type change: any custom binding, fake, or extension typed against GuzzleHttp\Client will break. Migrate to Laravel PendingRequest and Laravel HTTP client testing/faking patterns.
• New exceptions: signing, verification, and extraction may throw JsonException. Catch it at the application boundary and convert it into a domain-specific error with useful context.
• TSA policy change: signCms() now defaults to TSA_GOST2015_POLICY. If existing workflows depend on TSA_GOST_POLICY, set it explicitly and plan to migrate; older policies are deprecated.
• JSON failures: v2 fixes a failed json_encode() being sent as an empty NCANode request body, but still validate input encoding, especially for non-UTF-8 or binary-adjacent content.
• File uploads without ids: the document id loss bug is fixed, but explicit ids are still the safest integration pattern.
• Install command failure: kalkan:install now checks file_get_contents() results. If installation fails, check file permissions and paths rather than assuming the command succeeded.
• PHPUnit 13 discovery: test discovery was fixed for PHPUnit 13. If you maintain package-adjacent tests, re-check phpunit.xml patterns after upgrading.
• QR dependency upgrade: endroid/qr-code moved to 6.0. If the application customizes QR generation around the package, verify the new API and output assumptions.
• Debugging NCANode: check endpoint reachability, TLS/certificate trust, key/password correctness, TSA availability, and clock sync. Log HTTP status and correlation ids, but never log private keys or passwords.
• Static analysis: PHPStan is now level 7. If you extend package classes, expect stricter type assumptions, especially around HTTP client and JSON-decoded values.