Download the PHP package dynamik-dev/cloak-php without Composer

Cloak

A simple, extensible PHP package for redacting sensitive data from strings and revealing them later.

Installation

Requirements

• PHP 8.2+
• ext-mbstring (required by libphonenumber)

Quick Start

Using Helper Functions

Using Specific Detectors

Using the Cloak Class

For more control, use the Cloak class directly:

Configuring with Builder Methods

Built-in Detectors

Cloak provides several built-in detectors for common sensitive data types:

Phone Number Detection

Phone detection uses libphonenumber-for-php for robust international phone number validation with intelligent false positive prevention.

Features:

• International format support for all countries
• Validates actual phone numbers (not just digit patterns)
• Filters out order IDs, timestamps, serial numbers, etc.
• Handles various formats: (212) 456-7890, 212-456-7890, +44 117 496 0123

Examples:

Custom Detectors

Cloak supports two approaches for custom detectors: factory methods (concise) and direct instantiation (explicit).

Pattern-based Detector

Word-based Detector

Callable Detector

Mixed Approach

You can mix both patterns freely:

Implementing DetectorInterface

For full control, implement the DetectorInterface:

Advanced Features

Filtering Detections

Use filters to exclude certain detections from being cloaked:

Multiple Filters

Filters are applied in sequence, and all must return true for a detection to be included:

Lifecycle Callbacks

Hook into the cloaking/uncloaking process:

Encryption

Encrypt sensitive values at rest using the convenient encrypt() method:

Environment Variable Support:

Custom Encryptors:

For full control, use withEncryptor() with a custom implementation:

Storage

Default Store (ArrayStore)

By default, Cloak uses ArrayStore for in-memory storage. This is perfect for:

• Testing
• Single-request scenarios
• Simple use cases without persistence

Custom Store Implementation

For persistent storage across requests, implement StoreInterface:

Laravel Cache Store Example

Framework Integration

Custom Resolver

For framework adapters (like Laravel, Symfony, etc.), you can override how Cloak::make() resolves instances using resolveUsing():

This allows framework packages to:

• Integrate with dependency injection containers
• Use framework-specific storage drivers
• Apply framework configuration automatically
• Let developers extend and customize via container bindings

Example Laravel Service Provider:

Now developers can customize behavior through container bindings:

Clearing the Resolver:

Extending Cloak

Cloak follows a compositional architecture, making it easy to extend with custom implementations.

Custom Placeholder Generator

Create custom placeholder formats by implementing PlaceholderGeneratorInterface:

Custom Encryptor

Implement EncryptorInterface for custom encryption strategies:

Placeholder Format

Placeholders follow the format {{TYPE_KEY_INDEX}}:

• TYPE: Uppercase detector type (EMAIL, PHONE, SSN, CREDIT_CARD)
• KEY: 6-character alphanumeric unique key
• INDEX: Integer counter per type, starting at 1

Example: {{EMAIL_x7k2m9_1}}

The default format can be customized by implementing a custom PlaceholderGeneratorInterface.

API Reference

Factory Methods

Builder Methods

Lifecycle Callbacks

Core Methods

Edge Cases

• Same value appears multiple times: Reuses the same placeholder
• No detections found: Returns original text unchanged
• Missing cache on uncloak: Leaves placeholder in place
• Empty input: Returns empty string
• Overlapping patterns: All patterns are processed independently

Testing

Static Analysis

License

MIT