PHPackages stats4sd/laravel-kobo-link - 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. stats4sd/laravel-kobo-link AbandonedArchivedLibrary stats4sd/laravel-kobo-link ========================== Manage KoboToolBox from your Laravel Project 1.0.2(4y ago)32554MITPHPPHP ^8.0 Since Apr 25Pushed 3y ago1 watchersCompare [ Source](https://github.com/stats4sd/laravel-kobo-link)[ Packagist](https://packagist.org/packages/stats4sd/laravel-kobo-link)[ Docs](https://github.com/stats4sd/laravel-kobo-link)[ RSS](/packages/stats4sd-laravel-kobo-link/feed)WikiDiscussions dev Synced 2d ago READMEChangelog (10)Dependencies (10)Versions (37)Used By (0) Manage KoboToolBox from your Laravel Project ============================================ [](#manage-kobotoolbox-from-your-laravel-project) [![Latest Version on Packagist](https://camo.githubusercontent.com/be365faa9ea75594c66badd3fea2af4d8bf4754d91a7e1dade395df4c92a8c34/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73746174733473642f6c61726176656c2d6b6f626f2d6c696e6b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/stats4sd/laravel-kobo-link)[![GitHub Tests Action Status](https://camo.githubusercontent.com/ad973fb7a4cde431e3f929e1e0ded427ba4332bd91aa772e0ae0dacf9f5444e5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f73746174733473642f6c61726176656c2d6b6f626f2d6c696e6b2f72756e2d74657374733f6c6162656c3d7465737473)](https://github.com/stats4sd/laravel-kobo-link/actions?query=workflow%3Arun-tests+branch%3Amaster)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/47d364c7ba695d7c0a962e8b429a916cf69d016f23a70a15f6cc4e2533aa440f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f73746174733473642f6c61726176656c2d6b6f626f2d6c696e6b2f436865636b253230262532306669782532307374796c696e673f6c6162656c3d636f64652532307374796c65)](https://github.com/stats4sd/laravel-kobo-link/actions?query=workflow%3A%22Check+%26+fix+styling%22+branch%3Amaster)[![Total Downloads](https://camo.githubusercontent.com/84744a811fa2226d71ca810940bca4c898c87fe411b4b43afa42e0f876f5044a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73746174733473642f6c61726176656c2d6b6f626f2d6c696e6b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/stats4sd/laravel-kobo-link) This package turns your Laravel / Laravel Backpack platform into a management system for data collected through [KoboToolBox](https://kf.kobotoolbox.org). It is designed to support research or survey data collection, and provides features beyond the scope of what KoboToolBox or other ODK Services can provide on their own. Who is it for? -------------- [](#who-is-it-for) Platforms built with this package can help with the following scenarios: 1. Multiple teams need to use the same set of ODK forms provided by a central team, but need to retain ownership of their data (i.e. the data of all teams cannot simply be pooled together and made accessible to everyone) 2. The data collection is complex, where data from some forms needs to be processed and then shared back to other forms as customised CSV files. 1. Including the possibility that each team requires different data to be made available in their ODK forms. > ### IMPORTANT NOTE > > [](#important-note) > > This is not an off-the-shelf data management solution! It requires you to build your own Laravel platform and pull in this package via composer. It does not handle the processing of the data collected through your ODK forms, but it provides hooks to enable you to write your own processing scripts to run automatically when ODK submissions are pulled in from KoboToolBox. You can provide your own database structures / data models to organise the processed data however you see fit. Installation ------------ [](#installation) You can install the package via composer: ``` composer require stats4sd/laravel-kobo-link ``` You can publish and run the migrations with: ``` php artisan vendor:publish --provider="Stats4sd\KoboLink\KoboLinkServiceProvider" --tag="kobo-link-migrations" php artisan migrate ``` ### Setup Required Configuration Variables [](#setup-required-configuration-variables) In order to link up to a KoBoToolbox server, you must provide the following environment variables: ``` KOBO_ENDPOINT= KOBO_OLD_ENDPOINT= KOBO_USERNAME= KOBO_PASSWORD= DATA_PROCESSING_CLASS= ``` The two endpoint variables should be the full url to the server you are using. For example: ``` ## If you use the 'for everyone else' server provided by the team at https://kobotoolbox.org: KOBO_ENDPOINT=https://kf.kobotoolbox.org, KOBO_OLD_ENDPOINT=https://kc.kobotoolbox.org ## If you use their humanitarian server, use: KOBO_ENDPOINT=https://kobo.humanitarianresponse.info KOBO_OLD_ENDPOINT=https://kc.humanitarianresponse.info ``` The platform requires a 'primary' user account on the KoboToolbox server to manage deployments of ODK forms. This account will *own* every form published by the platform. We **highly** recommend creating an account specifically for the Laravel platform. If the platform uses an account also used by others, there is a chance that your database will become out of sync with the forms present on KoBoToolbox, and the form management functions may stop working correctly. Setup Data Models ----------------- [](#setup-data-models) This packages assumes that the following models exist in the platform: - `\App\Models\User` The package provides the following models: Feature / PurposeModelDatabase TableCommentsTeam ManagementTeamteamsIf the platform will be used by a single group who share data (e.g. one research project, or a single survey), you can simply create 1 team.Team ManagementInviteinvitesThis package includes a system of inviting users to specific teams. This feature will hopefully be seperated into a separate package in the future, as it is not a core part of the ODK / KoboToolbox system.ODK Form ManagementXlsformxlsformsThis stores every ODK form present in the platform. Forms can be either deployed to *every* team, or to a single team, based on needs. This allows most teams to use a 'common' form, but gives you the option to add a custom version of a form for a specific team if required.ODK Form ManagementTeamXlsformteam\_xlsformThe link table for ODK forms and teams. This table will contain 1 record for every unique form that gets deployed to KoboToolbox.Submission ProcessingSubmissionsubmissionsEvery submission that is pulled from KoboToolbox is stored in this table. The main contents is stored as a JSON field, so the table structure is the same regardless of the form's structure. You can then write the processing scripts to 'unpack' this JSON into whatever formats you require.Submission ProcessingDatamapdatamapsDatamaps handle the link to the actual processing scripts. Each ODK form can be linked to 1 or more data maps, and submissions will be processed using *all* linked data maps.TODO: add section explaining how the data maps work, and include real examples. ### Publishing The config [](#publishing-the-config) If you add the required ENV variables to your application, there should be no need to publish the config file. However, you may wish to do so anyway. To publish the file, use: ``` php artisan vendor:publish --provider="Stats4sd\KoboLink\KoboLinkServiceProvider" --tag="kobo-link-config" ``` Add the Front-end ----------------- [](#add-the-front-end) This package assumes you are using Laravel Backpack as your admin panel. As such, it comes with a set of CrudControllers for managing your XLS forms and submissions. It also assumes that you are able to build your own front-end to allow team members to access their data, manage forms etc. You can add links to these crud panels into your sidebar file located at resourcs\\views\\vendor\\backpack\\base\\inc\\sidebar\_content.blade.php: TODO: Add example team UI for team members to manage their own forms, submissions and team members/invites. ``` Teams XLSForms Submissions ``` Writing Data Processing Scripts ------------------------------- [](#writing-data-processing-scripts) The Datamap model includes a `process(Submission $submission)` method. This hooks into a Datamap Service class, which is designed to be overwritten by you. Each platform will require a different set of data processing scripts tailored to the data being collected, so we have tried to make it easy to include these scripts in your platform. Here is the short version: 1. Create a "DatamapService" class, and add the fully qualified path to this class into your .env file. E.g.: `DATA_PROCESSING_CLASS="\App\Services\DatamapService::class"` 2. Write the methods you want to use to process a submisison. The method should accept a single Submission parameter, and can then do anything you want to 'process' the submission. e.g.: ``` public function testForm(Stats4sd\KoboLink\Models\Submission $submission) { /* PROCESS SUBMISSION DATA */ /* get the submission contents */ $data = $submission->content; // the Datamap model includes a helper function to remove the lengthy group names from the submission: $data = $this->removeGroupNames($data); /** Now $data is a set of key-value pairs that can be processed however you need, including : * - creating new database entries via Eloquent, * - manual SQL querying, * - passing the submission to an external process like R or Python running on the server. * * Repeat groups need to be handled manually - they will be left with the 'value' as a nested json array. **/ /* At the end, you should update the $submission entry: */ $submission->processed = 1; /* If your processing throws errors, e.g. validation errors, you can add those to the "errors" array: */ $submission->errors = [ 'variable_name' => 'Error message', 'variable_2' => 'Error message', ]; /** If your processing has created new Eloquent models, you can add those to the "entries" array. * - This allows you to easily identify what records each submission created; * - It is used in the 'reprocessSubmissions()' method to delete previously created entries and avoid duplication. **/ // example, if your submission created 1 Household entry and 2 HouseholdMember entries: $submission->entries = [ "App\Models\Household" => [$household->id], "App\Models\HouseholdMember" => [$memberOne->id, $memberTwo->id], ]; $submission->save(); } ``` TODO: include real examples :) 3. Now, you should create a Datamap entry with an ID of the method name. For the example above, you would add the following record to the `datamaps` table: - `INSERT INTO datamaps SET id = "testForm", title = "Test Form Processing";` It is vital to match the datamap ID to the method name, as this is how the datamap chooses which method to run during processing. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [Dave Mills](https://github.com/stats4sd) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 33 — LowBetter than 75% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity17 Limited adoption so far Community13 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 69% 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 ~10 days Recently: every ~52 days Total 33 Last Release 1514d ago Major Versions 0.2.6 → 1.0.02021-10-15 PHP version history (3 changes)0.0.2PHP ^7.4 0.1.3PHP ^7.4|^8.0 1.0.0PHP ^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/2a7ba5ca40fde83339632231db5f6a95522c1de137f0029a338a5d90fa449a46?d=identicon)[dave-mills](/maintainers/dave-mills) ![](https://www.gravatar.com/avatar/e794ce6c1705bd8592bc7eb32dece5eb2dfa9773d695bc418ca0c16e263a132d?d=identicon)[Dan Tang](/maintainers/Dan%20Tang) --- Top Contributors [![dave-mills](https://avatars.githubusercontent.com/u/5711101?v=4)](https://github.com/dave-mills "dave-mills (89 commits)")[![dan-tang-ssd](https://avatars.githubusercontent.com/u/86968034?v=4)](https://github.com/dan-tang-ssd "dan-tang-ssd (40 commits)") --- Tags laravelstats4sdlaravel-kobo-link ### Code Quality TestsPHPUnit Static AnalysisPsalm Type Coverage Yes ### Embed Badge ![Health badge](/badges/stats4sd-laravel-kobo-link/health.svg) ``` [![Health](https://phpackages.com/badges/stats4sd-laravel-kobo-link/health.svg)](https://phpackages.com/packages/stats4sd-laravel-kobo-link) ``` ### Alternatives [bagisto/bagisto Bagisto Laravel E-Commerce 26.2k161.6k7](/packages/bagisto-bagisto)[unopim/unopim UnoPim Laravel PIM 9.4k1.8k](/packages/unopim-unopim)[vormkracht10/laravel-mails Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app. 24149.7k](/packages/vormkracht10-laravel-mails)[danihidayatx/image-optimizer Optimize your Filament images before they reach your database. Forked from joshembling/image-optimizer for Filament v4 & v5 support. 254.4k](/packages/danihidayatx-image-optimizer)[thomascombe/backpack-async-export This is a package to manage async export in Backpack for Laravel 1528.5k](/packages/thomascombe-backpack-async-export)[tapp/filament-form-builder User facing form builder using Filament components 131.2k1](/packages/tapp-filament-form-builder) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)