Parameter Encryption Zend Crypt Bundle Laravel Package

Getting Started

1. Install via Composer, checking version constraints for your Laravel/Symfony stack:

   composer require vendor/package
   

   This release (v1.1.0) adds support for Symfony 4.x and zendframework/zend-crypt 3.x, so it is compatible with Laravel 5.6+ (which uses Symfony 4 components).

2. Publish any package configuration (if the package provides one):

   php artisan vendor:publish --provider="Vendor\Package\ServiceProvider"
   

   Review the published config for keys, ciphers, or adapter settings.

3. First use case: perform a basic encrypt/decrypt round-trip or hash a value using the package’s facade or injectable service. Consult the README’s “Usage” section for the exact method names. A typical smoke test:

   $ciphertext = Package::encrypt('secret');
   $plaintext  = Package::decrypt($ciphertext);
   // assert $plaintext === 'secret'
   

4. Where to look first:

   • README.md for installation and usage examples.
   • The package’s service provider to see bindings and config merging.
   • config/ directory (if published) for adjustable options.

Implementation Patterns

• Dependency injection – Inject the package’s service interface into controllers, jobs, or commands rather than using the facade everywhere. This keeps your code testable.

  public function __construct(private PackageService $crypto) {}
  

• Model attribute encryption – Use a custom cast or accessor/mutator to encrypt sensitive columns transparently:

  protected $casts = [
      'secret' => EncryptedCast::class, // or use the package’s provided cast if available
  ];
  

• Queue-safe payloads – If you encrypt data before dispatching jobs, ensure the key material is available to workers (e.g., via .env and config cache). The package’s Symfony 4 compatibility means it works with Laravel’s queue stack without extra shims.

• Version pinning – In composer.json, you can now allow:

  "symfony/*": "^4.0",
  "zendframework/zend-crypt": "^3.0"
  

  This is useful if your application already depends on these versions. The package no longer forces older constraints.

• Testing – Mock the service in unit tests, or use the package’s test helpers if provided. For integration tests, use an in-memory key and assert round-trip encryption.

• Configuration over code – Prefer publishing and editing the config file for cipher/key settings rather than hard-coding values. Use environment variables for secrets.

Gotchas and Tips

• PHP version requirement – zendframework/zend-crypt 3.x requires PHP 7.1 or higher. Confirm your runtime meets this before upgrading.

• Laravel/Symfony alignment – Symfony 4.x support means Laravel 5.6+. If you are on Laravel 5.5 (Symfony 3), stay on the previous package release or upgrade Laravel first.

• Removed dist config files – v1.1.0 removes .php-cs-fixer.dist.php and phpunit.xml.dist from git exports. These files will not appear in vendor/. If your CI or local tooling relied on them, copy equivalent configs into your project or fetch them from the package repository.

• Clear caches after upgrade – Run php artisan config:clear and composer dump-autoload after updating to avoid stale bindings or config.

• Debugging crypto failures – Enable Laravel’s logging and wrap operations in try/catch to surface exceptions. Check storage/logs/laravel.log for decryption errors (often caused by key rotation or mismatched cipher settings).

• Extension points – Most crypto packages allow custom key providers, cipher lists, or adapters via config. Publish the config and override the relevant array keys. If the package uses a manager class, you can extend it and rebind in a service provider.

• Don’t roll your own – Use the package’s high-level API for encryption, decryption, and hashing. Avoid mixing it with Laravel’s Crypt unless the package explicitly wraps it; key formats may differ.

• Backward compatibility – v1.1.0 is a minor release with no breaking changes. Existing code should continue to work, but verify your composer.lock resolves the new Symfony/zend-crypt versions as expected.