 |
VOOZH | about |
|
VOOZH | about |
This document describes the contract layer of the hypervel/encryption package, which defines the behavioral contracts that all encryption implementations must fulfill. The two primary interfaces—Encrypter and StringEncrypter—establish the public API for encryption operations, key management, and data serialization.
For information about the concrete implementation of these contracts, see The Encrypter Implementation. For details on the exceptions thrown by these methods, see Error Handling and Exceptions.
The encryption system uses interface-based design to separate contract definition from implementation. This allows for dependency injection, testing with mock implementations, and potential future implementations with different cryptographic backends.
Sources: src/Contracts/Encrypter.php1-38 src/Contracts/StringEncrypter.php1-23
The Encrypter interface defines the core contract for encryption implementations. It is located at src/Contracts/Encrypter.php7-37 and provides five methods covering encryption operations and key management.
| Method | Parameters | Return Type | Exceptions | Description |
|---|---|---|---|---|
encrypt() | mixed $valuebool $serialize = true | string | EncryptException | Encrypts any PHP value, optionally serializing it first |
decrypt() | string $payloadbool $unserialize = true | mixed | DecryptException | Decrypts a payload, optionally unserializing the result |
getKey() | None | string | None | Returns the current encryption key |
getAllKeys() | None | array | None | Returns current key plus all previous keys |
getPreviousKeys() | None | array | None | Returns only the previous encryption keys |
Sources: src/Contracts/Encrypter.php9-36
The encrypt() and decrypt() methods form the core cryptographic operations:
Sources: src/Contracts/Encrypter.php9-21
Defined at src/Contracts/Encrypter.php14 this method encrypts a value and returns a base64-encoded string containing the encrypted payload.
Parameters:
mixed $value: Any PHP value to encrypt (string, array, object, etc.)bool $serialize: Whether to serialize the value before encryption (default: true)Return Value: A base64-encoded string containing a JSON structure with cryptographic artifacts (IV, ciphertext, MAC/tag).
Exceptions: Throws \Hypervel\Encryption\Exceptions\EncryptException if encryption fails.
Serialization Behavior: When $serialize is true, the value is serialized using PHP's serialize() function before encryption. This allows encryption of complex data structures. When false, the value must be a string.
Defined at src/Contracts/Encrypter.php21 this method decrypts a payload previously encrypted with encrypt().
Parameters:
string $payload: The base64-encoded encrypted payloadbool $unserialize: Whether to unserialize the decrypted value (default: true)Return Value: The decrypted value. Type depends on what was originally encrypted and the $unserialize parameter.
Exceptions: Throws \Hypervel\Encryption\Exceptions\DecryptException if:
Deserialization Behavior: When $unserialize is true, the implementation calls unserialize() on the decrypted data. When false, raw decrypted bytes are returned as a string.
Sources: src/Contracts/Encrypter.php14-21
The interface defines three methods for accessing encryption keys, supporting key rotation scenarios:
Sources: src/Contracts/Encrypter.php23-36
Defined at src/Contracts/Encrypter.php26 returns the current encryption key as a raw byte string.
Parameters: None
Return Value: string - The current encryption key (raw bytes, not base64-encoded)
Usage: This key is used for all encryption operations. During decryption, it is the first key attempted.
Defined at src/Contracts/Encrypter.php31 returns an array containing the current key followed by all previous keys.
Parameters: None
Return Value: array - Array of key strings, with current key at index 0
Usage: Used during decryption to attempt decryption with multiple keys, enabling zero-downtime key rotation.
Defined at src/Contracts/Encrypter.php36 returns only the previous encryption keys, excluding the current key.
Parameters: None
Return Value: array - Array of previous key strings
Usage: Useful for auditing, key management tools, and determining if old keys can be retired.
Sources: src/Contracts/Encrypter.php23-36
The StringEncrypter interface provides specialized methods for encrypting strings without serialization overhead. It is defined at src/Contracts/StringEncrypter.php7-22 as a separate contract that can be implemented alongside or independently of the Encrypter interface.
| Method | Parameters | Return Type | Exceptions | Description |
|---|---|---|---|---|
encryptString() | string $value | string | EncryptException | Encrypts a string without serialization |
decryptString() | string $payload | string | DecryptException | Decrypts a string without deserialization |
Sources: src/Contracts/StringEncrypter.php9-21
Sources: src/Contracts/StringEncrypter.php1-23
Defined at src/Contracts/StringEncrypter.php14 this method encrypts a string value without applying PHP serialization.
Parameters:
string $value: The string to encryptReturn Value: string - Base64-encoded encrypted payload
Exceptions: Throws \Hypervel\Encryption\Exceptions\EncryptException if encryption fails.
Relationship to encrypt(): This method is functionally equivalent to calling encrypt($value, false) where $value is a string. It provides a more explicit, type-safe API for string-only operations.
Defined at src/Contracts/StringEncrypter.php21 this method decrypts a payload and returns the raw string without deserialization.
Parameters:
string $payload: The base64-encoded encrypted payloadReturn Value: string - The decrypted string value
Exceptions: Throws \Hypervel\Encryption\Exceptions\DecryptException if decryption or validation fails.
Relationship to decrypt(): This method is functionally equivalent to calling decrypt($payload, false) and expecting a string result. It provides stronger type guarantees in the method signature.
Sources: src/Contracts/StringEncrypter.php9-21
The standard implementation pattern is for a single class to implement both interfaces, providing a unified encryption service that supports both serialized and non-serialized operations.
Sources: src/Contracts/Encrypter.php1-38 src/Contracts/StringEncrypter.php1-23
The separation of Encrypter and StringEncrypter into distinct interfaces serves several architectural purposes:
| Reason | Benefit |
|---|---|
| Interface Segregation | Clients that only need string encryption can depend on a narrower contract |
| Type Safety | encryptString() and decryptString() have stricter type signatures than their generic counterparts |
| API Clarity | Method names explicitly indicate that serialization is not performed |
| Backward Compatibility | Allows gradual migration from generic methods to specialized methods |
| Testing | Enables creation of mock implementations that only support string operations |
Sources: src/Contracts/Encrypter.php1-38 src/Contracts/StringEncrypter.php1-23
When using these interfaces in application code, type hint against the appropriate interface based on your requirements:
Type Hinting Guidelines:
Type hint Encrypter when you need:
getKey(), getAllKeys(), getPreviousKeys())Type hint StringEncrypter when you need:
Type hint both (intersection type) if your code requires both capabilities and you want compile-time verification that the implementation provides both.
Sources: src/Contracts/Encrypter.php1-38 src/Contracts/StringEncrypter.php1-23
Implementations of these interfaces must maintain the following guarantees:
| Invariant | Description |
|---|---|
| Roundtrip Integrity | decrypt(encrypt($value, $s), $s) === $value for any value and serialize flag |
| Key Consistency | getKey() returns the same value throughout the object's lifetime unless explicitly changed |
| Key Ordering | getAllKeys()[0] always equals getKey() |
| Previous Keys Subset | All keys in getPreviousKeys() appear in getAllKeys() starting from index 1 |
| Deterministic Failures | Same malformed payload always throws the same exception type |
| Freshness | Each encrypt() call generates a new, random IV |
Contract Requirements:
EncryptException for any encryption failureDecryptException for any decryption failureRuntimeExceptionSources: src/Contracts/Encrypter.php9-21 src/Contracts/StringEncrypter.php9-21
The contract layer consists of two interfaces that together define the complete encryption API:
Encrypter interface (src/Contracts/Encrypter.php7-37): Defines core encryption/decryption with serialization support and key managementStringEncrypter interface (src/Contracts/StringEncrypter.php7-22): Defines specialized string encryption without serialization overheadBoth interfaces are typically implemented by a single class that provides unified encryption services. The separation enables interface segregation while the common implementation ensures consistency.
For details on how these contracts are implemented, see The Encrypter Implementation. For information on how encrypter instances are created and configured, see The Encrypter Factory.
Refresh this wiki