Encrypter Laravel Package

Getting Started

The Spiral Encrypter component is a lightweight, PSR-12-compliant encryption wrapper built around PHP’s openssl_* functions. To begin:

1. Install: composer require spiral/encrypter
2. Minimum PHP: 7.2+
3. Core interface: Spiral\Encrypter\EncrypterInterface
4. Basic usage:

   use Spiral\Encrypter\Encrypter;
   use Spiral\Encrypter\Key;
   
   $key = Key::fromString('your-32-byte-base64-key-here'); // Must be 32 bytes for AES-256
   $encrypter = new Encrypter($key);
   
   $encrypted = $encrypter->encrypt('secret data');
   $decrypted = $encrypter->decrypt($encrypted);
   

5. Key management: Use Key::fromBase64() or Key::fromString()—ensure keys are 32 bytes for AES-256-CBC (default).

Start by replacing base64_encode/decode or manual openssl calls in your codebase with this component for safer, more consistent encryption.

Implementation Patterns

• Factory-based creation (via EncrypterFactory):

  $factory = new EncrypterFactory([
      'cipher' => 'AES-256-CBC',
      'mac' => 'SHA256', // for authenticated encryption (HMAC)
  ]);
  $encrypter = $factory->getEncrypter($key);
  

• Configuration-driven setup (ideal for DI containers):

  return [
      'encrypter' => [
          'key' => env('ENCRYPTER_KEY'),
          'cipher' => 'AES-256-CBC',
          'mac' => 'SHA256',
      ],
  ];
  

• Store & retrieve encrypted config (e.g., DB passwords, API tokens):

  $config = [
      'db_password' => $encrypter->encrypt($rawPassword),
  ];
  // Later...
  $decrypted = $encrypter->decrypt($config['db_password']);
  

• Integrate with environment variables:

  # .env
  ENCRYPTER_KEY=base64:your_base64_encoded_32_byte_key=
  

  $key = Key::fromBase64($_ENV['ENCRYPTER_KEY']);
  

• Typed encryption for objects:

  // Serialize + encrypt
  $payload = $encrypter->encrypt(json_encode($data));
  $data = json_decode($encrypter->decrypt($payload), true);
  

Use EncrypterFactory for default-safe configurations (e.g., enabling authenticated encryption via hmac/mac).

Gotchas and Tips

• ⚠️ Key length matters: AES-256 requires a 32-byte key (not 64-char string!). openssl_get_cipher_methods() may list AES-256-CBC but key length must be correct.
• ⚠️ Use EncrypterFactory over direct Encrypter instantiation unless you’re certain about defaults—factory ensures authenticated encryption (HMAC) is used to prevent padding oracle attacks.
• mac algorithm required: By default, EncrypterFactory enables MAC verification (SHA256). Without it, decrypt failures may not be obvious (silent corruption risk).
• No automatic key rotation: You must manage key versions manually (e.g., prefix encrypted strings with version and use multiple encrypters).
• Base64 encoding is automatic: Encrypted output is base64-encoded—no need to re-encode. Use base64_decode() only when migrating.
• Test with known vectors: Validate your setup using NIST test vectors for AES-CBC + HMAC.
• Legacy vs. modern:
  • v1.0.0 used Manager; renamed to Factory in v1.0.1.
  • Namespace changed from Spiral\Encrypter → Spiral\Encrypter (no prefix change, but ensure no conflicts).
• Not for key management: This is an encrypter, not a full KMS. For production, pair with AWS KMS, Vault, or environment-based key injection.
• No BC break in v1.2.0: Just strict typing and CS fixes—safe to upgrade from v1.1.x if tests exist.