DynamoDB driver for Laravel Auditing package

#Laravel DynamoDB Auditing

A DynamoDB driver for the Laravel Auditing package, allowing you to store audit logs in AWS DynamoDB instead of a traditional database.

#Features

• High Performance: Store audit logs in DynamoDB for better scalability
• Auto-scaling: DynamoDB handles scaling automatically
• TTL Support: Automatic cleanup of old audit logs
• Flexible Schema: NoSQL structure for varying audit data
• Query Service: Built-in service for querying audit logs
• Laravel Integration: Seamless integration with Laravel Auditing
• Queue Support: Optional queue processing for improved performance

#Installation

#1. Install via Composer

composer require infinitypaul/laravel-dynamodb-auditing

#2. Publish Configuration

php artisan vendor:publish --tag=dynamodb-auditing-config

#3. Configure Environment Variables

Add the following to your .env file:

# Enable DynamoDB auditing
AUDIT_DRIVER=dynamodb
 
# DynamoDB Configuration
DYNAMODB_AUDIT_TABLE=your-audit-table-name
DYNAMODB_AUDIT_TTL_DAYS=730
DYNAMODB_AUDIT_RECENT_DAYS=7
 
# Queue Configuration (optional - improves performance)
DYNAMODB_AUDIT_QUEUE_ENABLED=false
# DYNAMODB_AUDIT_QUEUE_CONNECTION=redis  # Optional: override default queue connection
# DYNAMODB_AUDIT_QUEUE_NAME=audits       # Optional: override default queue
 
# AWS Credentials (production)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
 
# Local Development (optional)
DYNAMODB_ENDPOINT=http://localhost:8000
DYNAMODB_ACCESS_KEY_ID=dummy
DYNAMODB_SECRET_ACCESS_KEY=dummy

#4. Configure Laravel Auditing Driver

Add the DynamoDB driver configuration to your config/audit.php file in the drivers array:

'drivers' => [
    'database' => [
        'table' => 'audits',
        'connection' => null,
    ],
    'dynamodb' => [
        'table' => env('DYNAMODB_AUDIT_TABLE', 'optimus-audit-logs'),
        'region' => env('DYNAMODB_REGION', env('AWS_DEFAULT_REGION', 'us-east-1')),
    ],
],

#5. Create DynamoDB Table

# For local development
php artisan audit:setup-dynamodb --local
 
# For production
php artisan audit:setup-dynamodb

#DynamoDB Table Structure

The package uses the following DynamoDB table structure:

#Primary Key Design

• Partition Key (PK): {auditable_type}#{auditable_id} (e.g., App\Models\Wallet#12345)
• Sort Key (SK): {timestamp}#{audit_id} (for chronological ordering)

#Global Secondary Index (GSI)

• CreatedAtIndex: For recent audit browsing
• Partition Key: audit_type (always "AUDIT")
• Sort Key: created_at (timestamp)

#Attributes

• audit_id - Unique identifier for the audit
• user_id - ID of the user who performed the action
• event - Type of event (created, updated, deleted, etc.)
• auditable_type - Model class name
• auditable_id - Model ID
• old_values - JSON of old values
• new_values - JSON of new values
• url - Request URL
• ip_address - User's IP address
• user_agent - User's browser/client
• created_at - Timestamp
• TTL - Time-to-live for automatic cleanup

#Setup

#Quick Setup (Recommended)

# Interactive installer - handles complete setup
php artisan audit:install-dynamodb
 
# For local development
php artisan audit:install-dynamodb --local
 
# Skip all confirmations
php artisan audit:install-dynamodb --local --force

The installer automatically:

• ✅ Checks for migration conflicts
• ✅ Publishes configuration
• ✅ Creates DynamoDB table with GSI
• ✅ Tests the installation
• ✅ Provides next steps

#Manual Setup (Advanced)

If you prefer step-by-step control:

#1. Create DynamoDB Table

# Setup local DynamoDB table (requires DynamoDB Local running on port 8000)
php artisan audit:setup-dynamodb --local
 
# Or force recreate if table exists
php artisan audit:setup-dynamodb --local --force

#2. Test the Setup

# Test DynamoDB audit functionality
php artisan audit:test-dynamodb
 
# Test with specific model
php artisan audit:test-dynamodb --model="App\Models\User" --id=1

#Usage

#Basic Usage

Once configured, the package works automatically with Laravel Auditing:

use OwenIt\Auditing\Contracts\Auditable;
 
class User extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;
 
    // Your model code
}

#Queue Processing (Recommended for Production)

For high-traffic applications, enable queue processing to improve performance:

# Enable queue processing (uses your existing Laravel queue configuration)
DYNAMODB_AUDIT_QUEUE_ENABLED=true
 
# Optional: Override default queue settings
# DYNAMODB_AUDIT_QUEUE_CONNECTION=redis  # Use specific queue connection
# DYNAMODB_AUDIT_QUEUE_NAME=audits       # Use specific queue name

Benefits of Queue Processing:

• Faster Response Times: Audit writes don't block user requests
• Better Scalability: Handle high-volume audit operations
• Resilience: Failed audit writes are automatically retried
• Non-blocking: User operations continue even if DynamoDB is temporarily unavailable

Queue Worker Setup:

# If using default queue configuration, just run your normal queue workers
php artisan queue:work
 
# If using a specific queue name, target that queue
php artisan queue:work --queue=audits

Note: When queue processing is enabled, audit logs are processed asynchronously, so they may not be immediately available for querying.

#Querying Audit Logs

Use the provided AuditQueryService:

use InfinityPaul\LaravelDynamoDbAuditing\AuditQueryService;
 
$auditService = app(AuditQueryService::class);
 
// Get all audits with pagination
$result = $auditService->getAllAudits(
    limit: 25,
    lastEvaluatedKey: null,
    filters: [
        'entity_type' => 'App\\Models\\Wallet',  // Required for fast search
        'entity_id' => '12345',                  // Required for fast search
        'start_date' => '2024-01-01T00:00:00',  // Optional date filtering
        'end_date' => '2024-12-31T23:59:59',    // Optional date filtering
    ]
);

#Configuration

#Environment Variables

#Configuration File

The config/dynamodb-auditing.php file allows you to customize:

• AWS credentials and region
• Table name and TTL settings
• Local vs production configurations

#TTL (Time-To-Live) Configuration

Control automatic cleanup of audit logs:

# Auto-delete after 2 years (default)
DYNAMODB_AUDIT_TTL_DAYS=730
 
# Auto-delete after 1 year
DYNAMODB_AUDIT_TTL_DAYS=365
 
# Auto-delete after 30 days
DYNAMODB_AUDIT_TTL_DAYS=30
 
# Infinite retention (never auto-delete)
DYNAMODB_AUDIT_TTL_DAYS=null

Important: Setting DYNAMODB_AUDIT_TTL_DAYS=null will keep audit logs forever, which may increase storage costs over time.

#Performance Considerations

#Why DynamoDB for Audit Logs?

DynamoDB excels at audit log storage because:

• Consistent Performance: O(1) read/write operations regardless of table size
• Horizontal Scaling: Automatically scales to handle millions of records
• Efficient Queries: Partition + Sort key design enables fast lookups
• No Performance Degradation: Unlike SQL databases, performance doesn't degrade with table growth

#Testing

Run the package tests:

composer test

#Contributing

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

#Commands

The package provides several Artisan commands for setup and testing:

#Command Examples

# 🚀 RECOMMENDED: Interactive installer (does everything)
php artisan audit:install-dynamodb --local
 
# Individual commands (if you prefer manual control)
php artisan audit:setup-dynamodb --local
php artisan audit:test-dynamodb
php artisan audit:prevent-migration --check
 
# Advanced usage
php artisan audit:setup-dynamodb --force  # Force recreate table
php artisan audit:test-dynamodb --model="App\Models\Product" --id=5
php artisan audit:prevent-migration       # Remove MySQL migrations

#Repository & Support

• 📦 GitHub Repository: https://github.com/infinitypaul/laravel-dynamodb-auditing
• 📚 Documentation: Available in the repository
• 🐛 Issues & Bug Reports: GitHub Issues
• 💬 Feature Requests: GitHub Issues

#License

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