Download the PHP package dibakar/activity-scope without Composer

Activity Scope — Audit Trail & Activity Logging for Laravel

📋 Table of Contents

• About
• Features
• Requirements
• Installation
• Configuration
• Usage
  • Basic Usage
  • Model Integration
  • Query Scopes
  • Advanced Features
  • Security & Privacy
  • Events & Hooks
• Examples
• API Reference
• Testing
• Contributing
• Changelog
• License
• Support

📖 About {#about}

Activity Scope is a high-performance audit trail and activity logging system for Laravel. It allows you to effortlessly track user actions, monitor Eloquent model changes, and maintain a historical record of your application's state—all while prioritizing privacy and high performance.

📚 Check out the API.md for a full list of available builder methods and scopes.

✨ Features {#features}

• 🔧 Fluent Activity Builder: Expressive, chainable API for logging any event with ease
• 🤖 Smarter Auto-Actor: Automatically resolves the current authenticated user as the actor
• 🔒 Privacy First: Built-in IP anonymization and recursive sensitive metadata scrubbing
• 🧩 Independent Modular Traits:
  • HasActivities: Core relationships and log retrieval
  • LogsActivity: Zero-config auto-logging for Eloquent events
• 🔗 Relationship Support: Log activity across model relationships or on multiple models at once
• 📝 Human-Readable Logs: Integrated MessageBuilder to transform raw logs into meaningful alerts
• 🛡️ Security Ready: Dedicated security event logging for audits
• 🎯 Type Safety: Built with PHP 8.1+ features and strict typing

📋 Requirements {#requirements}

• PHP: >= 8.1
• Laravel: ^10.0|^11.0|^12.0
• Illuminate/Database: ^10.0|^11.0|^12.0
• Illuminate/Support: ^10.0|^11.0|^12.0

🚀 Installation {#installation}

You can install the package via composer:

Quick Setup

Publish the config and migrations with our handy install command:

Manual Setup

Alternatively, you can publish them manually via vendor:publish:

⚙️ Configuration {#configuration}

After publishing the config file, you can customize the behavior in config/activityscope.php:

🛠 Usage {#usage}

Basic Usage

Using the Global Helper

The most common way to log activity is using the activity() helper:

Automatic Actor Resolution

By default, the package automatically attaches auth()->user() to any activity. You can override this manually:

Model Integration

Automatic Model Logging

Add the LogsActivity trait to your model for automatic auditing of created, updated, and deleted events:

Manual Model Integration

Use the HasActivities trait to gain access to relationships and a model-contextual activity builder:

Advanced Model Configuration

Customize what gets logged and when:

Query Scopes

Filtering Activities

Use the powerful query scopes to retrieve specific activities:

Advanced Querying

Advanced Features

Control Flow Logic

Utilize fluent methods to control when and how activities are logged:

Security & Privacy

Built-in tools to handle sensitive data and privacy requirements:

Status & Severity

Categorize activities by outcome and importance:

Metadata & Context

Rich context management for detailed audit trails:

Events & Hooks

Human-Readable Messages

Transform any activity record into a readable string using the integrated MessageBuilder:

Event System

Listen to activity events to trigger additional actions:

Custom Event Handlers

📚 Examples {#examples}

Check out the examples/ directory for comprehensive usage examples:

• basic_usage.php - Simple logging examples
• model_integration.php - Model trait usage
• query_scopes.php - Advanced querying
• complex_workflows.php - Real-world scenarios

Quick Example

🧪 Testing {#testing}

Basic Assertions

You can use the built-in test helper to assert activities were logged:

Advanced Testing

Test Helpers

Run package tests with:

For code analysis:

📖 API Reference {#api-reference}

For a comprehensive list of all available methods, scopes, and advanced features, check out our detailed API Documentation.

Quick Reference

🤝 Contributing {#contributing}

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Guidelines

• Follow PSR-12 coding standards
• Add tests for new features
• Update documentation for any API changes
• Ensure all tests pass before submitting

📝 Changelog {#changelog}

Please see CHANGELOG.md for more information on what has changed recently.

📄 License {#license}

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support {#support}

• Issues: GitHub Issues
• Documentation: API Reference
• Examples: Check the examples/ directory

Made by Dibakar Mitra