Getting Started

Install the package via Composer: composer require vendor/package (replace with actual package name).
Publish the configuration file: php artisan vendor:publish --provider="Vendor\Package\ServiceProvider".
Generate an encryption key if the package provides a command (e.g., php artisan package:generate-key) or set a key in .env as instructed in the config file.
Start with the simplest use case: encrypt and decrypt a string using the provided facade or helper:
```
$ciphertext = Package::encrypt('my secret');
$plaintext = Package::decrypt($ciphertext);
```
Look first at the package’s README for the facade/helper name, config options, and any Laravel‑specific integrations (model casts, validation rules, etc.).

Implementation Patterns

Model attribute encryption – Use the package’s custom cast or accessor/mutator to automatically encrypt/decrypt sensitive columns (e.g., API tokens, personal data) on save/retrieve.
Config value encryption – Store encrypted values in .env or the database and decrypt them at runtime (e.g., in a service provider or config file) to avoid plain‑text secrets.
Queue‑safe encryption – Ensure encryption keys are available to queue workers (they often run in a separate environment); pass encrypted payloads only when the worker can decrypt them.
File encryption – Encrypt files before storing on disk or S3, then decrypt on download using stream filters or temporary files.
Key rotation workflow – Implement a command or migration that re‑encrypts existing data with a new key, using the package’s ability to decrypt with old keys and encrypt with new ones.
Multi‑tenant keys – If the package supports key providers, use per‑tenant keys by resolving the key dynamically (e.g., from a tenant‑specific config or database).
Validation integration – Decrypt incoming encrypted payloads before passing them to Laravel’s validator, or create a custom validation rule that decrypts and validates in one step.

PHP 8 requirement (2.0.0) – This release updates defuse/php-encryption for PHP 8, so the package now likely requires PHP 8+. Verify your composer.json and CI environment before upgrading; this is a breaking change for PHP 7 projects.
Not for passwords – Use Laravel’s hashing (Hash::make) for passwords; encryption is reversible and unsuitable for one‑way storage.
Searchability – Encrypted fields cannot be queried with LIKE or =; consider blind indexing or deterministic encryption only if the package explicitly supports it.
Key management – Never commit encryption keys. Use environment variables or a secrets manager, and restrict access to the key file.
Performance – Encryption is CPU‑intensive; avoid encrypting large blobs in tight loops. Batch operations or use chunking where possible.
Debugging decryption failures – Catch DecryptException (or the package’s equivalent) when decrypting user‑supplied or legacy data to avoid 500 errors; log the failure and handle gracefully.
Extension points – Check if the package allows custom key providers or cipher methods; these can be useful for integrating with external KMS (AWS KMS, HashiCorp Vault).
Upgrade path – If upgrading from 1.x, test decryption of existing data with the new defuse/php-encryption version; the underlying library may have changed formats or padding. Run a full backup before rotating keys.