Record - Laravel USSD Documentation

Understanding Records

Records allow you to store user input and other data collected during a USSD session. This data persists across state transitions and can be accessed from any state within the same session. The data is automatically cleared when the session ends.

Basic Usage

Records are accessed through the $this->record property in state classes:

<?php

namespace App\Ussd\States;

use Vendor\LaravelUssd\Support\AbstractState;
use Vendor\LaravelUssd\Support\Context;

class AmountState extends AbstractState
{
    public function next(Context $context, string $input): ?string
    {
        $this->setContext($context);
        // Store the amount
        $this->record->set('amount', $input);
        
        return ConfirmState::class;
    }
}

Record Methods

set($key, $value)

Stores a single value with the specified key. The value will be available throughout the session.

$this->record->set('amount', 100);

setMultiple(array $data)

Stores multiple key-value pairs at once. Useful for storing related data together.

$this->record->setMultiple([
    'recipient' => '233241234567',
    'amount' => 100
]);

get($key, $default = null)

Retrieves a stored value by key. Returns the default value if the key doesn't exist.

$amount = $this->record->get('amount');

getMultiple(array $keys)

Retrieves multiple values at once by providing an array of keys. Returns an associative array.

$data = $this->record->getMultiple(['amount', 'recipient']);

has($key)

Checks if a key exists in the stored data. Returns true if the key exists.

if ($this->record->has('amount')) {
    // ...
}

delete($key)

Removes a stored value by key. Useful for clearing specific data when it's no longer needed.

$this->record->delete('temporary_data');

Using Records in States

Records are commonly used to collect data across multiple states and then use that data in a final state:

<?php

namespace App\Ussd\States;

use Vendor\LaravelUssd\Support\AbstractState;
use Vendor\LaravelUssd\Support\Context;
use Vendor\LaravelUssd\Support\UssdResponse;

class RecipientState extends AbstractState
{
    public function entry(Context $context): UssdResponse
    {
        return UssdResponse::continue('Enter recipient phone number:');
    }

    public function next(Context $context, string $input): ?string
    {
        $this->setContext($context);
        $this->record->set('recipient', $input);
        return AmountState::class;
    }
}

class AmountState extends AbstractState
{
    public function entry(Context $context): UssdResponse
    {
        return UssdResponse::continue('Enter amount:');
    }

    public function next(Context $context, string $input): ?string
    {
        $this->setContext($context);
        $this->record->set('amount', $input);
        return ConfirmState::class;
    }
}

class ConfirmState extends AbstractState
{
    public function entry(Context $context): UssdResponse
    {
        $this->setContext($context);
        // Retrieve stored data
        $recipient = $this->record->get('recipient');
        $amount = $this->record->get('amount');

        return UssdResponse::continue(
            "Confirm Transfer:\n" .
            "To: {$recipient}\n" .
            "Amount: {$amount}\n\n" .
            "1. Confirm\n" .
            "2. Cancel"
        );
    }

    public function next(Context $context, string $input): ?string
    {
        $this->setContext($context);
        if ($input === '1') {
            // Get all stored data for processing
            $transferData = $this->record->getMultiple(['recipient', 'amount']);
            // Process transfer...
            return ProcessTransferState::class;
        }

        return WelcomeState::class;
    }
}

Data Persistence

Record data is stored in the session context and persists across state transitions within the same USSD session. The data is automatically cleared when:

The session ends (user exits or session times out)
The session is explicitly cleared
The session expires based on the configured timeout

This ensures that data collected during a session is available throughout the entire flow but doesn't persist beyond the session lifecycle.