Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

MongoDB-based activity logging engine for PHP with archiving, filtering, and DI-friendly design.

License

Notifications You must be signed in to change notification settings

Maatify/mongo-activity

Repository files navigation

Version PHP Build

Monthly Downloads Total Downloads

Stars License Status Code Quality

Changelog Security

πŸ“Š maatify/mongo-activity

Advanced MongoDB-based user activity logging system Designed for tracking, querying, and archiving user/admin actions in a performant, structured, and easily searchable format.

πŸš€ Features

  • βœ… Structured activity tracking β€” supports CRUD + view actions
  • βœ… Enum-based configuration β€” roles, modules, and types
  • βœ… Optimized indexes for performance
  • βœ… Advanced filtering (user, role, module, type, keyword, date range)
  • βœ… Pagination-ready search results
  • βœ… Quarter-based archiving system (auto CRON support)
  • βœ… Environment-independent β€” use via DI container
  • βœ… Dual database mode (active + archive)

πŸ“ Project Structure

maatify-mongo-activity/
β”œβ”€β”€ src/
β”‚ β”œβ”€β”€ Contract/
β”‚ β”‚ β”œβ”€β”€ AppModuleInterface.php
β”‚ β”‚ β”œβ”€β”€ ActivityTypeInterface.php
β”‚ β”‚ └── UserRoleInterface.php
β”‚ β”œβ”€β”€ Enum/
β”‚ β”‚ β”œβ”€β”€ AppModulesEnum.php
β”‚ β”‚ β”œβ”€β”€ ActivityTypeEnum.php
β”‚ β”‚ └── UserRoleEnum.php
β”‚ β”œβ”€β”€ DTO/
β”‚ β”‚ └── ActivityRecordDTO.php
β”‚ β”œβ”€β”€ Repository/
β”‚ β”‚ β”œβ”€β”€ ActivityRepository.php
β”‚ β”‚ β”œβ”€β”€ ArchiveRepository.php
β”‚ β”‚ └── PeriodResolverRepository.php
β”‚ β”œβ”€β”€ Manager/
β”‚ β”‚ └── ActivityArchiveManager.php
β”‚ └── Helpers/
β”‚ └── ActivityPeriodResolver.php
β”œβ”€β”€ scripts/
β”‚ β”œβ”€β”€ mongo-activity-ensure-indexes.php
β”‚ └── mongo-activity-archive.php
β”œβ”€β”€ .env.example
└── composer.json

βš™οΈ Installation

🟒 Public (via Packagist)

composer require maatify/mongo-activity

πŸ” Private Repository (VCS)

If the library is private and hosted on GitHub, GitLab, or Bitbucket:

{
 "repositories": [
 {
 "type": "vcs",
 "url": "git@github.com:maatify/mongo-activity.git"
 }
 ],
 "require": {
 "maatify/mongo-activity": "dev-main"
 }
}

Then install:

composer update maatify/mongo-activity

⚠️ Make sure your user has access to the private repository via SSH or a valid Personal Access Token.

🧱 Local Development (Path Repository)

If you are developing both the project and the library locally:

{
 "repositories": [
 {
 "type": "path",
 "url": "../maatify/mongo-activity",
 "options": { "symlink": true }
 }
 ],
 "require": {
 "maatify/mongo-activity": "dev-main"
 }
}

Install with:

composer require maatify/mongo-activity:dev-main

βœ… Any change you make inside the library will instantly reflect in your project (no reinstall required).

πŸ”‘ Using a GitHub Access Token (HTTPS)

If you prefer HTTPS authentication instead of SSH:

composer config --global github-oauth.github.com ghp_yourAccessTokenHere

Then reference your repository as:

{
 "repositories": [
 {
 "type": "vcs",
 "url": "https://github.com/maatify/mongo-activity.git"
 }
 ],
 "require": {
 "maatify/mongo-activity": "dev-main"
 }
}

🧩 Environment Example (.env.example)

# Mongo Connection
MONGO_URI=mongodb://127.0.0.1:27017
# Databases
MONGO_DB_ACTIVITY=maatify_activity
MONGO_DB_ACTIVITY_ARCHIVE=maatify_activity_archive
# Collections
MONGO_COLLECTION_ACTIVITY=user_activities
# Feature toggle
MONGO_ACTIVITY_ENABLED=true

🧠 Basic Usage Example

use MongoDB\Client;
use Maatify\MongoActivity\Repository\ActivityRepository;
use Maatify\MongoActivity\DTO\ActivityRecordDTO;
use Maatify\MongoActivity\Enum\AppModulesEnum;
use Maatify\MongoActivity\Enum\UserRoleEnum;
use Maatify\MongoActivity\Enum\ActivityTypeEnum;
$client = new Client($_ENV['MONGO_URI']);
$repo = new ActivityRepository($client);
$repo->insert([
 'user_id' => 501,
 'role' => UserRoleEnum::ADMIN->value,
 'type' => ActivityTypeEnum::UPDATE->value,
 'module' => AppModulesEnum::PRODUCT->value,
 'action' => 'edit_price',
 'description' => 'Updated product #312',
 'ref_id' => 312,
 'created_at' => new MongoDB\BSON\UTCDateTime(),
]);

πŸ” Searching with Filters

$result = $repo->search(
 userId: 501,
 module: AppModulesEnum::PRODUCT,
 keyword: 'price',
 from: '2025εΉ΄11月01ζ—₯T00:00:00',
 to: '2025εΉ΄11月05ζ—₯T23:59:59',
 perPage: 10
);

πŸ—ƒοΈ Archiving Old Records

To move logs older than 6 months to quarterly archive collections:

php scripts/mongo-activity-archive.php

It automatically moves data to collections such as:

user_activities_archive_2025_0103
user_activities_archive_2025_0406
user_activities_archive_2025_0709
user_activities_archive_2025_1012

🧱 Ensuring Indexes

To (re)create indexes for faster queries:

php scripts/mongo-activity-ensure-indexes.php

This ensures indexes for:

  • user_id
  • created_at
  • module
  • role
  • type

🧩 Basic Usage Example

use MongoDB\Client;
use Maatify\MongoActivity\Repository\ActivityRepository;
use Maatify\MongoActivity\Enum\AppModulesEnum;
use Maatify\MongoActivity\Enum\UserRoleEnum;
use Maatify\MongoActivity\Enum\ActivityTypeEnum;
$client = new Client($_ENV['MONGO_URI']);
$repo = new ActivityRepository($client);
$repo->insert([
 'user_id' => 501,
 'role' => UserRoleEnum::ADMIN->value,
 'type' => ActivityTypeEnum::UPDATE->value,
 'module' => AppModulesEnum::PRODUCT->value,
 'action' => 'edit_price',
 'description' => 'Updated product #312',
 'ref_id' => 312,
 'created_at' => new MongoDB\BSON\UTCDateTime(),
]);

πŸ” Searching with Filters

$result = $repo->search(
 userId: 501,
 module: AppModulesEnum::PRODUCT,
 keyword: 'price',
 from: '2025εΉ΄11月01ζ—₯T00:00:00',
 to: '2025εΉ΄11月05ζ—₯T23:59:59',
 perPage: 10
);

πŸ—ƒοΈ Archiving Old Records

Move logs older than 6 months to quarterly archive collections:

php scripts/mongo-activity-archive.php

Creates collections such as:

user_activities_archive_2025_0103
user_activities_archive_2025_0406
user_activities_archive_2025_0709
user_activities_archive_2025_1012

🧱 Ensuring Indexes

To (re)create performance indexes:

php scripts/mongo-activity-ensure-indexes.php

Creates indexes on:

  • user_id
  • created_at
  • module
  • role
  • type

πŸ”Œ Integration with Slim Framework / DI Container

Register the Mongo Client Service

use MongoDB\Client;
use DI\ContainerBuilder;
$containerBuilder = new ContainerBuilder();
$containerBuilder->addDefinitions([
 Client::class => fn() => new Client($_ENV['MONGO_URI']),
]);
$container = $containerBuilder->build();

Register the Activity Repository

use Maatify\MongoActivity\Repository\ActivityRepository;
$containerBuilder->addDefinitions([
 ActivityRepository::class => fn($c) =>
 new ActivityRepository(
 $c->get(Client::class),
 $_ENV['MONGO_DB_ACTIVITY'],
 $_ENV['MONGO_COLLECTION_ACTIVITY']
 ),
]);

Use inside a Route

$app->post('/log', function ($request, $response) use ($container) {
 $repo = $container->get(ActivityRepository::class);
 $repo->insert([
 'user_id' => 123,
 'role' => 'admin',
 'type' => 'update',
 'module' => 'settings',
 'action' => 'change_password',
 'description' => 'Admin updated user password',
 'created_at' => new MongoDB\BSON\UTCDateTime(),
 ]);
 $response->getBody()->write('Activity logged.');
 return $response;
});

🧩 CRON Tasks Summary

Script Purpose Schedule
scripts/mongo-activity-archive.php Archive logs older than 6 months Every 6 months
scripts/mongo-activity-ensure-indexes.php Verify indexes for all collections Once after deployment

βš™οΈ Requirements

Dependency Minimum Version Notes
PHP 8.4 Native enums & readonly props
mongodb/mongodb 2+ Official MongoDB driver
vlucas/phpdotenv 5.6+ For .env loading (optional)

🧰 Dependencies

  • PHP β‰₯ 8.4
  • mongodb/mongodb β‰₯ 2
  • vlucas/phpdotenv β‰₯ 5.6

πŸͺͺ License

MIT license Β© Maatify.dev

You’re free to use, modify, and distribute this library with attribution.

πŸ§‘β€πŸ’» Maintainer

Maatify.dev https://www.Maatify.dev

AltStyle γ«γ‚ˆγ£γ¦ε€‰ζ›γ•γ‚ŒγŸγƒšγƒΌγ‚Έ (->γ‚ͺγƒͺγ‚ΈγƒŠγƒ«) /