PHPackages                             ar4min/erp-agent - 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. [Utility & Helpers](/categories/utility)
4. /
5. ar4min/erp-agent

ActiveLibrary[Utility & Helpers](/categories/utility)

ar4min/erp-agent
================

ERP Agent for Control Plane communication - Heartbeat, License validation, and more

1.4.0(3mo ago)00MITPHPPHP ^8.1

Since Jan 4Pushed 3mo agoCompare

[ Source](https://github.com/ar4min/erp-agent)[ Packagist](https://packagist.org/packages/ar4min/erp-agent)[ RSS](/packages/ar4min-erp-agent/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (5)Versions (5)Used By (0)

ERP Agent
=========

[](#erp-agent)

Laravel package for connecting ERP instances to Control Plane. Handles heartbeat, license validation, and more.

Installation
------------

[](#installation)

```
composer require ar4min/erp-agent
```

Quick Setup
-----------

[](#quick-setup)

```
php artisan erp:install
```

This will:

1. Publish the configuration file
2. Ask for Control Plane credentials
3. Update your `.env` file
4. Test the connection

Manual Configuration
--------------------

[](#manual-configuration)

### 1. Publish Config

[](#1-publish-config)

```
php artisan vendor:publish --tag=erp-agent-config
```

### 2. Add to `.env`

[](#2-add-to-env)

```
CONTROL_PLANE_URL=http://your-control-plane.com
CONTROL_PLANE_TOKEN=your-service-token
INSTANCE_ID=5
LICENSE_KEY=XXXX-XXXX-XXXX-XXXX-XXXX
MACHINE_ID=unique-machine-id
```

Commands
--------

[](#commands)

### Test Connection

[](#test-connection)

```
php artisan erp:test-connection
```

### Heartbeat

[](#heartbeat)

```
# Send once
php artisan erp:heartbeat --once

# Show metrics without sending
php artisan erp:heartbeat --show

# Continuous (every 60s)
php artisan erp:heartbeat
```

### License

[](#license)

```
# Validate
php artisan erp:license

# Force refresh
php artisan erp:license --refresh

# Show status
php artisan erp:license --status
```

Scheduler Setup
---------------

[](#scheduler-setup)

Add to `app/Console/Kernel.php`:

```
protected function schedule(Schedule $schedule)
{
    // Heartbeat every minute
    $schedule->command('erp:heartbeat --once')->everyMinute();

    // License validation every 6 hours
    $schedule->command('erp:license --refresh')->everySixHours();
}
```

Middleware
----------

[](#middleware)

### License Verification

[](#license-verification)

Protect routes that require valid license:

```
// In routes/web.php
Route::middleware(['erp.license'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
    // ... other protected routes
});
```

### Response Time Tracking

[](#response-time-tracking)

Track response times for heartbeat metrics:

```
// In app/Http/Kernel.php
protected $middleware = [
    // ...
    \Ar4min\ErpAgent\Middleware\TrackResponseTime::class,
];
```

Using Services
--------------

[](#using-services)

### In Controllers

[](#in-controllers)

```
use Ar4min\ErpAgent\Services\LicenseService;
use Ar4min\ErpAgent\Services\HeartbeatService;

class DashboardController extends Controller
{
    public function index(LicenseService $license)
    {
        // Check if module is enabled
        if (!$license->hasModule('accounting')) {
            abort(403, 'Module not available');
        }

        // Get license info
        $status = $license->getStatus();

        return view('dashboard', compact('status'));
    }
}
```

### Check Module Access

[](#check-module-access)

```
$license = app(LicenseService::class);

if ($license->hasModule('hr')) {
    // HR module features
}

if ($license->hasModule('crm')) {
    // CRM module features
}
```

### Get License Status

[](#get-license-status)

```
$status = $license->getStatus();

// $status contains:
// - valid: bool
// - modules: array
// - expires_at: string
// - days_until_expiration: int
// - tenant_name: string
// - plan_name: string
// - in_grace_period: bool
// - grace_remaining: int (seconds)
```

Configuration
-------------

[](#configuration)

See `config/erp-agent.php` for all options:

```
return [
    'control_plane' => [
        'url' => env('CONTROL_PLANE_URL'),
        'token' => env('CONTROL_PLANE_TOKEN'),
        'timeout' => 30,
    ],

    'instance' => [
        'id' => env('INSTANCE_ID'),
        'machine_id' => env('MACHINE_ID'),
    ],

    'license' => [
        'key' => env('LICENSE_KEY'),
        'validation_interval' => 6 * 60 * 60, // 6 hours
        'cache_ttl' => 24 * 60 * 60, // 24 hours
        'grace_period' => 72 * 60 * 60, // 72 hours offline
    ],

    'heartbeat' => [
        'enabled' => true,
        'interval' => 60,
    ],

    'middleware' => [
        'redirect_to' => '/license-expired',
        'except' => ['login', 'logout', 'license-expired'],
    ],
];
```

Grace Period
------------

[](#grace-period)

When Control Plane is unreachable:

1. System continues working using cached license
2. Grace period starts (default: 72 hours)
3. After grace period expires, license becomes invalid

Microsoft Clarity Analytics
---------------------------

[](#microsoft-clarity-analytics)

Built-in support for Microsoft Clarity user behavior analytics (heatmaps, session recordings).

### Setup

[](#setup)

1. Get your Project ID from [clarity.microsoft.com](https://clarity.microsoft.com)
2. Add to `.env`:

```
CLARITY_ENABLED=true
CLARITY_PROJECT_ID=your-project-id
```

That's it! The script is automatically injected into all HTML responses.

### Features

[](#features)

- **Auto-injection**: No code changes needed in your views
- **Tenant tracking**: Automatically tracks `instance_id` and `tenant_name` for filtering
- **User tracking**: Tracks logged-in user ID (hashed email for privacy)
- **Route exclusion**: Login/logout pages are excluded by default
- **IP exclusion**: Exclude developer IPs from tracking

### Configuration

[](#configuration-1)

```
// config/erp-agent.php
'clarity' => [
    'enabled' => env('CLARITY_ENABLED', true),
    'project_id' => env('CLARITY_PROJECT_ID', ''),
    'auto_inject' => true,  // Inject script automatically
    'track_tenant' => true, // Track tenant/instance info
    'exclude_routes' => ['login', 'logout', 'password/*'],
    'exclude_ips' => ['127.0.0.1'],  // Developer IPs
],
```

### Filtering in Clarity Dashboard

[](#filtering-in-clarity-dashboard)

In Clarity, you can filter sessions by:

- `instance_id` - Specific ERP instance
- `tenant_name` - Tenant/company name
- `user_id` - Specific user
- `user_hash` - Hashed user email

License
-------

[](#license-1)

MIT

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance80

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~10 days

Total

4

Last Release

103d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1276b5637c3258a8d3935bfbdda577f6866c1b943626be57d926df523b783d5e?d=identicon)[ar4min](/maintainers/ar4min)

---

Top Contributors

[![ar4min](https://avatars.githubusercontent.com/u/30212253?v=4)](https://github.com/ar4min "ar4min (10 commits)")

### Embed Badge

![Health badge](/badges/ar4min-erp-agent/health.svg)

```
[![Health](https://phpackages.com/badges/ar4min-erp-agent/health.svg)](https://phpackages.com/packages/ar4min-erp-agent)
```

###  Alternatives

[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[glhd/conveyor-belt

14797.0k](/packages/glhd-conveyor-belt)[torchlight/torchlight-laravel

A Laravel Client for Torchlight, the syntax highlighting API.

120452.8k11](/packages/torchlight-torchlight-laravel)[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[ashallendesign/favicon-fetcher

A Laravel package for fetching website's favicons.

190272.4k3](/packages/ashallendesign-favicon-fetcher)

PHPackages © 2026

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