Forem: Lepres KIKOUNGA

How Thinking in UX Forces You to Build Better UI — Even If You're Not a Designer

Lepres KIKOUNGA — Mon, 09 Mar 2026 20:55:28 +0000

Most developers I know can explain the difference between good and bad code instantly. Clean abstractions, clear naming, separation of concerns — they have a vocabulary for it and an instinct for it.

Ask those same developers to explain why their app looks the way it does, and the answer is usually some version of: "I'm not a designer."

That answer reveals a misunderstanding. The biggest UI problems in developer-built applications are not aesthetic problems. They are thinking problems. They come from building an interface the way you build a data model — from the inside out — instead of the way a user experiences it, from the outside in.

UX thinking is not about taste. It's a framework. And once you have it, it changes every decision you make before you write a single line of interface code.

Start with the job, not the screen

The most common mistake developers make when building UI is starting with data. You have a User object with twelve fields, so you build a profile screen that shows twelve fields. You have a list of orders, so you build a screen that lists orders. The interface becomes a projection of your data model.

Users don't experience your data model. They arrive at a screen with a specific goal — something they want to do or find — and they leave once that goal is accomplished. Every element that doesn't serve that goal is noise.

Before designing any screen, write down one sentence:

What does the user need to accomplish here?

"The user wants to track their active delivery."
"The user wants to pay for their order."
"The user wants to find a past invoice."

Now design backward from that job. What is the last action before the job is done? What comes before that? Keep working backward until you have the minimum number of steps required. That sequence is your flow. Every screen, every field, every button you add beyond that minimum needs to earn its place.

A concrete example. You're building a checkout flow. Your order model has: items, quantities, delivery address, billing address, payment method, promo code, gift message, and order notes.

The user's job is: complete the purchase as quickly as possible.

From that job, you immediately know several things:

Billing address can default to delivery address (one less screen for most users)
Promo code, gift message, and order notes are secondary — they should be collapsible or optional, not prominent steps in the main flow
The primary action on every screen should be obvious and require no hesitation

You haven't touched typography or color. You've made the flow better by thinking about what the user is actually there to do.

Friction is a tax on the user

Every click, every field, every decision you ask the user to make has a cost. Not a metaphorical cost — a real one. Attention, time, effort. Users have a limited budget of all three, and they spend it on every interaction with your interface.

Some friction is necessary. You need a delivery address. You need payment confirmation. But developers introduce friction constantly without realizing it, because they're not accounting for the user's budget — they're just implementing requirements.

Ask yourself for every step, every field, every modal: Does the user need to do this, or is this something I can handle for them?

A few patterns that eliminate friction without any design skill required:

Smart defaults. If 90% of your users choose the same option, make it the default. Don't make everyone dismiss the other options to get to what they want.

Pre-fill what you know. If the user is logged in, you know their name, their email, possibly their address. Don't ask for what you already have.

Progressive disclosure. Show the options that apply to the current context. Hide what doesn't. A user creating a basic account doesn't need to see enterprise billing settings.

Forgiving input. Accept phone numbers with spaces, dashes, or parentheses. Accept dates in multiple formats. Don't force users to format their input for the convenience of your parser.

None of these are visual design decisions. They are logic decisions — the kind developers are good at — applied to the user's experience instead of the implementation.

Hierarchy is communication, not decoration

Visual hierarchy is the hardest concept to understand without design training, because it looks like an aesthetic choice. It isn't. It's information.

Every element on a screen has a level of importance relative to the user's current job. Visual hierarchy is the mechanism by which you communicate those levels — making important things prominent, secondary things less so, and supporting information quiet.

You don't need design instinct to apply this. You need to know what matters most on each screen, and then ask: Does the visual weight of each element match its actual importance?

Take a typical form screen. It usually has:

A title or header
Several input fields
A primary action button (Submit, Continue, Save)
A secondary action (Cancel, Go back)
Possibly error or helper text

The primary action is the most important element — it's how the user completes their job. It should be the most visually prominent thing on the screen. The secondary action matters, but less. It should be visible but clearly less prominent than the primary. Helper text exists to prevent mistakes; it should be readable but shouldn't compete for attention with the fields.

If your Submit button is the same size, color, and weight as your Cancel button, you've told the user those two actions are equally important. They are not. That's a hierarchy failure — and it has nothing to do with aesthetics. It's a factual mismatch between importance and visual representation.

Correcting it doesn't require design skills. It requires being honest about what matters on each screen and making sure the interface reflects that honestly.

Consistency is the easiest win

Of all the principles in this article, this one is the most straightforward to implement and has one of the highest impacts on how professional an application feels.

Inconsistency forces users to re-evaluate every screen they encounter. When a button looks different here than it does there, when spacing changes from section to section, when the same type of feedback uses different colors in different places, users cannot build a mental model of your application. Every screen feels like the first screen.

Consistency removes that cognitive load. When everything behaves predictably, users stop thinking about the interface and start thinking about their task. That's exactly where you want their attention.

You don't need a full design system to be consistent. You need a small set of rules, defined early and applied without exception:

Four or five spacing values. Use multiples of a base unit (4px or 8px works well). Apply them everywhere — padding, margins, gaps between elements.
Two or three text sizes. A heading size, a body size, and possibly a small/label size. Don't invent new sizes for individual screens.
One primary action style. One secondary action style. Use them consistently.
A consistent color for positive feedback, one for errors, one for warnings. Don't reuse them for anything else.

Define those rules in constants in your code. Reference the constants everywhere. Never hardcode a size or color directly.

That's it. No design tool required. Just discipline.

Putting it together: one screen, from scratch

Imagine you're building a screen that lets a user view and cancel an active subscription.

Step 1 — Define the job.
The user wants to cancel their subscription. (A secondary job: confirm what they're currently paying for before deciding.)

Step 2 — Minimum flow.
Show current plan details → Offer cancellation → Confirm → Done. Four steps maximum.

Step 3 — Eliminate friction.
Don't make the user re-enter their password to cancel. Don't hide the cancel option behind three menus. Don't interrupt the flow with upsell screens (or if you must, make them skippable in one tap). Pre-fill any information you already have in the confirmation step.

Step 4 — Apply hierarchy.
The current plan name and price are most important — they're what the user came to see. The Cancel Subscription button should be clearly visible but styled as a destructive action, not the primary CTA. Keep My Subscription should be the prominent action if you want to reduce churn. Error and success states should be unambiguous.

Step 5 — Be consistent.
Same spacing as everywhere else. Same button styles. Same color for the destructive action as every other destructive action in the app.

You haven't made a single aesthetic decision. You've built a screen that works well because you thought clearly about what the user is there to do.

The skill you already have

Developers reason about systems every day. You think about inputs and outputs, about what matters and what doesn't, about removing unnecessary steps from a process. That's UX thinking. It's the same mental model applied to a different layer.

The gap is not skill. It's habit — the habit of asking "what does the user need here?" before asking "how do I implement this?"

Build that habit, and the interface quality follows.

Not because you became a designer. Because you stopped building for your implementation and started building for the person on the other side of the screen.

Detect User Inactivity System-Wide on Android with AccessibilityService

Lepres KIKOUNGA — Tue, 24 Feb 2026 16:12:41 +0000

Here is a scenario you will run into sooner or later building Android kiosk apps, digital signage, or any long-running background service: you need to know when the user has not interacted with the device for a certain amount of time. Maybe you want to show content after 20 seconds of idle time, then dismiss it the instant someone touches the screen again.

You start looking for the right API. PowerManager.isInteractive() tells you if the screen is on, not if anyone is actually using it. onUserInteraction() in an Activity only fires when your own Activity is in the foreground. There is no getLastInteractionTime() anywhere in the SDK.

Eventually you land on AccessibilityService, try it, and it works perfectly. This article walks you through exactly how, and why.

What is AccessibilityService really doing here

AccessibilityService is designed for assistive technology — screen readers, switch access, voice control. That is its primary documented purpose. But what makes it useful for our use case is a side effect of how it works: the service receives accessibility events from any app on the device, system-wide, while running in the background.

These events include:

TYPE_TOUCH_INTERACTION_START — user touched the screen
TYPE_VIEW_CLICKED — user tapped a view
TYPE_VIEW_SCROLLED — user scrolled content
TYPE_GESTURE_DETECTION_START — a gesture was recognized

In other words: as long as the screen is on and the user is doing something, your service receives a steady stream of events. When that stream goes quiet, the user is idle.

A word on Google Play policy: AccessibilityService is a privileged API. Google Play has strict rules about what justifies its use. For kiosk apps, enterprise deployments, or apps distributed outside the Play Store, this is a legitimate tool. Never use it to collect sensitive data or surveil users. If you are building a consumer app, check whether your use case actually qualifies before submitting to the store.

Prerequisites

Android Studio Hedgehog or later
Min SDK 26+
Kotlin 1.9+
Basic familiarity with Android Services

Step 1 — Declare the service in the Manifest

The service requires the BIND_ACCESSIBILITY_SERVICE permission. Android enforces this at the system level — only the OS can bind to your service, not other apps.

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.BIND_ACCESSIBILITY_SERVICE" />

<service
    android:name=".service.UserActivityService"
    android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"
    android:exported="true">

    <intent-filter>
        <action android:name="android.accessibilityservice.AccessibilityService" />
    </intent-filter>

    <meta-data
        android:name="android.accessibilityservice"
        android:resource="@xml/accessibility_service_config" />
</service>

android:exported="true" is required because the system binds to the service from outside your process.

Step 2 — Configure the service with an XML file

Create res/xml/accessibility_service_config.xml. This file is how you tell Android what events to deliver and how to present the service to the user in Settings.

<?xml version="1.0" encoding="utf-8"?>
<accessibility-service
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:accessibilityEventTypes="typeAllMask"
    android:accessibilityFeedbackType="feedbackGeneric"
    android:accessibilityFlags="flagIncludeNotImportantViews"
    android:canRetrieveWindowContent="false"
    android:description="@string/accessibility_service_description"
    android:summary="@string/accessibility_service_summary"
    android:notificationTimeout="100"
    android:packageNames="@null" />

Each attribute is a deliberate choice:

Attribute	Value	Why
`accessibilityEventTypes`	`typeAllMask`	We want any interaction event, so we use the broad mask
`canRetrieveWindowContent`	`false`	We do not need to read screen content — only that an event happened. Always set this to `false` unless you specifically need it.
`packageNames`	`@null`	Listen to events from all packages, not just our own
`notificationTimeout`	`100`	Minimum ms between events. Prevents flooding without missing real interactions

Add the string resources referenced above:

<!-- res/values/strings.xml -->
<string name="accessibility_service_description">
    Detects user interactions to manage screen idle state.
</string>
<string name="accessibility_service_summary">
    Required to detect when the screen is idle.
</string>

These strings appear in the Accessibility settings page. Write them clearly — the user will read them before enabling your service.

Step 3 — Implement the AccessibilityService

class UserActivityService : AccessibilityService() {

    interface ActivityCallback {
        fun onUserActivity()
    }

    companion object {
        private var activityCallback: ActivityCallback? = null

        fun setActivityCallback(callback: ActivityCallback?) {
            activityCallback = callback
        }

        fun isServiceEnabled(context: Context): Boolean {
            val componentName = ComponentName(context, UserActivityService::class.java)
            val enabledServices = Settings.Secure.getString(
                context.contentResolver,
                Settings.Secure.ENABLED_ACCESSIBILITY_SERVICES
            ) ?: return false

            val splitter = TextUtils.SimpleStringSplitter(':')
            splitter.setString(enabledServices)

            while (splitter.hasNext()) {
                val enabled = ComponentName.unflattenFromString(splitter.next())
                if (enabled == componentName) return true
            }
            return false
        }
    }

    override fun onServiceConnected() {
        serviceInfo = serviceInfo.apply {
            eventTypes =
                AccessibilityEvent.TYPE_TOUCH_INTERACTION_START or
                AccessibilityEvent.TYPE_VIEW_CLICKED or
                AccessibilityEvent.TYPE_VIEW_SCROLLED or
                AccessibilityEvent.TYPE_GESTURE_DETECTION_START
        }
    }

    override fun onAccessibilityEvent(event: AccessibilityEvent?) {
        activityCallback?.onUserActivity()
    }

    override fun onInterrupt() {}

    override fun onDestroy() {
        super.onDestroy()
        activityCallback = null
    }
}

A few things worth unpacking.

We override serviceInfo inside onServiceConnected() to narrow down the event types at runtime. The XML config sets the initial filter, but you can refine it programmatically here. For inactivity detection, the four event types above cover every meaningful user interaction without the noise of TYPE_WINDOW_STATE_CHANGED or TYPE_ANNOUNCEMENT.

The companion object is a static bridge between the service and your app. Android manages the AccessibilityService lifecycle independently — you cannot instantiate it yourself. So instead of trying to hold a reference to the service, you register a callback on the companion object, and the service calls it when events arrive.

Step 4 — Build the InactivityDetector

The service tells you that the user is active. The InactivityDetector handles the how long — tracking elapsed time and firing callbacks when the user crosses the idle threshold.

class InactivityDetector(
    private val timeoutSeconds: Int,
    private val callback: Callback
) {

    interface Callback {
        fun onInactive()
        fun onActive()
    }

    private val handler = Handler(Looper.getMainLooper())
    private var lastActivityTime = System.currentTimeMillis()
    private var isActive = true
    private var isRunning = false

    private val checkRunnable = object : Runnable {
        override fun run() {
            if (!isRunning) return
            checkInactivity()
            handler.postDelayed(this, CHECK_INTERVAL_MS)
        }
    }

    fun start() {
        if (isRunning) return
        isRunning = true
        lastActivityTime = System.currentTimeMillis()
        handler.postDelayed(checkRunnable, CHECK_INTERVAL_MS)
    }

    fun stop() {
        isRunning = false
        handler.removeCallbacks(checkRunnable)
    }

    fun onUserActivity() {
        lastActivityTime = System.currentTimeMillis()
        if (!isActive) {
            isActive = true
            callback.onActive()
        }
    }

    private fun checkInactivity() {
        val elapsed = System.currentTimeMillis() - lastActivityTime
        if (isActive && elapsed >= timeoutSeconds * 1000L) {
            isActive = false
            callback.onInactive()
        }
    }

    companion object {
        private const val CHECK_INTERVAL_MS = 1000L
    }
}

The check runs on the main thread via Handler(Looper.getMainLooper()). This is intentional: any UI changes triggered by the callbacks need to run on the main thread anyway, and keeping state management single-threaded eliminates a class of race conditions.

onActive() only fires on the transition from inactive to active. If the user is already active and sends another event, we silently update lastActivityTime without re-firing the callback. Without this guard, rapid interactions would flood your consumer with redundant onActive() calls.

Step 5 — Wire it up in a background service

class ContentService : Service(), UserActivityService.ActivityCallback {

    private lateinit var inactivityDetector: InactivityDetector

    override fun onCreate() {
        super.onCreate()

        inactivityDetector = InactivityDetector(
            timeoutSeconds = 20,
            callback = object : InactivityDetector.Callback {
                override fun onInactive() {
                    showContent()
                }
                override fun onActive() {
                    hideContent()
                }
            }
        )

        UserActivityService.setActivityCallback(this)
        inactivityDetector.start()
    }

    override fun onUserActivity() {
        inactivityDetector.onUserActivity()
    }

    override fun onDestroy() {
        super.onDestroy()
        UserActivityService.setActivityCallback(null)
        inactivityDetector.stop()
    }

    override fun onBind(intent: Intent?): IBinder? = null

    private fun showContent() { /* your logic */ }
    private fun hideContent() { /* your logic */ }
}

The setActivityCallback(null) call in onDestroy() is not optional. The AccessibilityService and your ContentService have independent lifecycles managed by Android. If ContentService is destroyed while UserActivityService is still running, the stale reference will cause a crash or silent misbehavior when the next event fires.

Step 6 — Handle screen on/off events

AccessibilityService only delivers events when the screen is active and the device is being used. If the screen turns off, you stop receiving events — but the InactivityDetector is still counting. You need to handle screen state separately.

private val screenReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        when (intent?.action) {
            Intent.ACTION_SCREEN_ON   -> inactivityDetector.onUserActivity()
            Intent.ACTION_USER_PRESENT -> inactivityDetector.onUserActivity() // after unlock
            Intent.ACTION_SCREEN_OFF  -> hideContent()
        }
    }
}

val filter = IntentFilter().apply {
    addAction(Intent.ACTION_SCREEN_ON)
    addAction(Intent.ACTION_SCREEN_OFF)
    addAction(Intent.ACTION_USER_PRESENT)
}
registerReceiver(screenReceiver, filter)

Unregister in onDestroy():

unregisterReceiver(screenReceiver)

ACTION_USER_PRESENT fires after the lock screen is dismissed, which is different from ACTION_SCREEN_ON. Always handle both if your app needs to react correctly to device unlock.

Step 7 — Check if the service is enabled and guide the user

AccessibilityService requires the user to manually enable it in Settings → Accessibility. There is no runtime permission dialog — you must redirect them yourself.

fun ensureAccessibilityEnabled(activity: Activity) {
    if (UserActivityService.isServiceEnabled(activity)) return

    AlertDialog.Builder(activity)
        .setTitle("Enable accessibility access")
        .setMessage(
            "This app needs accessibility permission to detect screen idle state. " +
            "Tap 'Open Settings', find this app in the list, and enable it."
        )
        .setPositiveButton("Open Settings") { _, _ ->
            activity.startActivity(Intent(Settings.ACTION_ACCESSIBILITY_SETTINGS))
        }
        .setNegativeButton("Not now", null)
        .show()
}

Do not cache the result of isServiceEnabled(). The user can revoke accessibility access at any point from Settings, without any callback to your app. Re-check it each time your service starts, and handle gracefully the case where it gets disabled while your service is running.

Common pitfalls

The service is declared but receives no events: The user has not enabled it in Settings. Your isServiceEnabled() check should catch this on startup. There is no workaround for the manual step — it is an intentional Android security requirement.

Events stop arriving after some time: Android's battery optimization can kill background services. For anything that needs to run continuously, make your service a foreground service with a persistent notification.

onAccessibilityEvent is called on every single interaction across the whole system: That is expected behavior. The InactivityDetector handles the debouncing — do not try to filter events in onAccessibilityEvent unless you have a specific reason.

You see a crash after ContentService is destroyed: You forgot to call setActivityCallback(null) in onDestroy(). The AccessibilityService held a reference to your destroyed object and tried to call a method on it.

Conclusion

AccessibilityService solves a real problem that has no clean alternative in the Android SDK: knowing that the user is interacting with the device from a background service, regardless of which app is in the foreground.

The architecture is clean once you have the three pieces in place: the AccessibilityService listens to system-wide events and forwards them via a callback, the InactivityDetector manages the timeout state machine, and your service reacts to onInactive() and onActive(). Each piece has one job, and the separation makes it easy to test each in isolation.

This pattern works well for kiosk apps, digital signage players, ambient display apps, and any use case where you need to react to user presence without controlling the foreground. If that sounds like your situation, this is the right approach.

If you found this useful or ran into something I did not cover, drop a comment below.

Build a Complete PKI from Scratch in Node.js

Lepres KIKOUNGA — Tue, 17 Feb 2026 13:25:52 +0000

Intro

When I needed to implement document signing in a production application, I quickly realized that most guides online either:

Rely on OpenSSL CLI commands and child_process.execSync (fragile, platform-dependent)
Use outdated libraries that haven't been maintained since 2018
Skip the "why" entirely and just paste code

So I built it myself — a complete PKI (Public Key Infrastructure) using node-forge for certificate generation combined with Node.js built-in crypto for key management. This post walks you through every step and explains a real compatibility issue you will hit if you use node-forge alone.

By the end, you'll have a working PKI that:

Issues X.509 certificates programmatically
Encrypts private keys securely at rest
Signs PDFs or any data
Handles the node-forge decryption bug correctly

What is a PKI (and why should you care)?

A PKI is the infrastructure that makes digital trust possible. Before diving into code, it helps to understand how the pieces fit together.

Think of it like a notary system. When you need to prove your identity for a legal document, you don't ask a random person to vouch for you — you go to a recognized institution that everyone trusts. That institution verifies your identity and stamps the document.

A PKI works the same way, but digitally:

Certificate Authority (CA) — the trusted institution. It issues certificates that vouch for identities.
Certificates (X.509) — the digital equivalent of a stamped document. Each certificate binds a public key to an identity (a person, a service, a role).
Key pairs — each actor has a private key (kept secret) and a public key (shared freely). What you sign with the private key, anyone can verify with the public key.

Real-world uses: HTTPS (TLS), document signing (PDF/PAdES), code signing, email (S/MIME).

The trust chain

A PKI is structured as a hierarchy. A production-grade three-tier setup looks like this:

Root CA — the anchor of trust. Self-signed. Kept offline (air-gapped machine or HSM). You only bring it online to sign a new Intermediate CA, which happens rarely (once every few years).
Intermediate CA — signed by the Root, used for day-to-day certificate issuance. If it's compromised, you revoke it and issue a new one from the Root — without ever putting the Root CA at risk.
Signing Certificate — the leaf. Issued to a specific actor (person, service, role). If compromised, the Intermediate CA revokes it and issues a new one.

This layering is what gives PKIs their resilience: the higher the tier, the less it's exposed, the harder it is to compromise.

The node-forge Compatibility Problem

Let me save you the debugging session I went through.

node-forge encrypts private keys with forge.pki.encryptRsaPrivateKey(). This works fine. The problem appears later, when you try to decrypt the same key with forge.pki.decryptRsaPrivateKey() — it silently returns null for keys encrypted with AES-256 in certain environments.

This is a known but poorly documented issue. Depending on your Node.js version and the exact AES-256 encryption parameters forge uses, the decryption fails without throwing an error.

The fix: use Node.js built-in crypto.createPrivateKey() for decryption. It handles all standard PKCS#1/PKCS#8 encrypted key formats correctly, then you hand the decrypted key back to forge for operations that require it (like building a PKCS#12 bundle).

Here's the flow that works:

node-forge encryptRsaPrivateKey()   →  encrypted PEM on disk
                                           ↓
Node.js crypto.createPrivateKey()   →  decrypted CryptoKey object
                                           ↓
privateKeyObject.export({ type: 'pkcs1' })  →  unencrypted PEM
                                           ↓
node-forge privateKeyFromPem()      →  forge key object (for P12, signing, etc.)

We'll see this in practice in Step 4.

Prerequisites

Node.js 20 LTS or later
TypeScript (optional but recommended)

pnpm add node-forge
pnpm add -D @types/node-forge

node is a built-in module — no extra installation needed for crypto.

Step 1 — Generate the Root CA

The Root CA is self-signed: it signs its own certificate with its own private key. There is no higher authority vouching for it. It is trusted by declaration — you add it manually to your application's trust store.

Key decisions for the Root CA:

RSA 4096-bit: Root CAs have long lifetimes (10 years). The higher key strength compensates for the longer exposure window. The workers: -1 option tells node-forge to use all available CPU threads for key generation — without it, a 4096-bit key can block your process for several seconds.
basicConstraints: cA: true: marks this certificate as a CA. Without this extension, other software refuses to use it to verify or sign anything.
keyUsage: keyCertSign: explicitly declares that this certificate is authorized to sign other certificates.
critical: true: if a parser doesn't understand this extension, it must reject the certificate. This prevents old or lenient parsers from ignoring security-relevant constraints.

import forge from 'node-forge';
import crypto from 'crypto';

export interface CACertificate {
  certificate: string; // PEM format
  privateKey: string;  // PEM format, AES-256 encrypted
  publicKey: string;   // PEM format
}

export async function generateRootCA(passphrase: string): Promise<CACertificate> {
  // workers: -1 uses all available CPU threads — essential for 4096-bit to avoid blocking
  const keys = forge.pki.rsa.generateKeyPair({ bits: 4096, workers: -1 });

  const cert = forge.pki.createCertificate();
  cert.publicKey = keys.publicKey;

  // Serial numbers must be unique within a CA — use random bytes, not sequential integers
  cert.serialNumber = crypto.randomBytes(16).toString('hex');

  const now = new Date();
  cert.validity.notBefore = now;
  cert.validity.notAfter = new Date();
  cert.validity.notAfter.setFullYear(now.getFullYear() + 10);

  const attrs = [
    { name: 'commonName', value: 'My Root CA' },
    { name: 'organizationName', value: 'My Org' },
    { name: 'countryName', value: 'FR' },
  ];

  cert.setSubject(attrs);
  cert.setIssuer(attrs); // Self-signed: issuer = subject, identical fields

  cert.setExtensions([
    {
      name: 'basicConstraints',
      cA: true,          // This is a CA — can sign other certificates
      critical: true,
    },
    {
      name: 'keyUsage',
      keyCertSign: true, // Authorized to sign certificates
      cRLSign: true,     // Authorized to sign Certificate Revocation Lists
      critical: true,
    },
    {
      name: 'subjectKeyIdentifier',
      // Fingerprint of this key, referenced by child certs via authorityKeyIdentifier
    },
  ]);

  // Self-sign: the CA's own private key signs its own certificate
  cert.sign(keys.privateKey, forge.md.sha256.create());

  // Encrypt the private key before returning — never store it in plaintext
  const privateKeyPem = forge.pki.encryptRsaPrivateKey(keys.privateKey, passphrase, {
    algorithm: 'aes256',
  });

  return {
    certificate: forge.pki.certificateToPem(cert),
    privateKey: privateKeyPem,
    publicKey: forge.pki.publicKeyToPem(keys.publicKey),
  };
}

Notice setIssuer(attrs) receives the same array as setSubject(attrs). That is the definition of a self-signed certificate — the issuer and subject are identical.

The private key is immediately encrypted before the function returns. It should never exist in plaintext on disk.

Step 2 — Issue an Intermediate CA

The Intermediate CA sits between the Root CA and the signing certificates. Its role: absorb the day-to-day risk of certificate issuance so the Root CA never has to be exposed online.

Key differences from the Root CA:

Signed by the Root CA, not self-signed — the Root CA's private key signs this certificate
pathlenConstraint: 0: this Intermediate CA can sign leaf certificates but cannot create further intermediate CAs. Limits blast radius if compromised.
authorityKeyIdentifier: links this certificate back to the Root CA's public key fingerprint — the mechanism chain-walkers use to find the issuer

export interface IntermediateCACertificate {
  certificate: string; // PEM format
  privateKey: string;  // PEM format, AES-256 encrypted
  publicKey: string;   // PEM format
}

export async function generateIntermediateCA(
  rootCA: CACertificate,
  rootPassphrase: string,
  options: {
    commonName: string;
    organization?: string;
    country?: string;
    validityYears?: number;
  }
): Promise<IntermediateCACertificate> {
  const { commonName, organization = '', country = '', validityYears = 5 } = options;

  // Decrypt the Root CA private key to sign this certificate
  // — see Step 4 for why we use Node.js crypto here instead of forge
  const rootPrivateKey = decryptPrivateKey(rootCA.privateKey, rootPassphrase);

  const keys = forge.pki.rsa.generateKeyPair({ bits: 2048, workers: -1 });
  const cert = forge.pki.createCertificate();

  cert.publicKey = keys.publicKey;
  cert.serialNumber = crypto.randomBytes(16).toString('hex');

  const now = new Date();
  cert.validity.notBefore = now;
  cert.validity.notAfter = new Date();
  cert.validity.notAfter.setFullYear(now.getFullYear() + validityYears);

  const subjectAttrs = [{ name: 'commonName', value: commonName }];
  if (organization) subjectAttrs.push({ name: 'organizationName', value: organization });
  if (country) subjectAttrs.push({ name: 'countryName', value: country });

  cert.setSubject(subjectAttrs);

  // Issuer = Root CA
  const rootCACert = forge.pki.certificateFromPem(rootCA.certificate);
  cert.setIssuer(rootCACert.subject.attributes);

  cert.setExtensions([
    {
      name: 'basicConstraints',
      cA: true,              // This is a CA — can sign leaf certificates
      pathlenConstraint: 0,  // But cannot sign further intermediate CAs
      critical: true,
    },
    {
      name: 'keyUsage',
      keyCertSign: true,
      cRLSign: true,
      critical: true,
    },
    {
      name: 'authorityKeyIdentifier',
      keyIdentifier: true,       // Points back to the Root CA's key fingerprint
      authorityCertIssuer: true,
    },
    { name: 'subjectKeyIdentifier' },
  ]);

  // Signed by Root CA's private key
  cert.sign(rootPrivateKey, forge.md.sha256.create());

  const privateKeyPem = forge.pki.encryptRsaPrivateKey(keys.privateKey, rootPassphrase, {
    algorithm: 'aes256',
  });

  return {
    certificate: forge.pki.certificateToPem(cert),
    privateKey: privateKeyPem,
    publicKey: forge.pki.publicKeyToPem(keys.publicKey),
  };
}

After this step, the Intermediate CA certificate carries the Root CA's signature. Anyone verifying a leaf certificate will walk the chain: leaf → Intermediate CA → Root CA. As long as they trust the Root CA, the entire chain is trusted.

Step 3 — Issue a Signing Certificate

The signing certificate is what you hand to an actor (a user, a service, a role). It is now signed by the Intermediate CA, not the Root directly — the Root CA never needs to be online for day-to-day issuance.

Key differences from the CA certificates:

basicConstraints: cA: false: this is a leaf certificate — it cannot sign other certificates
keyUsage: digitalSignature + nonRepudiation: for signing documents. nonRepudiation means the signer cannot later deny having signed something — required for legal validity in most jurisdictions
authorityKeyIdentifier: points to the Intermediate CA's key fingerprint

export interface SigningCertificate {
  certificate: string; // PEM format
  privateKey: string;  // PEM format, AES-256 encrypted
  publicKey: string;   // PEM format
}

export async function generateSigningCertificate(
  intermediateCA: IntermediateCACertificate,
  passphrase: string,
  options: {
    commonName: string;
    organization?: string;
    country?: string;
    validityDays?: number;
  }
): Promise<SigningCertificate> {
  const { commonName, organization = '', country = '', validityDays = 730 } = options;

  // Decrypt the Intermediate CA private key — using the Node.js crypto workaround
  const intermediatePrivateKey = decryptPrivateKey(intermediateCA.privateKey, passphrase);

  const keys = forge.pki.rsa.generateKeyPair({ bits: 2048, workers: -1 });
  const cert = forge.pki.createCertificate();

  cert.publicKey = keys.publicKey;
  cert.serialNumber = crypto.randomBytes(16).toString('hex');

  const now = new Date();
  cert.validity.notBefore = now;
  cert.validity.notAfter = new Date();
  cert.validity.notAfter.setDate(now.getDate() + validityDays);

  const subjectAttrs = [{ name: 'commonName', value: commonName }];
  if (organization) subjectAttrs.push({ name: 'organizationName', value: organization });
  if (country) subjectAttrs.push({ name: 'countryName', value: country });

  cert.setSubject(subjectAttrs);

  // Issuer = Intermediate CA (not the Root)
  const intermediateCACert = forge.pki.certificateFromPem(intermediateCA.certificate);
  cert.setIssuer(intermediateCACert.subject.attributes);

  cert.setExtensions([
    {
      name: 'basicConstraints',
      cA: false,          // Leaf certificate — cannot sign other certificates
      critical: true,
    },
    {
      name: 'keyUsage',
      digitalSignature: true,  // Can sign data (documents, PDFs)
      nonRepudiation: true,    // Signature is legally binding — signer cannot deny it
      critical: true,
    },
    {
      name: 'authorityKeyIdentifier',
      keyIdentifier: true,      // Points to Intermediate CA by key fingerprint
      authorityCertIssuer: true,
    },
    { name: 'subjectKeyIdentifier' },
  ]);

  // Signed by the Intermediate CA's private key
  cert.sign(intermediatePrivateKey, forge.md.sha256.create());

  const privateKeyPem = forge.pki.encryptRsaPrivateKey(keys.privateKey, passphrase, {
    algorithm: 'aes256',
  });

  return {
    certificate: forge.pki.certificateToPem(cert),
    privateKey: privateKeyPem,
    publicKey: forge.pki.publicKeyToPem(keys.publicKey),
  };
}

The Root CA private key is never touched during this step — it can remain offline. Only the Intermediate CA key is needed to issue new signing certificates.

Step 4 — Verify the Certificate Chain

Verification answers: "can I trust this certificate?" In a three-tier PKI, this means walking the full chain: signing certificate → Intermediate CA → Root CA.

Each step does two things: confirm the issuer/subject linkage (via authorityKeyIdentifier), and verify the cryptographic signature (did the parent's private key sign this certificate?). If every link holds and the chain ends at a trusted root, the certificate is valid.

export function verifyCertificateChain(
  signingCertPem: string,
  intermediateCAPem: string,
  rootCAPem: string,
): { valid: boolean; error?: string } {
  try {
    const signingCert = forge.pki.certificateFromPem(signingCertPem);
    const intermediateCert = forge.pki.certificateFromPem(intermediateCAPem);
    const rootCert = forge.pki.certificateFromPem(rootCAPem);

    // Check the signing cert is a leaf (not a CA)
    const leafConstraints = signingCert.getExtension('basicConstraints') as { cA?: boolean } | null;
    if (leafConstraints?.cA) {
      return { valid: false, error: 'Signing certificate must not be a CA' };
    }

    // Check all certificates are within their validity windows
    const now = new Date();
    for (const cert of [signingCert, intermediateCert, rootCert]) {
      if (now < cert.validity.notBefore || now > cert.validity.notAfter) {
        return { valid: false, error: `Certificate "${cert.subject.getField('CN')?.value}" is expired or not yet valid` };
      }
    }

    // Walk the chain: verify each signature with the parent's public key
    // intermediateCert.verify(signingCert) = did Intermediate CA sign the signing cert?
    if (!intermediateCert.verify(signingCert)) {
      return { valid: false, error: 'Signing certificate signature is invalid (not signed by Intermediate CA)' };
    }

    // rootCert.verify(intermediateCert) = did Root CA sign the Intermediate CA?
    if (!rootCert.verify(intermediateCert)) {
      return { valid: false, error: 'Intermediate CA signature is invalid (not signed by Root CA)' };
    }

    // Root CA must be self-signed
    if (!rootCert.verify(rootCert)) {
      return { valid: false, error: 'Root CA self-signature is invalid' };
    }

    return { valid: true };
  } catch (err) {
    return { valid: false, error: err instanceof Error ? err.message : 'Verification failed' };
  }
}

The cert.verify(issuerCert) call is the core of each step: it uses the issuer's public key to validate the signature embedded in the certificate. If the private key that signed it doesn't match the issuer's public key, verification fails.

In a real verification flow, you'd also check revocation status (CRL or OCSP). We keep it simple here.

Step 5 — Decrypting Private Keys (the node-forge compatibility issue)

Here is the part that took me the most time to debug.

node-forge encrypts private keys with forge.pki.encryptRsaPrivateKey(). The encrypted PEM header is BEGIN RSA PRIVATE KEY (PKCS#1 format with an encryption wrapper). When you later need to use that key, the natural choice is forge.pki.decryptRsaPrivateKey(). And this is where it breaks.

The symptom: forge.pki.decryptRsaPrivateKey(encryptedPem, passphrase) returns null. No exception, no error message — just null. Your code then crashes trying to call .sign() on a null value.

The root cause: node-forge's AES-256 decryption for the PBE-SHA1-AES-256-CBC scheme has compatibility issues in certain Node.js versions. It works in some environments, silently fails in others.

The fix: delegate decryption to Node.js built-in crypto, which uses OpenSSL and handles all standard encrypted key formats correctly:

import crypto from 'crypto';
import forge from 'node-forge';

/**
 * Decrypts an AES-256 encrypted PEM private key.
 *
 * node-forge's decryptRsaPrivateKey() silently returns null for AES-256
 * encrypted keys in some Node.js versions. Node.js built-in crypto handles
 * the same format correctly, so we use it for decryption and re-export
 * in a format forge can read.
 */
export function decryptPrivateKey(
  encryptedPem: string,
  passphrase: string,
): forge.pki.rsa.PrivateKey {
  // Step 1: Node.js crypto decrypts the key correctly
  const keyObject = crypto.createPrivateKey({
    key: encryptedPem,
    format: 'pem',
    passphrase: passphrase,
  });

  // Step 2: export as unencrypted PKCS#1 PEM — a format forge reads without issues
  const unencryptedPem = keyObject.export({
    type: 'pkcs1',
    format: 'pem',
  }) as string;

  // Step 3: now forge can parse it without problems
  return forge.pki.privateKeyFromPem(unencryptedPem);
}

Usage is straightforward:

// Encrypted key lives on disk (or in a secrets manager)
const encryptedKeyPem = fs.readFileSync('pki/signing/accountant.key', 'utf-8');

// Decrypt with the workaround
const privateKey = decryptPrivateKey(encryptedKeyPem, process.env.PKI_PASSPHRASE);

// Now use it normally with forge
const p12 = forge.pkcs12.toPkcs12Asn1(privateKey, [cert], passphrase, { algorithm: '3des' });

The key insight: never call forge.pki.decryptRsaPrivateKey() with AES-256 encrypted keys. Always go through crypto.createPrivateKey() instead.

Step 6 — Sign Data with a Certificate

With a decrypted private key and a certificate, you can sign arbitrary data. The process:

Hash the data — SHA-256 produces a fixed-size 32-byte digest of any input
Sign the hash — the private key encrypts the hash. Only the holder of this private key can produce this output.
Encode as Base64 — raw signature bytes are binary; Base64 makes them safe to store in a database or transmit in JSON

To verify, the process runs in reverse: recompute the hash of the data, use the public key to decrypt the signature and recover the original hash. If they match, the data is authentic and unmodified.

export function signData(
  data: string | Buffer,
  privateKey: forge.pki.rsa.PrivateKey,
): string {
  const md = forge.md.sha256.create();
  const content = typeof data === 'string' ? data : data.toString('binary');
  md.update(content, 'utf8');

  // RSA-PKCS#1-v1.5 signature: hash → RSA sign → raw bytes
  const signature = privateKey.sign(md);

  // Base64-encode for safe storage and transport
  return forge.util.encode64(signature);
}

export function verifySignature(
  data: string | Buffer,
  signatureBase64: string,
  certificatePem: string,
): boolean {
  try {
    const cert = forge.pki.certificateFromPem(certificatePem);
    const publicKey = cert.publicKey as forge.pki.rsa.PublicKey;

    const md = forge.md.sha256.create();
    const content = typeof data === 'string' ? data : data.toString('binary');
    md.update(content, 'utf8');

    // Decodes the signature and verifies against the recomputed hash
    return publicKey.verify(md.digest().bytes(), forge.util.decode64(signatureBase64));
  } catch {
    return false;
  }
}

verifySignature only confirms the data was signed with this certificate's private key. It does not confirm that the certificate is trustworthy. For full trust verification, also call verifySigningCertificate — a valid signature from an untrusted certificate is worthless.

Putting It All Together

async function main() {
  const passphrase = 'min-12-char-passphrase';

  // 1. Generate the Root CA once — store offline, never on a server
  const rootCA = await generateRootCA(passphrase);
  console.log('Root CA created');

  // 2. Generate the Intermediate CA — signed by Root, used for day-to-day issuance
  const intermediateCA = await generateIntermediateCA(rootCA, passphrase, {
    commonName: 'My Signing CA',
    organization: 'My Org',
    country: 'FR',
    validityYears: 5,
  });
  console.log('Intermediate CA created');

  // 3. Issue signing certificates per actor — signed by Intermediate CA
  //    Root CA does not need to be online for this step
  const accountantCert = await generateSigningCertificate(intermediateCA, passphrase, {
    commonName: 'Cabinet Dupont & Associés',
    organization: 'Cabinet Dupont',
    country: 'FR',
    validityDays: 730,
  });
  console.log('Accountant certificate issued');

  // 4. Verify the full chain: signing cert → Intermediate CA → Root CA
  const chainResult = verifyCertificateChain(
    accountantCert.certificate,
    intermediateCA.certificate,
    rootCA.certificate,
  );
  console.log('Chain valid:', chainResult.valid); // true

  // 5. Sign some data — first decrypt the private key using the workaround
  const privateKey = decryptPrivateKey(accountantCert.privateKey, passphrase);
  const signature = signData('Tax declaration 2024-Q4', privateKey);

  // 6. Verify the signature using the certificate's public key
  const signatureValid = verifySignature(
    'Tax declaration 2024-Q4',
    signature,
    accountantCert.certificate
  );
  console.log('Signature valid:', signatureValid); // true

  // Tamper detection — any change to the data fails verification
  const tampered = verifySignature(
    'Tax declaration 2024-Q4 (modified)',
    signature,
    accountantCert.certificate
  );
  console.log('Tampered signature valid:', tampered); // false
}

main();

Storing and Loading Certificates

import fs from 'fs/promises';
import path from 'path';

// Save all three files to a directory
async function saveCertificate(cert: SigningCertificate, dir: string): Promise<void> {
  await fs.mkdir(dir, { recursive: true });

  await Promise.all([
    fs.writeFile(path.join(dir, 'cert.pem'), cert.certificate),
    fs.writeFile(path.join(dir, 'key.pem'), cert.privateKey),     // AES-256 encrypted
    fs.writeFile(path.join(dir, 'public.pem'), cert.publicKey),
  ]);
}

// Load back from disk
async function loadCertificate(dir: string): Promise<SigningCertificate> {
  const [certificate, privateKey, publicKey] = await Promise.all([
    fs.readFile(path.join(dir, 'cert.pem'), 'utf-8'),
    fs.readFile(path.join(dir, 'key.pem'), 'utf-8'),
    fs.readFile(path.join(dir, 'public.pem'), 'utf-8'),
  ]);

  return { certificate, privateKey, publicKey };
}

A few rules to follow in production:

Never commit pki/ to git — add it to .gitignore. Certificates and encrypted keys should go in a secrets manager, not source control.
The Root CA private key should never be on an application server — generate it offline, store it in an HSM or vault, and only bring it online to sign new certificates (once every few years).
Minimum 12-character passphrase for key encryption — store it in environment variables or a secrets manager, never hardcoded.
Track issued certificates in a database — serial number, subject, validity dates, revocation status. You need this to implement a CRL or OCSP endpoint later.

Common Pitfalls

forge.pki.decryptRsaPrivateKey returns null: as described above, use crypto.createPrivateKey() instead. Always.

workers: -1 is essential for 4096-bit keys: without it, node-forge generates RSA 4096 keys synchronously, blocking the entire Node.js event loop for 2–10 seconds. With workers: -1, it uses all available CPU threads in parallel.

Clock skew: notBefore / notAfter validation fails if server clocks drift. Set notBefore to new Date(Date.now() - 5 * 60 * 1000) (5 minutes in the past) as a buffer against clock differences between issuer and verifier.

SHA-1 is dead: forge.md.sha256.create() is what we're using throughout. forge.md.sha1.create() exists but SHA-1 certificates are rejected by all modern runtimes and browsers.

Sequential serial numbers: serial numbers must be unique within a CA. Sequential integers can collide in distributed systems where multiple servers issue certificates concurrently. Use crypto.randomBytes(16) as shown above.

What's Next?

This PKI gives you the foundation for more advanced use cases:

PDF signing (PAdES) — combine this certificate chain with @signpdf to sign PDFs in a format that Adobe Reader can verify. I cover this in the next post.
Intermediate CA — add a layer between Root CA and signing certificates for better compartmentalization in large deployments
CRL (Certificate Revocation List) — a signed list of revoked serial numbers that clients check before trusting a certificate
OCSP — online revocation status checking, an alternative to CRLs

Conclusion

The key takeaways:

Three-tier chain: Root CA (offline) → Intermediate CA (restricted) → Signing Certificate (daily use). Each tier can be rotated or revoked without compromising the ones above it.
node-forge for certificate generation — it handles X.509 structure, extensions, and signing well
Node.js crypto for key decryption — forge.pki.decryptRsaPrivateKey silently returns null for AES-256 encrypted keys; crypto.createPrivateKey() does not
Encrypt keys immediately — forge.pki.encryptRsaPrivateKey() before any key ever touches disk
workers: -1 for RSA key generation — avoids blocking the event loop

The chain of signatures is what makes trust transitive: if you trust the Root CA, and the Root signed the Intermediate, and the Intermediate signed the leaf, then you trust the leaf. Break any link in the chain and verification fails.

Questions or edge cases you've hit? Drop them in the comments.

How to Integrate OneSignal Push Notifications in Your Laravel App

Lepres KIKOUNGA — Wed, 19 Nov 2025 12:00:38 +0000

Push notifications are essential for keeping users engaged with your app. Whether you're building a mobile app, web application, or both, OneSignal makes it easy to send notifications across platforms. In this guide, I'll show you how to integrate OneSignal into your Laravel application and start sending push notifications in minutes.

What You'll Learn

By the end of this tutorial, you'll know how to:

Set up OneSignal in your Laravel application
Send notifications to specific users
Target user segments and groups
Add images and action buttons to notifications
Handle notification events
Use Laravel's notification system with OneSignal

Prerequisites

Before we start, make sure you have:

A Laravel 11 or 12 application
PHP 8.3 or higher
A OneSignal account (free tier works fine)
Your OneSignal App ID and REST API Key

Step 1: Install the Package

First, install the OneSignal package via Composer:

composer require lepresk/laravel-onesignal

The package will auto-register with Laravel, so no need to manually add the service provider.

Step 2: Configure Your Credentials

Publish the configuration file:

php artisan vendor:publish --tag=onesignal-config

Add your OneSignal credentials to your .env file:

ONESIGNAL_APP_ID=your-app-id-here
ONESIGNAL_REST_API_KEY=your-rest-api-key-here
ONESIGNAL_ANDROID_CHANNEL_ID=your-android-channel-id

Getting Your OneSignal API Credentials

If this is your first time with OneSignal, here's how to get your credentials:

Go to onesignal.com and create a free account
Click New App/Website and follow the setup wizard
Once your app is created, go to Settings in the left sidebar
Click on Keys & IDs
Copy your App ID and REST API Key

For the Android Channel ID:

In your OneSignal dashboard, go to Settings → Platforms
Under Android, you'll find your Firebase Server Key section
The channel ID is typically something you define in your Android app (e.g., "default_channel")
If you're only using iOS or web, you can leave this empty

Step 3: Send Your First Notification

Let's send a simple notification to test everything works:

use Lepresk\LaravelOnesignal\Facades\OneSignal;
use Lepresk\LaravelOnesignal\PushMessage;

$message = (new PushMessage())
    ->withTitle('Hello World')
    ->withBody('This is my first push notification!')
    ->toExternalUserIds([123]); // Your user's ID

$response = OneSignal::send($message);

if ($response->isSuccessful()) {
    echo "Notification sent successfully!";
    echo "Notification ID: " . $response->getNotificationId();
    echo "Recipients: " . $response->getRecipients();
}

Understanding External User IDs

External User IDs are identifiers you assign to your users in OneSignal. They map your application's user IDs to OneSignal's internal player IDs. This way, you can send notifications to users using your own database IDs without tracking OneSignal's player IDs.

To set up external user IDs, you'll need to configure them in your mobile app or web SDK when users log in.

Step 4: Targeting Different Audiences

Send to Specific Users

// Single user
$message->toUser(123);

// Multiple users
$message->toExternalUserIds([1, 2, 3, 4, 5]);

Send to Segments

Segments are groups of users you define in your OneSignal dashboard based on criteria like location, language, or custom tags.

// Send to a custom segment
$message->toSegment('Premium Users');

// Send to multiple segments
$message->toSegments(['Premium Users', 'Active Users']);

// Built-in segments
$message->toSubscribedSegment();  // All subscribed users
$message->toActiveSegment();       // Active users
$message->toInactiveSegment();     // Inactive users

Send Based on Tags

Tags are key-value pairs you set on user devices for custom targeting:

$message->toTag('subscription_level', 'premium');
$message->toTag('age_group', '18-25');
$message->toTag('interests', 'technology', '=');

Step 5: Enhance Your Notifications

Add Images

Make your notifications stand out with images:

$message = (new PushMessage())
    ->withTitle('New Product Launch!')
    ->withBody('Check out our latest features')
    ->withImage('https://yourapp.com/images/product-launch.jpg')
    ->toSegment('All Users');

Add Action Buttons

Action buttons let users take immediate action from the notification:

$message = (new PushMessage())
    ->withTitle('Flash Sale!')
    ->withBody('50% off - 2 hours only')
    ->addButton('shop', 'Shop Now', 'https://yourapp.com/sale')
    ->addButton('remind', 'Remind Me Later')
    ->toSegment('Active Users');

The third parameter (URL) is optional. If provided, clicking the button will open that URL.

Multi-language Support

Send notifications in multiple languages:

$message = (new PushMessage())
    ->withTitle('Welcome!', 'en')
    ->withTitle('Bienvenue!', 'fr')
    ->withTitle('¡Bienvenido!', 'es')
    ->withBody('Thanks for joining our app', 'en')
    ->withBody('Merci de rejoindre notre application', 'fr')
    ->withBody('Gracias por unirte a nuestra aplicación', 'es')
    ->toSubscribedSegment();

Set Priority

Control how quickly users receive notifications:

// High priority (immediate delivery)
$message->withHightPriority();

// Normal priority
$message->withDefaultPriority();

Custom Data

Attach custom data to your notifications for handling in your app:

$message = (new PushMessage())
    ->withTitle('New Message')
    ->withBody('You have a new message from John')
    ->addData('type', 'chat')
    ->addData('chat_id', 456)
    ->addData('sender_id', 789)
    ->toUser($userId);

Step 6: Using Laravel's Notification System

For a more Laravel-native approach, integrate with Laravel's notification system:

Create a Notification

php artisan make:notification OrderShipped

Configure the Notification

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use Lepresk\LaravelOnesignal\PushMessage;

class OrderShipped extends Notification
{
    public function __construct(
        private int $orderId,
        private string $trackingNumber
    ) {}

    public function via($notifiable): array
    {
        return ['push'];
    }

    public function toPush($notifiable): PushMessage
    {
        return (new PushMessage())
            ->withTitle('Order Shipped!')
            ->withBody("Your order #{$this->orderId} is on its way")
            ->addData('order_id', $this->orderId)
            ->addData('tracking_number', $this->trackingNumber)
            ->addButton('track', 'Track Order', "https://yourapp.com/orders/{$this->orderId}")
            ->toUser($notifiable->onesignal_id); // Assuming you store OneSignal user ID in this field
    }
}

Send the Notification

$user = User::find(1);
$user->notify(new OrderShipped($orderId, $trackingNumber));

Step 7: Handle Notification Events

Monitor what happens with your notifications by listening to events:

// In your EventServiceProvider
use Lepresk\LaravelOnesignal\Events\NotificationSending;
use Lepresk\LaravelOnesignal\Events\NotificationSent;
use Lepresk\LaravelOnesignal\Events\NotificationFailed;

protected $listen = [
    NotificationSending::class => [
        LogNotificationAttempt::class,
    ],
    NotificationSent::class => [
        LogNotificationSuccess::class,
    ],
    NotificationFailed::class => [
        HandleNotificationFailure::class,
    ],
];

Example Event Listener

<?php

namespace App\Listeners;

use Lepresk\LaravelOnesignal\Events\NotificationSent;
use Illuminate\Support\Facades\Log;

class LogNotificationSuccess
{
    public function handle(NotificationSent $event): void
    {
        Log::info('Push notification sent', [
            'notification_id' => $event->response->getNotificationId(),
            'recipients' => $event->response->getRecipients(),
        ]);

        // Update your analytics, database, etc.
    }
}

Step 8: Advanced Configuration

The package offers several configuration options in config/onesignal.php:

Set Default TTL (Time to Live)

Control how long OneSignal attempts to deliver notifications:

'defaults' => [
    'ttl' => env('ONESIGNAL_DEFAULT_TTL', 604800), // 7 days
],

Configure Logging

'logging' => [
    'enabled' => true,
    'channel' => 'stack', // Use a specific log channel
    'level' => 'info',
],

Exception Handling

'throw_exceptions' => true, // Throw exceptions on failures

If set to false, failures will be logged but won't throw exceptions.

Real-World Examples

Welcome New Users

$message = (new PushMessage())
    ->withTitle('Welcome to MyApp!')
    ->withBody('We\'re excited to have you here')
    ->withImage('https://myapp.com/welcome-banner.jpg')
    ->addButton('start', 'Get Started', 'https://myapp.com/onboarding')
    ->toUser($newUser->id);

OneSignal::send($message);

Cart Abandonment Reminder

$message = (new PushMessage())
    ->withTitle('Don\'t Forget Your Cart!')
    ->withBody('You left some items behind. Complete your order now.')
    ->addData('cart_id', $cart->id)
    ->addButton('checkout', 'Complete Purchase', 'https://myapp.com/checkout')
    ->setTTL(86400) // 24 hours
    ->toUser($user->id);

OneSignal::send($message);

Daily Digest for Active Users

$message = (new PushMessage())
    ->withTitle('Your Daily Digest')
    ->withBody('See what\'s new today')
    ->withImage('https://myapp.com/digest-banner.jpg')
    ->addButton('view', 'View Digest', 'https://myapp.com/digest')
    ->toActiveSegment()
    ->withDefaultPriority();

OneSignal::send($message);

Troubleshooting

Notification Not Received

Verify your OneSignal credentials are correct
Check that the user has a valid OneSignal player ID
Ensure the user has granted notification permissions
Check OneSignal dashboard for delivery status

Testing in Development

Use OneSignal's test mode and send to your own device first:

$message = (new PushMessage())
    ->withTitle('Test Notification')
    ->withBody('Testing push notifications')
    ->toUser($yourTestUserId);

$response = OneSignal::send($message);
dd($response->getRawResponse()); // See the full response

Common Pitfalls to Avoid

Sending too many notifications
I learned this the hard way. Users will disable notifications if you spam them. Be selective about what deserves a push notification.

Not testing on real devices
The OneSignal dashboard shows if a notification was sent, but only testing on actual devices tells you if it looks good and works properly.

Forgetting about timezones
Sending a promotion at 3 AM local time is not great. Use intelligent delivery or schedule based on user timezones.

Generic messages
"You have a new notification" tells users nothing. Be specific about what happened and why they should care.

Wrapping Up

That's it. You now have OneSignal working in your Laravel app with a clean, maintainable integration. The examples I showed cover most use cases, but there's more in the documentation if you need advanced features like delayed sending or custom notification sounds.

The package is open source, so if you run into issues or want to add features, contributions are welcome on GitHub.

Links:

GitHub: https://github.com/lepresk/laravel-onesignal
Packagist: https://packagist.org/packages/lepresk/laravel-onesignal

If you found this helpful or have questions, leave a comment. I'm usually pretty quick to respond.

How to Integrate MTN Mobile Money in PHP - Complete Guide

Lepres KIKOUNGA — Sun, 26 Oct 2025 22:16:59 +0000

How to Integrate MTN Mobile Money in PHP - Complete Guide

Mobile Money is the dominant payment method in Africa, with MTN Mobile Money (MoMo) leading the market. If you're building a PHP application that needs to accept payments or send money in Africa, integrating MTN MoMo is essential.

In this guide, I'll show you how to integrate MTN Mobile Money using a modern PHP library that makes it simple and type-safe.

What We'll Build

By the end of this tutorial, you'll be able to:

Accept payments from customers (Collection)
Send money to users (Disbursement)
Check transaction status
Handle callbacks
Test everything in sandbox mode

Installation

First, install the library via Composer:

composer require lepresk/momo-api

Requirements: PHP 7.4+ or PHP 8.x

Quick Start: Accepting Payments

Let's start with the most common use case - accepting a payment from a customer.

1. Setup Collection API

<?php
use Lepresk\MomoApi\MomoApi;

$collection = MomoApi::collection([
    'environment' => 'sandbox', // Use 'mtncongo', 'mtnuganda', etc. for production
    'subscription_key' => 'YOUR_SUBSCRIPTION_KEY',
    'api_user' => 'YOUR_API_USER',
    'api_key' => 'YOUR_API_KEY',
    'callback_url' => 'https://yourdomain.com/callback'
]);

2. Request Payment (Quick Method)

The simplest way to request a payment:

// Request 1000 XAF from phone number 242068511358
$paymentId = $collection->quickPay('1000', '242068511358', 'ORDER-123');

echo "Payment ID: $paymentId"; // UUID v4

3. Check Payment Status

$transaction = $collection->getPaymentStatus($paymentId);

if ($transaction->isSuccessful()) {
    echo "Payment of {$transaction->getAmount()} {$transaction->getCurrency()} received!";
    echo "Payer: {$transaction->getPayer()}";

    // Update your database, fulfill order, etc.
} elseif ($transaction->isFailed()) {
    $reason = $transaction->getReason();

    if ($reason->isNotEnoughFunds()) {
        echo "Customer has insufficient funds";
    } elseif ($reason->isPayerLimitReached()) {
        echo "Customer reached their transaction limit";
    }
}

Advanced: Sending Money (Disbursement)

Need to pay out to users? Use the Disbursement API:

use Lepresk\MomoApi\MomoApi;
use Lepresk\MomoApi\Models\TransferRequest;

$disbursement = MomoApi::disbursement([
    'environment' => 'sandbox',
    'subscription_key' => 'YOUR_SUBSCRIPTION_KEY',
    'api_user' => 'YOUR_API_USER',
    'api_key' => 'YOUR_API_KEY'
]);

// Send money to a user
$transfer = TransferRequest::make('5000', '242068511358', 'SALARY-001');
$transferId = $disbursement->transfer($transfer);

// Check transfer status
$result = $disbursement->getTransferStatus($transferId);

if ($result->isSuccessful()) {
    echo "Transfer of {$result->getAmount()} sent successfully!";
}

Handling Callbacks

MTN MoMo sends asynchronous callbacks when transactions complete. Here's how to handle them:

<?php
// webhook.php

use Lepresk\MomoApi\Models\Transaction;

// Parse the callback data
$transaction = Transaction::parse($_GET);

if ($transaction->isSuccessful()) {
    // Update order status in database
    $orderId = $transaction->getExternalId();
    $amount = $transaction->getAmount();

    DB::table('orders')
        ->where('id', $orderId)
        ->update(['status' => 'paid', 'amount' => $amount]);

    // Send confirmation email, etc.
} elseif ($transaction->isFailed()) {
    $reason = $transaction->getReason();

    // Log the failure
    error_log("Payment failed: {$reason->getCode()} - {$reason->getMessage()}");
}

http_response_code(200); // Always return 200 to MTN

Testing in Sandbox Mode

Before going to production, test everything in sandbox:

1. Create Sandbox API User

use Lepresk\MomoApi\MomoApi;
use Lepresk\MomoApi\Support\Uuid;

$momo = MomoApi::create(MomoApi::ENVIRONMENT_SANDBOX);

// Generate UUID for API user
$uuid = Uuid::v4();

// Create API user
$apiUser = $momo->sandbox('YOUR_SANDBOX_SUBSCRIPTION_KEY')
    ->createApiUser($uuid, 'https://yourdomain.com/callback');

// Create API key
$apiKey = $momo->sandbox('YOUR_SANDBOX_SUBSCRIPTION_KEY')
    ->createApiKey($apiUser);

echo "API User: $apiUser\n";
echo "API Key: $apiKey\n";

2. Use These Credentials

Now use the generated credentials for testing in sandbox mode.

Production Deployment

When ready for production:

$collection = MomoApi::collection([
    'environment' => 'mtncongo', // or 'mtnuganda', 'mtnghana', etc.
    'subscription_key' => env('MOMO_SUBSCRIPTION_KEY'),
    'api_user' => env('MOMO_API_USER'),
    'api_key' => env('MOMO_API_KEY'),
    'callback_url' => env('MOMO_CALLBACK_URL')
]);

Supported Countries

The library supports all MTN MoMo markets:

Congo
Uganda
Ghana
Cameroon
Zambia
Ivory Coast
Benin
South Africa
And more...

Best Practices

1. Always Use Environment Variables

// .env
MOMO_SUBSCRIPTION_KEY=your_key_here
MOMO_API_USER=your_user_here
MOMO_API_KEY=your_key_here
MOMO_CALLBACK_URL=https://yourdomain.com/webhook

2. Validate Callbacks via API

Never trust callback data alone. Always verify:

// In your webhook handler
$callbackData = Transaction::parse($_GET);
$paymentId = $callbackData->getExternalId();

// Verify by calling the API
$verified = $collection->getPaymentStatus($paymentId);

if ($verified->isSuccessful()) {
    // NOW you can trust it and process the order
}

3. Handle Errors Gracefully

use Lepresk\MomoApi\Exceptions\ResourceNotFoundException;
use Lepresk\MomoApi\Exceptions\InternalServerErrorException;

try {
    $paymentId = $collection->quickPay('1000', '242068511358', 'ORDER-123');
} catch (ResourceNotFoundException $e) {
    // Payment not found
    log_error("Payment not found: " . $e->getMessage());
} catch (InternalServerErrorException $e) {
    // MTN server error - retry later
    queue_retry($paymentRequest);
}

4. Check Account Balance

Monitor your account balance regularly:

$balance = $collection->getBalance();

if ((int)$balance->getAvailableBalance() < 10000) {
    notify_admin("Low MoMo balance: {$balance->getAvailableBalance()} {$balance->getCurrency()}");
}

Security Tips

Never commit credentials - Use .env files
Validate webhook IPs - Only accept callbacks from MTN IPs
Use HTTPS - For all callback URLs
Log everything - Keep audit trails
Implement idempotency - Use unique externalId for each transaction

Error Handling Reference

Common error reasons you'll encounter:

$transaction = $collection->getPaymentStatus($paymentId);

if ($transaction->isFailed()) {
    $reason = $transaction->getReason();

    // Check specific errors
    if ($reason->isNotEnoughFunds()) {
        // Customer balance too low
    } elseif ($reason->isPayerLimitReached()) {
        // Daily/monthly limit exceeded
    } elseif ($reason->isPayeeNotFound()) {
        // Invalid phone number
    }

    // Get raw error data
    echo $reason->getCode();    // e.g., "NOT_ENOUGH_FUNDS"
    echo $reason->getMessage(); // Human-readable message
}

Advanced Features

Refunds

use Lepresk\MomoApi\Models\RefundRequest;

// Refund a previous transaction
$refund = RefundRequest::make(
    '1000',                                    // Amount
    '07a461a4-e721-462b-81c6-b9aa2f8abf06',   // Original transaction ID
    'REFUND-001'                               // Your refund reference
);

$refundId = $disbursement->refund($refund);

// Check refund status
$status = $disbursement->getRefundStatus($refundId);

Custom Payment Request

For more control over payment requests:

use Lepresk\MomoApi\Models\PaymentRequest;

$request = new PaymentRequest(
    amount: '2500',
    currency: 'XAF',
    externalId: 'ORDER-456',
    payer: '242068511358',
    payerMessage: 'Payment for premium subscription',
    payeeNote: 'Thank you for your purchase'
);

$paymentId = $collection->requestToPay($request);

Real-World Example: E-commerce Checkout

Here's a complete checkout flow:

<?php
// checkout.php

use Lepresk\MomoApi\MomoApi;

// 1. Initialize collection
$collection = MomoApi::collection([...]);

// 2. Get cart total from session
$cartTotal = $_SESSION['cart_total'];
$userPhone = $_SESSION['user_phone'];
$orderId = generate_order_id();

// 3. Request payment
try {
    $paymentId = $collection->quickPay(
        (string)$cartTotal,
        $userPhone,
        $orderId
    );

    // 4. Save payment ID to database
    DB::table('orders')->insert([
        'id' => $orderId,
        'payment_id' => $paymentId,
        'amount' => $cartTotal,
        'status' => 'pending',
        'created_at' => now()
    ]);

    // 5. Show waiting page
    redirect("/payment/waiting/$paymentId");

} catch (\Exception $e) {
    show_error("Payment failed: " . $e->getMessage());
}

<?php
// webhook.php - Handle MTN callback

$transaction = Transaction::parse($_GET);
$orderId = $transaction->getExternalId();

if ($transaction->isSuccessful()) {
    DB::table('orders')
        ->where('id', $orderId)
        ->update(['status' => 'paid']);

    // Trigger order fulfillment
    dispatch(new FulfillOrderJob($orderId));

    // Send confirmation email
    Mail::to($customer)->send(new OrderConfirmation($orderId));
}

http_response_code(200);

Resources

GitHub Repository: lepresk/momo-api
Packagist: lepresk/momo-api
MTN Developer Portal: momodeveloper.mtn.com
API Documentation: GitHub README

Conclusion

Integrating MTN Mobile Money in PHP is now straightforward with this library. You get:

Type-safe - Full PHPStan level 5 compliance
Modern - Fluent API with sensible defaults
Tested - 57 tests with 211 assertions
Production-ready - Used in real applications
Well-documented - Examples for every method

The library handles all the complexity of OAuth tokens, HTTP headers, error handling, and status codes - so you can focus on building your application.

Questions? Drop a comment below or open an issue on GitHub!

Found this helpful? Star the repo on GitHub!

Tags: #php #payment #momo #mobilemoney #africa #api #tutorial #laravel #symfony #backend