Download the PHP package logger/ntfy without Composer

NtfyLogger

A small PSR-3 compatible logger and client for publishing messages to ntfy.

Requirements

• PHP >= 8.1
• A PSR-18 HTTP client
• PSR-17 request and stream factories

Installation

Install the package with Composer:

Install a PSR-18 client and PSR-17 implementation if your application does not already provide them. For example:

Basic Usage

Configuration

NtfyConfiguration accepts the target topic, optional authentication, and the ntfy server URL:

For self-hosted ntfy instances, pass your own server URL:

Use either bearer-token authentication or username/password authentication. Configuring both will throw an InvalidArgumentException.

Sending Messages Directly

You can use NtfyClient without the PSR-3 logger:

Passing ntfy Parameters

The logger maps common context keys to ntfy headers:

url and ntfy_url are aliases for the notification click URL. When both are present, ntfy_url wins.

Exception Context

When the context contains an exception value and that value is a Throwable, the logger appends a compact Markdown exception report to the notification body and enables ntfy Markdown rendering.

The report renders the exception class, message, throw location, and stack trace in short line-based blocks so it remains readable on narrow phone screens. Files that belong to the application are highlighted in bold.

Directly below the original log message, the report also shows the runtime context. In a web request this is the current URL, preferably from ntfy_url; relative ntfy_url values are resolved against the request scheme and host. In CLI runs, the logger shows the command invocation when it is available through $_SERVER['argv'].

Configure exception path handling through NtfyExceptionConfiguration:

basePath is used to shorten absolute file names in the trace. applicationPaths defines which files should be highlighted. It does not filter the trace.

Use traceIncludePaths as a whitelist or traceExcludePaths as a blacklist for trace entries. Both can be combined; excluded paths take precedence. Relative application, include, and exclude paths are resolved below basePath. With no trace filters configured, all frames are retained.

For full control, pass an NtfyParams instance or an array under the ntfy context key:

Supported parameter keys are:

• title
• priority
• tags
• markdown
• click
• attach
• filename
• icon
• actions
• delay
• email
• call
• topic
• sequence_id
• cache
• firebase
• unified_push

Log Level Defaults

When no custom ntfy parameters are provided, the logger derives priority and tags from the PSR-3 level:

The default notification title is the uppercase log level, unless a title context value is provided.

Error Handling

By default, errors during HTTP transmission and response handling are suppressed (throwOnError: false). This includes transport exceptions and non-2xx HTTP responses. The call returns normally even if delivery fails; failed messages are not retried.

To propagate these errors to the application, enable throwOnError:

With this option enabled, non-2xx HTTP responses throw a RuntimeException containing the URL, status code, and response body when available. HTTP-client exceptions are rethrown unchanged.

The option applies to NtfyClient::sendMessage(), sendMessageWithAttachment(), and NtfyLogger. Configuration validation and request-construction errors still propagate regardless of this setting. NtfyExceptionConfiguration only controls how logged exceptions are rendered.

Testing

Run the PHPUnit suite with Composer:

License

Proprietary.