- How do I integrate this package with Safaricom’s USSD API specifically?
- The package includes a built-in Safaricom provider adapter that abstracts API quirks. After installation, configure the provider in `config/ussd.php` under `providers` with your Safaricom credentials. The framework handles session IDs, rate limits, and response formatting automatically. For custom logic, extend the `SafaricomProvider` class or use middleware to pre-process requests.
- What’s the best way to handle large datasets in paginated menus (e.g., 1000+ records)?
- Use the `PaginatedMenu` class with a database-backed data provider (e.g., Eloquent). Enable Redis caching for menu templates and query results via `cache.driver = 'redis'` in the config. For high traffic, implement lazy-loading with `limit` and `offset` in your data provider, and consider async processing for analytics to avoid blocking the USSD gateway.
- Does this package support Laravel’s queue system for analytics or session persistence?
- Yes. The analytics module dispatches events (e.g., `MenuInteraction`) to Laravel’s queue system by default. Configure `analytics.queue = true` in the config to offload database writes. For session persistence, use the `SessionRepository` with a database driver and set `sessions.grace_period_minutes` to balance recovery time and resource usage.
- How do I mock USSD providers for unit testing?
- Use the `MockProvider` class included in the package’s testing utilities. In your test, replace the default provider with a mock instance via the `UssdFramework` constructor: `$framework = new UssdFramework([...], new MockProvider())`. The mock supports simulating responses, session IDs, and network errors for comprehensive test coverage of your menus and logic.
- Are there performance benchmarks for handling concurrent USSD sessions?
- The package is optimized for 10,000+ concurrent sessions with Redis caching and database indexing for session/analytics tables. Benchmark your setup by simulating load with tools like `ab` or `k6`, focusing on the `UssdController` response time. For peak loads, increase `session.grace_period_minutes` to 5–10 and use Laravel’s `throttle` middleware to limit requests per session.
- Can I use this package with a custom USSD provider not listed (e.g., a local telco)?
- Absolutely. Extend the `BaseProvider` class and implement the required methods (`sendRequest`, `parseResponse`). Register your provider in the config under `providers.custom` and set it as the default. The framework’s `ProviderFactory` will instantiate it dynamically. Document provider-specific quirks (e.g., session ID format) in your codebase.
- How does input sanitization work, and can I customize it?
- The package sanitizes USSD input via Laravel’s `Str::of()` and strips non-alphanumeric characters by default. Customize sanitization by overriding the `InputSanitizer` class or injecting a custom `FilterInterface` into the `UssdFramework` constructor. For security, enable the `security.rate_limiting` config to block brute-force attempts on sensitive menus.
- What’s the recommended setup for production monitoring of USSD flows?
- Instrument the package by extending the `UssdAnalytics` class to log custom events (e.g., failed sessions) to Laravel’s log channel or a monitoring tool like Datadog. Use middleware to track request latency and provider-specific errors. For observability, publish the `ussd` config and adjust `analytics.enabled` to `true` to capture user journeys in the database.
- Will this package work with Laravel 13 when it’s released, or should I wait?
- The package is designed for Laravel 12+ and leverages modern PHP 8.4+ features like enums and attributes. While Laravel 13 compatibility isn’t guaranteed yet, the modular architecture minimizes breaking changes. Monitor the [GitHub repo](https://github.com/Moffhub-Solutions/ussd_library) for updates or contribute a compatibility branch if needed.
- How do I implement a multi-step wizard (e.g., for airtime purchase with validation)?
- Use the `WizardMenu` class to chain steps with validation logic. Define each step as a closure in the `steps` array, where the last step returns a `UssdResponse` with the final action. For validation, throw `ValidationException` with error messages, which the framework automatically redirects to a retry step. Example: `$wizard->addStep('select_network', fn($session) => $session->input === '1' ? 'next' : 'retry')`.