Download the PHP package phpussd/phpussd without Composer

On this page you can find all versions of the php package phpussd/phpussd. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of phpussd/phpussd

Informations about the package phpussd

PhpUSSD

A fast, minimal PHP framework for building state-machine-based USSD applications.

PHP 8.1+ · Zero runtime dependencies · 75 tests passing

Features

Core

Feature Description
State machine navigation Every screen is a menu node. Every input is an explicit transition. No hidden routing — the full application flow is readable from one config file.
Lazy menu instantiation Only the single menu needed for the current request is constructed. All others are registered by class name and never loaded.
Batched session writes Session mutations accumulate in memory and flush once at the end of the request. No per-set() disk or Redis I/O.
Back / Main / Paginate 0 (back), 00 (main menu), 99 (next page), and 98 (prev page) are handled by the navigator before handleInput() is called. Menus never implement these themselves.
Zero dependencies The framework requires only php: >=8.1. Nothing else in Composer. Safe to drop into any PHP environment.

Menu Abstractions

Feature Description
AbstractMenu Base class for every screen. Implements display(), handleInput(), and getParentMenu(). Injects session, language, and HTTP client automatically.
MultiStepMenu trait Eliminates manual step-counter boilerplate for multi-input flows. Declare step names; the trait manages position, storage, and advancement — namespaced per class so two flows never overwrite each other.
PaginatedListMenu Base class for lists that exceed one USSD screen. Handles fetch, cache, page boundaries, and 98/99 navigation. Subclass implements fetchItems(), itemLabel(), and onItemSelected().
Guards Implement MenuGuardInterface to protect menus without embedding auth logic inside them. Guards run before both display() and handleInput(). Multiple guards can be stacked.
Lifecycle hooks Optional onEnter() and onLeave() methods on every menu. Use onEnter() to pre-fetch data into session; onLeave() to clean up.
Error pattern errorThen($message, $menuId) stores an error in session and returns a menu ID. The next display() call reads it with consumeError() and prepends it to the screen.

Gateway Drivers

Driver Format When to use
AfricasTalkingDriver Form-encoded POST · plain text CON …/END … Africa's Talking production gateway
NaloDriver Form-encoded POST · plain text Nalo Solutions gateway
JsonDriver JSON POST · JSON {"type","message","sessionId"} USSD Phone Simulator, REST clients, local dev
Custom Any Implement GatewayDriverInterface

Session Drivers

Driver Backing store When to use
FileSessionManager JSON files on disk Development, low-traffic deployments
RedisSessionManager Redis (ext-redis required) Production, multi-server
ArraySessionManager In-memory PHP array Unit and integration tests

Internationalisation

Feature Description
Multi-language Register any number of language providers in config. Active language stored in session and restored on every request automatically.
AbstractLanguage Array-backed translation provider. Extend it with a $translations array — no config files, no parsing.
Missing key visibility Missing translation keys render as [missing:key_name] rather than empty strings — immediately visible during development.
sprintf formatting $this->tf('key', $arg1, $arg2) wraps sprintf for parameterised translations.

HTTP Client

Feature Description
Pre-configured Injected as $this->http in every menu. Base URL, timeout, and default headers set once in config.
Retry with back-off Retries failed requests using exponential back-off. Retry count is configurable.
Dot-notation responses $response->get('user.profile.name') for nested JSON access without manual array traversal.
Auth helpers $this->http->withToken($token) and $this->http->withHeaders([...]) for per-request overrides.

Middleware

Feature Description
Pipeline Middleware wraps every request. Declared in app.php, runs outermost-first. Supports class name, {class, options} array, or factory callable.
CorsMiddleware Built-in. Sends Access-Control-Allow-* headers and short-circuits OPTIONS preflights. Fully configurable per-origin allowlist, methods, headers, credentials, and max_age.
Custom middleware Implement MiddlewareInterface — one method: process(array $payload, callable $next): string. Call $next($payload) to pass through or return directly to short-circuit.

Simulator Integration

Feature Description
JsonDriver Speaks the same protocol as the USSD Phone Simulator — accepts {"sessionId","serviceCode","msisdn","input"}, returns {"type","message","sessionId"}.
JSON body parsing index.php detects Content-Type: application/json and reads from php://input automatically. No changes to menus needed.
CORS via middleware Configure CorsMiddleware in app.php to allow the simulator origin. No CORS logic needed in index.php.

Installation

Quick Start

1. index.php

2. config/app.php

3. Write a menu

Core Concepts

AbstractMenu

Every menu extends AbstractMenu and implements three methods:

Method Purpose
display(): UssdResponse Build the screen shown to the user
handleInput(): string\|UssdResponse Process input; return a menu ID (transition) or response
getParentMenu(): ?string Target for "0. Back"; null = no back

Available in every menu:

MultiStepMenu Trait

Eliminates the manual $step = $session->get('x_step') copy-paste for flows with multiple input stages:

Trait methods: currentStep(), advanceStep(), rewindStep(), captureAndAdvance(), storeStepValue(step, value), getStepValue(step), isFirstStep(), isLastStep(), clearSteps(), resetToFirstStep().

Step data is namespaced per class — two multi-step menus in the same session never overwrite each other.

PaginatedListMenu

Pagination inputs: 99 = next page, 98 = previous page (avoids conflict with Africa's Talking's * delimiter).

Guards

Session Drivers

Driver Use case
FileSessionManager Development, low-traffic deployments
RedisSessionManager Production (requires ext-redis)
ArraySessionManager Unit tests

Session writes are batched — accumulated in memory and flushed once at the end of the request via save(). No per-set() disk writes.

Gateway Drivers

Driver Format When to use
AfricasTalkingDriver Form-encoded · plain text CON/END Africa's Talking production
NaloDriver Form-encoded · plain text CON/END Nalo Solutions production
JsonDriver JSON body · JSON response Simulator, REST clients, local dev

Implement GatewayDriverInterface to add your own.

HTTP Client

The client supports retries with exponential back-off. Configure via api.retries in app config.

Testing

Use ArraySessionManager in your own tests:

Directory Structure

Documentation

Document Contents
Framework Philosophy Architecture, design principles, and what the framework deliberately omits
Guidelines & Usage Practical reference: menus, sessions, translations, HTTP client, guards, testing
Contributing & AI Prompts Contribution guide and AI agent context

All versions of phpussd with dependencies

PHP Build Version
Package Version
Requires php Version >=8.1
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package phpussd/phpussd contains the following files

Loading the files please wait ...