PHPackages                             asharif88/kobo-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. asharif88/kobo-sdk

ActiveLibrary[API Development](/categories/api)

asharif88/kobo-sdk
==================

A PHP SDK to easily work with KoboToolbox API

0.5.0(6mo ago)011MITPHPPHP 8.3.\*

Since Nov 4Pushed 6mo agoCompare

[ Source](https://github.com/Asharif88/kobo-sdk)[ Packagist](https://packagist.org/packages/asharif88/kobo-sdk)[ RSS](/packages/asharif88-kobo-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (11)Versions (3)Used By (0)

Kobo SDK — PHP client for KoboToolbox APIs
==========================================

[](#kobo-sdk--php-client-for-kobotoolbox-apis)

[![PHP](https://camo.githubusercontent.com/500094cff5896afce2bf75f9340bac0ee58ba1c8954c3349c1813078305788ac/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e332d626c75652e737667)](https://www.php.net/) [![License](https://camo.githubusercontent.com/891419a00e04aa0e311068fa8a04eec92cab4f7026c76278279bf2a1da50e578/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d6c69676874677265792e737667)](LICENSE)

Lightweight PHP SDK to interact with [KoboToolbox](https://www.kobotoolbox.org/) API. Simplifies integration with Kobo deployments by wrapping common API endpoints and handling request/response formatting.

Table of contents

- [Overview](#overview)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
    - [Initialization](#initialization)
    - [Fetching Data](#fetching-data)
    - [Submitting Responses](#submitting-responses)
        - [Submit JSON](#submit-json)
        - [Submit XML](#submit-xml)
- [Implementation notes](#implementation-notes)
- [Handling file (binary) responses](#handling-file-binary-responses)
- [Utilities](#utilities)
- [Tests](#tests)
- [Contributing](#contributing)
- [License](#license)

### Overview

[](#overview)

This SDK provides a small, focused wrapper around common KoboToolbox API endpoints (v2). It includes helpers to:

- List and inspect assets (forms)
- Retrieve form content and submissions
- Submit new submissions as JSON or XML
- Download submission attachments (images, media)

The library prefers PSR-7/PSR-17 factories for creating requests and streams and a PSR-18 HTTP client for sending requests.

### Requirements

[](#requirements)

- PHP 8.3
- Composer
- A PSR-18 compatible HTTP client (the project uses discovery by default)
- PSR-17 request and stream factories

### Installation

[](#installation)

Install via Composer:

```
composer require asharif88/kobo-sdk
```

(For development or to run tests, install dev dependencies as listed in `composer.json`.)

### Configuration

[](#configuration)

The client expects a configuration array with at least the `url` and `api_key` values. Optionally provide `url_v1` when using endpoints that require the v1 API (media/submissions):

```
$config = [
    'url'     => 'https://kc.example.org',   // API v2 base URL
    'api_key' => 'YOUR_API_TOKEN',
    'url_v1'  => 'https://kc-v1.example.org' // optional, required for some endpoints
];
```

### Usage

[](#usage)

#### Initialization

[](#initialization)

Create a client instance and use the main helpers:

```
use KoboSDK\Client;

$config = [
    'url'     => 'https://kc.example.org',
    'api_key' => 'YOUR_API_KEY',
    'url_v1'  => 'https://kc-v1.example.org',
];

$client = new Client(config: $config);
```

#### Fetching Data

[](#fetching-data)

```
// List assets (forms)
$assets = $client->getAssets();

// Get full form metadata
// This function return an Asset object with permissions, type, content, uid & name properties
$form  = $client->asset('FORM_UID');

// Get the questions, and answers with labels of a specific form
$form = $client->assetContent('FORM_UID');

// Get all submissions of a specific form
$subs  = $client->getSubmissions('FORM_UID');

// getSubmissions supports filtering by date & pagination:
$subs  = $client->getSubmissions('FORM_UID', [
    'start' => new DateTimeImmutable('2024-01-01T00:00:00'),
    'end'   => new DateTimeImmutable('2024-01-31T23:59:59'),
    'offset'     => 0,
    'limit'     => 50,
]);
```

```
// You can get a specific submission with metadata fields removed
$sub   = $client->submission('FORM_UID', 'SUBMISSION_ID');

// or get the full submission with metadata using submissionRaw()
$sub   = $client->submissionRaw('FORM_UID', 'SUBMISSION_ID');

// Get Enketo Link
$link  = $client->getEditLink('FORM_UID', 'SUBMISSION_ID');

// You can also get a list of all attachments you have access to (requires v1 URL)
$attachments = $client->getMedia();
```

#### Submitting Responses

[](#submitting-responses)

##### Submit JSON

[](#submit-json)

```
$data = [
    'field1' => 'value',
    'field2' => 'value',
    'nested' => [
        'subfield1' => 'value'
        'subfield2' => 'multiple values'
    ]
];

$response = $client->submit('FORM_UID', $data);
```

##### Submit XML

[](#submit-xml)

*recommended*

```
$data = [
    'field1' => 'value',
    'field2' => 'value',
    'nested' => [
        'subfield1' => 'value'
        'subfield2' => 'multiple values'
    ]
];

$response = $client->submitXml('FORM_UID', $data);
```

### Implementation notes

[](#implementation-notes)

- v1 URLs are required for some endpoints (media, submissions). The SDK allows specifying a separate `url_v1` in the config.
- Implements the `/v1/submission.xml` endpoint, in both JSON and XML.

Note

XML submissions are preferred JSON submissions might cause issues with Kobo deployments that expect certain metadata or structure.

- Formats the request body to match Kobo's complex nested structure.
- When submitting XML the SDK will load the form asset to find a `deployment__uuid` which is required by many Kobo deployments. If the form has no deployment UUID the SDK will throw an exception.
- The library ensures `meta.instanceID` exists and will generate a `uuid:...` instance ID if missing.

### Handling file (binary) responses

[](#handling-file-binary-responses)

When the API returns binary data (for example a JPG attachment) you should treat the response body as a stream and persist it rather than trying to JSON-decode it. The SDK exposes attachment handling which returns the PSR-7 stream plus headers and content type.

Example approach:

```
$attachment = $client->getAttachment('FORM_UID', 'SUBMISSION_ID', 'ATTACHMENT_ID');

// $attachment['content'] is a PSR-7 stream; save to disk:
$stream = $attachment['content'];
$target = fopen('/tmp/photo.jpg', 'wb');
$stream->rewind();
while (! $stream->eof()) {
    fwrite($target, $stream->read(8192));
}
fclose($target);
```

You can also get the attachment by its XPath:

```
$attachment = $client->getSubmissionAttachments('FORM_UID', 'SUBMISSION_ID', 'group/photo');
```

### Utilities

[](#utilities)

The `Utils` class contains helpful functions used across the SDK:

- `Utils::arrayToXml(array $data, SimpleXMLElement &$xml)` — convert PHP arrays to XML nodes
- `Utils::createTempXmlFile(string $xml)` — write XML to a temp file (used when building multipart bodies)
- `Utils::formatPermissions(array $permissions)` — normalize permission structures returned by the API

### Tests

[](#tests)

The project includes PHPUnit tests. Run them with:

```
composer test
# or directly
vendor/bin/phpunit
```

### Contributing

[](#contributing)

Contributions, bug reports and pull requests are welcome. Feel free to submit a PR or open an issue.

### License

[](#license)

This project is licensed under the MIT License — see the `LICENSE` file for details.

###  Health Score

32

—

LowBetter than 71% of packages

Maintenance72

Regular maintenance activity

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

186d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7bc3352a55b3d4643b40bfa1d42b4a3729f2729300e65e924a2e8b09fd31964f?d=identicon)[asharif88](/maintainers/asharif88)

---

Top Contributors

[![Asharif88](https://avatars.githubusercontent.com/u/1073094?v=4)](https://github.com/Asharif88 "Asharif88 (6 commits)")

---

Tags

apikobokobotoolboxkobotoolbox-apiodkphpsdkphpapisdkodkkobokobotoolbox

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/asharif88-kobo-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/asharif88-kobo-sdk/health.svg)](https://phpackages.com/packages/asharif88-kobo-sdk)
```

###  Alternatives

[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k22.6M232](/packages/openai-php-client)[mozex/anthropic-php

Anthropic PHP is a supercharged community-maintained PHP API client that allows you to interact with Anthropic API.

46365.1k13](/packages/mozex-anthropic-php)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

963.1M35](/packages/getbrevo-brevo-php)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[deeplcom/deepl-php

Official DeepL API Client Library

2616.2M66](/packages/deeplcom-deepl-php)[deepseek-php/deepseek-php-client

deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities.

47073.9k5](/packages/deepseek-php-deepseek-php-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)