PHPackages                             infinitypaul/laravel-dynamodb-auditing - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. infinitypaul/laravel-dynamodb-auditing

ActiveLibrary[Database & ORM](/categories/database)

infinitypaul/laravel-dynamodb-auditing
======================================

DynamoDB driver for Laravel Auditing package

v2.1.3(5mo ago)113.5k—6.3%1[1 PRs](https://github.com/infinitypaul/laravel-dynamodb-auditing/pulls)MITPHPPHP ^8.1

Since Oct 26Pushed 5mo agoCompare

[ Source](https://github.com/infinitypaul/laravel-dynamodb-auditing)[ Packagist](https://packagist.org/packages/infinitypaul/laravel-dynamodb-auditing)[ RSS](/packages/infinitypaul-laravel-dynamodb-auditing/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (5)Versions (15)Used By (0)

Laravel DynamoDB Auditing
=========================

[](#laravel-dynamodb-auditing)

A DynamoDB driver for the [Laravel Auditing](https://github.com/owen-it/laravel-auditing) package, allowing you to store audit logs in AWS DynamoDB instead of a traditional database.

Features
--------

[](#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
------------

[](#installation)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require infinitypaul/laravel-dynamodb-auditing
```

### 2. Publish Configuration

[](#2-publish-configuration)

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

### 3. Configure Environment Variables

[](#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

[](#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', 'your-audit-logs'),
        'region' => env('DYNAMODB_REGION', env('AWS_DEFAULT_REGION', 'us-east-1')),
    ],
],
```

### 5. Create DynamoDB Table

[](#5-create-dynamodb-table)

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

# For production
php artisan audit:setup-dynamodb
```

DynamoDB Table Structure
------------------------

[](#dynamodb-table-structure)

The package uses the following DynamoDB table structure:

### Primary Key Design

[](#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)

[](#global-secondary-index-gsi)

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

### Attributes

[](#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
-----

[](#setup)

### Quick Setup (Recommended)

[](#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)

[](#manual-setup-advanced)

If you prefer step-by-step control:

#### 1. Create DynamoDB Table

[](#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

[](#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
-----

[](#usage)

### Basic 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)

[](#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

[](#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
-------------

[](#configuration)

### Environment Variables

[](#environment-variables)

VariableDescriptionDefault`AUDIT_DRIVER`Audit driver to use`database``DYNAMODB_AUDIT_TABLE`DynamoDB table name`your-audit-logs``DYNAMODB_AUDIT_TTL_DAYS`Days before auto-deletion (null = infinite)`730``DYNAMODB_AUDIT_RECENT_DAYS`Days to look back for recent audit browsing`1``DYNAMODB_AUDIT_QUEUE_ENABLED`Enable queue processing for better performance`false``DYNAMODB_AUDIT_QUEUE_CONNECTION`Queue connection to use (null = use default)`null``DYNAMODB_AUDIT_QUEUE_NAME`Queue name for audit jobs (null = use default)`null``DYNAMODB_ENDPOINT`Local DynamoDB endpoint`null``AWS_ACCESS_KEY_ID`AWS access keyRequired for production`AWS_SECRET_ACCESS_KEY`AWS secret keyRequired for production`AWS_DEFAULT_REGION`AWS region`us-east-1`### Configuration File

[](#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

[](#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
--------------------------

[](#performance-considerations)

### Why DynamoDB for Audit Logs?

[](#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
-------

[](#testing)

Run the package tests:

```
composer test
```

Contributing
------------

[](#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
--------

[](#commands)

The package provides several Artisan commands for setup and testing:

CommandDescriptionOptions`audit:install-dynamodb`**🚀 Interactive installer - complete setup**`--local`, `--production`, `--force``audit:setup-dynamodb`Create DynamoDB table with GSI for audit logs`--local`, `--force``audit:test-dynamodb`Test DynamoDB audit functionality`--model`, `--id``audit:prevent-migration`Remove conflicting MySQL audit migrations`--check`### Command Examples

[](#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
------------------------

[](#repository--support)

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

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance70

Regular maintenance activity

Popularity30

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 90% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

14

Last Release

169d ago

Major Versions

v1.4.0 → v2.0.02025-10-31

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/15332137?v=4)[Paul Edward](/maintainers/infinitypaul)[@infinitypaul](https://github.com/infinitypaul)

---

Top Contributors

[![infinitypaul](https://avatars.githubusercontent.com/u/15332137?v=4)](https://github.com/infinitypaul "infinitypaul (18 commits)")[![diazsasak](https://avatars.githubusercontent.com/u/7880137?v=4)](https://github.com/diazsasak "diazsasak (2 commits)")

---

Tags

laravelawsdynamodbauditing

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/infinitypaul-laravel-dynamodb-auditing/health.svg)

```
[![Health](https://phpackages.com/badges/infinitypaul-laravel-dynamodb-auditing/health.svg)](https://phpackages.com/packages/infinitypaul-laravel-dynamodb-auditing)
```

###  Alternatives

[aws/aws-sdk-php-laravel

A simple Laravel 9/10/11/12/13 service provider for including the AWS SDK for PHP.

1.7k35.6M75](/packages/aws-aws-sdk-php-laravel)[baopham/dynamodb

Eloquent syntax for DynamoDB

4975.7M6](/packages/baopham-dynamodb)[anourvalar/eloquent-serialize

Laravel Query Builder (Eloquent) serialization

11120.2M21](/packages/anourvalar-eloquent-serialize)[kitar/laravel-dynamodb

A DynamoDB based Eloquent model and Query builder for Laravel.

193675.3k1](/packages/kitar-laravel-dynamodb)[oryxcloud/laravel-dynamodb-session-driver

DynamoDB Session Driver for Laravel 5

1460.8k](/packages/oryxcloud-laravel-dynamodb-session-driver)[betapeak/laravel-auditing-filesystem

A filesystem driver for the owen-it/laravel-auditing package. Allows storage of the audits in CSV files, across all registered Laravel disks.

166.5k](/packages/betapeak-laravel-auditing-filesystem)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)