README

A faker implementation of NativePHP SecureStorage for web compatibility. This package provides the same interface as the native SecureStorage but uses a robust file-based cache system when running in web environments.

Quick Start

# Install the package
composer require kikiloaw/nativephp-secure-storage-faker

# Use in your code (no changes needed!)
use Native\Mobile\Facades\SecureStorage;

SecureStorage::set('auth_token', 'your-token-here');
$token = SecureStorage::get('auth_token');

That's it! The package automatically detects your environment and uses the appropriate implementation.

Features

• Automatic Environment Detection: Automatically detects if you're running in a NativePHP environment or web environment
• Seamless Fallback: Falls back to file-based cache storage when native SecureStorage is not available
• Same Interface: Provides the exact same interface as the native SecureStorage
• File-Based Cache: Uses a robust file-based cache system that works even when Laravel cache is not available
• Debug Logging: Includes debug logging for development environments
• Error Handling: Robust error handling with fallbacks
• No Code Changes Required: Works with existing code without modifications
• Testing Support: Includes methods for testing and debugging

Installation

Option 1: Install from GitHub (Recommended)

composer require kikiloaw/nativephp-secure-storage-faker

Option 2: Local Package Development

Add the package to your main project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/nativephp-secure-storage-faker"
        }
    ],
    "require": {
        "kikiloaw/nativephp-secure-storage-faker": "dev-main"
    }
}

Then run:

composer require kikiloaw/nativephp-secure-storage-faker

Option 3: Install from Packagist (Coming Soon)

Once published to Packagist, you can install it with:

composer require kikiloaw/nativephp-secure-storage-faker

Usage

Basic Usage

The package automatically detects your environment and uses the appropriate implementation:

use Native\Mobile\Facades\SecureStorage;

// These methods work the same whether you're in native or web environment
SecureStorage::set('auth_token', 'your-token-here');
$token = SecureStorage::get('auth_token');
SecureStorage::delete('auth_token');

// Additional methods available
$exists = SecureStorage::has('auth_token');
SecureStorage::clear(); // Clear all data
$keys = SecureStorage::keys(); // Get all keys

Manual Control

You can also use the manager directly for more control:

use NativePHP\SecureStorageFaker\SecureStorageManager;

// Force using faker implementation (useful for testing)
SecureStorageManager::forceFaker(true);

// Reset environment detection
SecureStorageManager::reset();

How It Works

Environment Detection

The package automatically detects the environment using several methods:

1. Checks for NativePHP environment variables
2. Tests if the native SecureStorage class exists and is functional
3. Falls back to the faker implementation if native is not available

Storage Backend

• Native Environment: Uses the actual NativePHP SecureStorage
• Web Environment: Uses a file-based cache system with automatic fallback

Cache Configuration

The faker implementation uses a robust file-based cache system that:

• Works independently of Laravel's cache configuration
• Stores data in the system's temporary directory
• Includes an index system for efficient key management
• Automatically handles serialization/deserialization
• Provides consistent behavior across different environments

Configuration

Environment Variables

You can set these environment variables to control behavior:

# Force NativePHP detection (optional)
NATIVEPHP=true

# Enable debug logging
APP_DEBUG=true

File Cache Location

The file-based cache is stored in the system's temporary directory:

• Windows: C:\Users\{username}\AppData\Local\Temp\nativephp-secure-storage-faker\
• Linux/Mac: /tmp/nativephp-secure-storage-faker/

You can customize this by setting the NATIVEPHP_SECURE_STORAGE_FAKER_CACHE_PATH environment variable.

API Reference

Methods

All methods have the same signature as the native SecureStorage:

get(string $key): mixed

Retrieves a value from secure storage.

set(string $key, mixed $value): void

Stores a value in secure storage.

delete(string $key): void

Removes a value from secure storage.

has(string $key): bool

Checks if a key exists in secure storage.

clear(): void

Clears all data from secure storage.

keys(): array

Returns all keys in secure storage.

Manager Methods

forceFaker(bool $force = true): void

Forces the use of faker implementation (useful for testing).

reset(): void

Resets environment detection cache.

Migration from Existing Code

If you're already using SecureStorage in your controllers with try-catch blocks, you can simplify your code:

Before (with try-catch):

try {
    $token = SecureStorage::get('auth_token');
} catch (\Throwable $e) {
    $token = Cache::get('native_auth_token');
}

After (simplified):

$token = SecureStorage::get('auth_token');

The package handles the fallback automatically!

Testing

The package includes methods to help with testing:

use NativePHP\SecureStorageFaker\SecureStorageManager;

// Force faker mode for testing
SecureStorageManager::forceFaker(true);

// Test your code
$result = SecureStorage::get('test_key');

// Reset after tests
SecureStorageManager::reset();

Troubleshooting

Common Issues

1. File permissions: Ensure the system temp directory is writable
2. Native detection failing: Check your NativePHP environment setup
3. Debug logs: Enable APP_DEBUG=true to see detailed logs
4. Class alias conflicts: The package automatically handles class aliasing

Debug Information

When APP_DEBUG=true, the package will log:

• Environment detection results
• File cache operations
• Fallback usage
• Error messages
• Native SecureStorage test results

Check your Laravel logs for detailed information.

Testing the Package

You can test if the package is working correctly:

use NativePHP\SecureStorageFaker\SecureStorageManager;

// Force faker mode and test
SecureStorageManager::forceFaker(true);
SecureStorageManager::set('test', 'value');
$result = SecureStorageManager::get('test');

if ($result === 'value') {
    echo "Package is working correctly!";
}

Contributing

1. Fork the repository
2. Create your feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Requirements

• PHP 8.2 or higher
• Laravel 10.x, 11.x, or 12.x
• NativePHP Mobile package (optional, for native environments)

Changelog

v1.0.0

• Initial release
• Automatic environment detection
• File-based cache system
• Full API compatibility with native SecureStorage
• Comprehensive testing support

Roadmap

• Packagist publication
• Configuration file publishing
• Additional storage backends (Redis, Database)
• Performance optimizations
• Extended debugging features

License

This package is open-sourced software licensed under the MIT license.

Credits

Created by kikiloaw for the NativePHP community.

Support

If you encounter any issues or have questions:

1. Check the troubleshooting section
2. Enable debug logging with APP_DEBUG=true
3. Open an issue on GitHub
4. Check the examples directory for usage patterns