PHPackages                             notilens/notilens - 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. [Logging & Monitoring](/categories/logging)
4. /
5. notilens/notilens

ActiveLibrary[Logging & Monitoring](/categories/logging)

notilens/notilens
=================

NotiLens — send alerts to NotiLens from PHP scripts, apps, and AI agents

0.5.1(1mo ago)132MITPHPPHP >=8.1

Since Mar 26Pushed 1mo agoCompare

[ Source](https://github.com/notilens/sdk-php)[ Packagist](https://packagist.org/packages/notilens/notilens)[ Docs](https://www.notilens.com)[ RSS](/packages/notilens-notilens/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependenciesVersions (8)Used By (0)

NotiLens
========

[](#notilens)

Send alerts to NotiLens from PHP scripts, apps, and AI agents.

Two ways to use it — pick one or both:

- **CLI** — for shell scripts, bash pipelines, any terminal workflow
- **SDK** — for PHP projects (import and call directly in code)

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

[](#installation)

```
composer global require notilens/notilens
```

Or per-project:

```
composer require notilens/notilens
```

---

CLI
===

[](#cli)

1. Setup
--------

[](#1-setup)

Get your token and secret from the [NotiLens dashboard](https://www.notilens.com).

```
notilens init --name my-app --token YOUR_TOKEN --secret YOUR_SECRET
```

This saves credentials to `~/.notilens_config.json`. All future commands read from there — no need to pass token/secret again.

**Multiple sources** (each notifies a different topic):

```
notilens init --name scraper --token TOKEN_A --secret SECRET_A
notilens init --name mailer  --token TOKEN_B --secret SECRET_B
```

**List / remove:**

```
notilens sources
notilens remove-source my-app
```

---

2. Notify
---------

[](#2-notify)

The simplest way to send a notification — no task or run context needed:

```
notilens notify order.placed    "Order #1234"      --name my-app
notilens notify disk.space.full "Only 1GB left"    --name my-app --type warning
notilens notify report.ready    "Report is ready"  --name my-app --download_url https://example.com/report.pdf
```

---

3. Commands
-----------

[](#3-commands)

`--task` is a semantic label (e.g. `email`, `report`). Each `task.start` creates an isolated run internally — concurrent executions of the same label never conflict.

### Task Lifecycle

[](#task-lifecycle)

```
notilens queue    --name my-app --task email
notilens start    --name my-app --task email
notilens progress "Fetching data"  --name my-app --task email
notilens loop     "Step 3 of 10"   --name my-app --task email
notilens retry    --name my-app --task email
notilens pause    "Rate limited"   --name my-app --task email
notilens resume   "Resuming"       --name my-app --task email
notilens wait     "Awaiting tool"  --name my-app --task email
notilens stop     --name my-app --task email
notilens complete "All done"       --name my-app --task email
notilens error    "Step 3 failed"  --name my-app --task email
notilens fail     "Unrecoverable"  --name my-app --task email
notilens timeout  "Took too long"  --name my-app --task email
notilens cancel   "User cancelled" --name my-app --task email
notilens terminate "Out of memory" --name my-app --task email
```

`task.start` prints the internal `run_id` to stdout.

### Output Events

[](#output-events)

```
notilens output.generate "Report ready"     --name my-app --task email
notilens output.fail     "Model unavailable" --name my-app --task email
```

### Input / Human-in-the-loop

[](#input--human-in-the-loop)

```
notilens input.required "Please confirm" --name my-app --task email
notilens input.approve  "Confirmed"      --name my-app --task email
notilens input.reject   "Rejected"       --name my-app --task email
```

### Metrics

[](#metrics)

```
notilens metric tokens=512 cost=0.003 --name my-app --task email
notilens metric.reset tokens          --name my-app --task email
notilens metric.reset                 --name my-app --task email
```

### Custom Events

[](#custom-events)

```
notilens track order.placed "Order #1234" --name my-app
```

---

4. force\_send (CLI)
--------------------

[](#4-force_send-cli)

By default NotiLens routes notifications through ML-based filtering. Use `--force_send true` to bypass ML and deliver immediately, or `--force_send false` to force ML routing even on high-signal commands.

CommandDefault`notilens notify``true``notilens fail``true``notilens timeout``true``notilens terminate``true``notilens input.required``true``notilens output.generate``true``notilens output.fail``true`Everything else`false````
# Override to route through ML
notilens fail "Error" --name my-app --task email --force_send false

# Override to bypass ML
notilens progress "Critical step" --name my-app --task email --force_send true
```

---

SDK
===

[](#sdk)

1. Setup
--------

[](#1-setup-1)

```
use NotiLens\NotiLens;

// Pass credentials directly
$nl = NotiLens::init('my-app', token: 'YOUR_TOKEN', secret: 'YOUR_SECRET');

// Or via env vars: NOTILENS_TOKEN / NOTILENS_SECRET
$nl = NotiLens::init('my-app');

// All options
$nl = NotiLens::init(
    name:     'my-app',
    token:    'YOUR_TOKEN',   // required (or env var)
    secret:   'YOUR_SECRET',  // required (or env var)
    stateTtl: 86400,          // optional — orphaned state TTL in seconds (default: 86400 / 24h)
);
```

---

2. Notify
---------

[](#2-notify-1)

The simplest way to send a notification — no task or run context needed:

```
$nl->notify('order.placed', 'Order #1234');
$nl->notify('disk.space.full', 'Only 1GB left', level: 'warning');
$nl->notify('report.ready', 'Your report is ready',
    downloadUrl: 'https://example.com/report.pdf',
    tags: 'report,weekly',
);

// Also available on a run
$run->notify('deploy.done', 'Deployed to production',
    openUrl: 'https://example.com/deploy/123',
);
```

---

3. Task Lifecycle
-----------------

[](#3-task-lifecycle)

`$nl->task($label)` creates a `Run` — an isolated execution context. Multiple concurrent runs of the same label never conflict.

```
$run = $nl->task('email');  // create a run for the "email" task
$run->queue();               // optional — pre-start signal
$run->start();               // begin the run

$run->progress('Fetching data');
$run->loop('Processing item 42');
$run->retry();
$run->pause('Rate limited');
$run->resume('Resuming work');
$run->wait('Waiting for tool response');

$run->stop();
$run->error('Step failed, retrying');  // non-fatal, run continues

// Terminal — pick one
$run->complete('All done');
$run->fail('Unrecoverable error');
$run->timeout('Timed out after 5m');
$run->cancel('Cancelled by user');
$run->terminate('Force-killed');
```

---

4. Input / Output
-----------------

[](#4-input--output)

```
$run->inputRequired('Approve deployment?');
$run->inputApproved('Approved');
$run->inputRejected('Rejected');

$run->outputGenerated('Report ready');
$run->outputFailed('Rendering failed');
```

---

5. Metrics
----------

[](#5-metrics)

```
$run->metric('tokens', 512);
$run->metric('tokens', 128);   // now 640
$run->metric('cost', 0.003);

$run->resetMetrics('tokens');  // reset one
$run->resetMetrics();          // reset all
```

Automatic Timing
----------------

[](#automatic-timing)

NotiLens automatically tracks task timing. These fields are included in every notification's `meta` payload when non-zero:

FieldDescription`total_duration_ms`Wall-clock time since `start``queue_ms`Time between `queue` and `start``pause_ms`Cumulative time spent paused`wait_ms`Cumulative time spent waiting`active_ms`Active time (`total − pause − wait`)---

6. Custom Events
----------------

[](#6-custom-events)

```
$run->track('custom.event', 'Something happened');
$run->track('custom.event', 'With meta', ['key' => 'value']);

$nl->track('app.deployed', 'v2.3.1 deployed');
```

---

7. force\_send (SDK)
--------------------

[](#7-force_send-sdk)

By default NotiLens routes notifications through ML-based filtering. Pass `forceSend: true` to bypass ML and deliver immediately.

MethodDefault`notify()``true``fail()``true``timeout()``true``terminate()``true``inputRequired()``true``outputGenerated()``true``outputFailed()``true`Everything else`false`All methods accept `$forceSend` as an overridable parameter:

```
// Override a default-true method to go through ML
$run->fail('Error', false);
$run->timeout('Slow', false);

// Override a default-false method to bypass ML
$run->progress('Critical step', true);
$run->complete('Done', true);

// Via named params for notify/track
$nl->notify('low.priority', 'FYI', forceSend: false);
$run->track('custom.event', 'msg', forceSend: true);
```

---

Full Example
------------

[](#full-example)

```
use NotiLens\NotiLens;

$nl  = NotiLens::init('summarizer', token: 'TOKEN', secret: 'SECRET');
$run = $nl->task('report');
$run->start();

try {
    $run->progress('Fetching PDF');
    $result = $llm->complete($prompt);
    $run->metric('tokens', $result->usage->total_tokens);
    $run->outputGenerated('Summary ready');
    $run->complete('All done');
} catch (\Throwable $e) {
    $run->fail($e->getMessage());
}
```

Requirements
------------

[](#requirements)

- PHP >= 8.1

License
-------

[](#license)

MIT — [notilens.com](https://www.notilens.com)

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance93

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

 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 ~9 days

Total

7

Last Release

35d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/34e46a4378fa735ccea54d3ef6378412ad00a87e71cc47e5ddefec6fa4ecf7f2?d=identicon)[solvzatechnologies](/maintainers/solvzatechnologies)

---

Top Contributors

[![notilens](https://avatars.githubusercontent.com/u/266655403?v=4)](https://github.com/notilens "notilens (15 commits)")

---

Tags

ai-agentsai-toolsmonitoringnotifyclimonitoringnotificationsalertsai-agentnotilens

### Embed Badge

![Health badge](/badges/notilens-notilens/health.svg)

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

###  Alternatives

[analog/analog

Fast, flexible, easy PSR-3-compatible PHP logging package with dozens of handlers.

3511.6M24](/packages/analog-analog)[datadog/php-datadogstatsd

An extremely simple PHP datadogstatsd client

19026.4M15](/packages/datadog-php-datadogstatsd)[ohdearapp/ohdear-cli

A standalone CLI tool for Oh Dear monitoring.

1401.3k](/packages/ohdearapp-ohdear-cli)

PHPackages © 2026

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