Core Concepts

Purpose and Scope

This document explains the fundamental architectural concepts of the hypervel/encryption library, focusing on how contracts, implementations, and the factory pattern work together to provide secure encryption capabilities.

The encryption system consists of three primary architectural layers:

Layer	Primary Components	Purpose
Contract Layer	Encrypter and StringEncrypter interfaces	Define the encryption API contract
Implementation Layer	Encrypter class	Implements cryptographic operations
Factory Layer	EncryptionFactory class	Creates and configures Encrypter instances

This page provides a high-level overview of these concepts and their relationships. For detailed specifications of the contract interfaces, see page 4.1 (Encryption Contracts and Interfaces). For implementation details including cipher support and cryptographic operations, see page 4.2 (The Encrypter Implementation). For factory configuration and instance creation, see page 4.3 (The Encrypter Factory).

Component Architecture Overview

The encryption library implements a layered architecture separating concerns between contracts, implementations, and factory instantiation.

Component Relationship Diagram

The architecture employs three fundamental design patterns:

Pattern	Implementation	Key Classes/Interfaces
Contract-Based Design	Interfaces define the API independently of implementation	Hypervel\Encryption\Contracts\Encrypter Hypervel\Encryption\Contracts\StringEncrypter
Factory Pattern	Factory creates fully configured instances from configuration	Hypervel\Encryption\EncryptionFactory
Dependency Injection	PSR-11 container manages lifecycle and resolves dependencies	ConfigProvider registers bindings

Sources: src/Contracts/Encrypter.php7-37 src/Contracts/StringEncrypter.php src/Encrypter.php13 src/EncryptionFactory.php15-32

Contract-Based Architecture

The library defines its API through two complementary interfaces located in the Hypervel\Encryption\Contracts namespace.

Interface Contract Diagram

Encrypter Interface

The Encrypter interface defines core encryption operations for mixed data types:

Method	Parameters	Return Type	Purpose
encrypt()	mixed $value, bool $serialize = true	string	Encrypts any PHP value with optional serialization
decrypt()	string $payload, bool $unserialize = true	mixed	Decrypts payload with optional unserialization
getKey()	None	string	Returns the current active encryption key
getAllKeys()	None	array	Returns current key plus all previous keys
getPreviousKeys()	None	array	Returns only the previous keys array

StringEncrypter Interface

The StringEncrypter interface provides string-specific convenience methods:

Method	Parameters	Return Type	Purpose
encryptString()	string $value	string	Encrypts string without serialization overhead
decryptString()	string $payload	string	Decrypts payload without unserialization

The Encrypter class implements both interfaces, providing a unified implementation. String-specific methods internally call the core encrypt() and decrypt() methods with serialize and unserialize parameters set to false.

Sources: src/Contracts/Encrypter.php7-37 src/Contracts/StringEncrypter.php src/Encrypter.php13 src/Encrypter.php124-127 src/Encrypter.php185-188

Factory Pattern and Instantiation

The EncryptionFactory class implements a factory pattern that creates fully configured Encrypter instances from application configuration.

Factory Instantiation Sequence

Factory Configuration Resolution

The factory implements a fallback strategy for configuration resolution:

Priority	Configuration Source	Keys Read	Use Case
1 (Primary)	app.key and app.cipher	app.key, app.cipher, app.previous_keys	Hyperf backward compatibility
2 (Fallback)	encryption.* namespace	encryption.key, encryption.cipher, encryption.previous_keys	Hypervel preferred approach

Key Parsing Logic

The parseKey() method handles the base64: prefix convention:

Input: "base64:SGVsbG8gV29ybGQh"
Output: base64_decode("SGVsbG8gV29ybGQh") → raw binary key

This allows keys to be safely stored in environment variables and configuration files that may not handle binary data.

Sources: src/EncryptionFactory.php17-32 src/EncryptionFactory.php49-56 src/EncryptionFactory.php63-70

Key Management Architecture

The encryption system implements a multi-key architecture supporting key rotation and backward compatibility.

Key Rotation Decryption Flow

Key Storage and Retrieval Methods

The Encrypter class provides three methods for key access:

Method	Return Value	Use Case
getKey()	Current encryption key string	Encrypting new data
getAllKeys()	Array: [currentKey, ...previousKeys]	Attempting decryption with key rotation
getPreviousKeys()	Array of previous keys only	Auditing or management operations

The previousKeys() method configures the previous keys array and validates that each key matches the cipher requirements:

$encrypter->previousKeys(['oldKey1', 'oldKey2']);

This method validates each key with Encrypter::supported() before storing them.

Encryption vs Decryption Key Usage

Operation	Keys Used	Behavior
Encryption	Current key only ($this->key)	Always uses the active key
Decryption	Current key + previous keys (getAllKeys())	Tries keys in order until success

This asymmetry ensures that new data uses the most current key while maintaining backward compatibility for data encrypted with older keys.

Sources: src/Encrypter.php283-303 src/Encrypter.php134-178 src/Encrypter.php307-320 src/Encrypter.php291-294

Exception Handling Framework

The library defines specific exception types for different failure scenarios, enabling precise error handling and debugging.

Exception Class	Trigger Condition	Recovery Strategy
MissingAppKeyException	No encryption key configured	Generate key with CLI command
EncryptException	Encryption operation failure	Verify cipher support and key validity
DecryptException	Decryption operation failure	Check payload format and key rotation

Exception hierarchy allows applications to implement graduated error handling, from specific recovery actions for missing keys to general error logging for cryptographic failures.

Sources: src/Contracts/Encrypter.php12-20