Laravel Surveyhero

https://github.com/statikbe/laravel-surveyhero
Admin
Laravel Surveyhero is a Laravel package that imports Surveyhero surveys, questions, answers, and...
Tokens:9,808
Snippets:93
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Install the package using Composer with the command 'composer require statikbe/laravel-surveyhero'.

```bash
composer require statikbe/laravel-surveyhero
```

--------------------------------

### Customize questions mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Example configuration for custom question mappings. Includes 'questions' key with per-question settings like 'type', 'field', 'answer_mapping', and 'mapped_data_type'. Comments show example question types.

```php
'question_mapping' => [
    [
        'survey_id' => 1234567,
        'collectors' => [986362,524948],
        'use_resume_link' => true,
        'questions' => [
            #example numeric input
            1000005 => [
                'question_id' => 1000005,
                'type' => 'text',
                'field' => 'custom_question_field_name',
            ],
            #example choice list
            1000002 => [
                'question_id' => 1000002,
                'type' => 'choices',
                'field' => 'another_custom_question_field_name',
                'answer_mapping' => [
                    13509166 => 10,
                    13509167 => 1000,
                    13509168 => 1337,
                ],
                'mapped_data_type' => 'int',
            ],
        ]
    ],
    ...
];
```

--------------------------------

### Run upgrade migration

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

Run the upgrade migration to add the new columns: surveys.use_resume_link (boolean, default false) and survey_responses.resume_link (nullable string). The migration is guarded with Schema::hasColumn() checks, so it is safe on fresh installs.

```shell
php artisan migrate
```

--------------------------------

### Text input question mapping example

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Example mapping for a text input question. The 'field' key is the identifier in your database for querying responses.

```php
1000005 => [
    'question_id' => 1000005,
    'type' => 'text',
    'field' => 'question_5',
],
```

--------------------------------

### Configure survey IDs in question_mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Example configuration for the surveyhero.php file. Add survey_id entries to specify which surveys to import. The ellipsis (...) indicates additional entries.

```php
'question_mapping' => [
    [
        'survey_id' => 1234567,
    ],
    [
        'survey_id' => 4897492,
    ],
    ...
];
```

--------------------------------

### Configure collectors in question_mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Example configuration for overriding collectors. Collectors in the config file overwrite those in the database. Use env('COLLECTOR_IDS') to read from environment variables.

```php
'question_mapping' => [
    [
        'survey_id' => 1234567,
        'collectors' => [986362,524948],
    ],
    [
        'survey_id' => 4897492,
        'collectors' => env('COLLECTOR_IDS'),
    ],
    ...
];
```

--------------------------------

### Implement Export marker on WithMultipleSheets class

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

In v4, a class that only implements WithMultipleSheets must also implement the new Export concern. This example shows a custom export class extending the package's SurveyExport and implementing Export. Every sheet returned must implement Export or Import.

```php
use Maatwebsite\Excel\Concerns\Export;

class MySurveyExport extends \Statikbe\Surveyhero\Exports\SurveyExport implements Export
{
    // ...
}
```

--------------------------------

### Import questions and answers command

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Imports all survey questions and answers associated with their (translated) label for a given survey ID or all surveys. Use '--survey=22333' to configure a specific survey and '--fresh' to wipe SurveyQuestions and SurveyAnswers before reimporting.

```shell
php artisan surveyhero:import-questions-and-answers
```

--------------------------------

### Run tests with Composer

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Use this command to run the package's test suite, which is built with Pest. It covers import services, HTTP client, DTOs, question/answer creators, and response creators.

```bash
composer test
```

--------------------------------

### Import surveys command

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Run this artisan command to import surveys. Use --survey=1234567 to import a specific survey, --all to import all, and --fresh to wipe and reimport all surveys.

```shell
php artisan surveyhero:import-surveys
```

--------------------------------

### Publish and run migrations

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Publish the migration files with the 'surveyhero-migrations' tag and then run the migrations. Edit the configuration file first if you want to customize the default data model.

```bash
php artisan vendor:publish --tag="surveyhero-migrations"
```

```bash
php artisan migrate
```

--------------------------------

### Run surveyhero:map --updateDatabase to generate mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

Generates the mapping in the database. Run this command after adding the migration.

```shell
php artisan surveyhero:map --updateDatabase
```

--------------------------------

### Generate mapping config file

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Run this command to generate a complete question_mapping PHP file (surveyhero_mapping.php) in the project root. The file contains the PHP array for copy-pasting into your config.

```shell
php artisan surveyhero:map --generateConfig
```

--------------------------------

### Import responses command

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Imports all survey responses for a given survey ID or all surveys. Requires at least one Survey record with a Surveyhero ID. Use '--survey=22333' to configure a specific survey and '--fresh' to wipe SurveyResponses and SurveyQuestionResponses before reimporting.

```shell
php artisan surveyhero:import-responses
```

--------------------------------

### List webhooks command

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Use this artisan command to list all webhooks for a specific survey. Provide the survey ID as a parameter.

```shell
php artisan surveyhero:list-webhooks --survey=12345
```

--------------------------------

### Publish config file

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Publish the configuration file using the 'surveyhero-config' tag. Check configuration options before customizing the data model.

```bash
php artisan vendor:publish --tag="surveyhero-config"
```

--------------------------------

### Facade webhook routes

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Use this convenience function on the facade to automatically register webhook routes. Add it to your api.php file.

```php
use Statikbe\Surveyhero\Facades\Surveyhero;

Surveyhero::webhookRoutes();
```

--------------------------------

### Configure custom Eloquent models in 'models' config

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Set your own Eloquent model classes in the 'models' configuration variable. The package expects certain column names; if you implement your own models without subclassing the defaults, you must implement the Contract interfaces in Statikbe\Surveyhero\Contracts.

```php
'models' => [
    'survey' => Statikbe\Surveyhero\Models\Survey::class,
    'survey_question' => Statikbe\Surveyhero\Models\SurveyQuestion::class,
    'survey_answer' => Statikbe\Surveyhero\Models\SurveyAnswer::class,
    'survey_response' => Statikbe\Surveyhero\Models\SurveyResponse::class,
    'survey_question_response' => Statikbe\Surveyhero\Models\SurveyQuestionResponse::class,
],
```

--------------------------------

### Add webhook command

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Use this artisan command to add a webhook to your Survey. Specify the event type and URL as parameters.

```shell
php artisan surveyhero:add-webhooks --eventType=response.completed --url=https://webhook.site/complete-response
```

--------------------------------

### Input list mapping with subquestion_mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Maps an input list question. Each input is imported as a separate SurveyQuestion row keyed by its 'input_id'. The 'subquestion_mapping' mirrors Choice Table but without an 'answer_mapping'; set 'mapped_data_type' to 'int' for numeric inputs, otherwise 'string'.

```php
1000005 => [
    'question_id' => 1000005,
    'type' => 'input_list',
    'mapped_data_type' => 'string',
    'subquestion_mapping' => [
        1745983 => ['question_id' => 1745983, 'field' => 'contact_name'],
        1745984 => ['question_id' => 1745984, 'field' => 'contact_address'],
    ],
],
```

--------------------------------

### Migration to add collector_ids, question_mapping, and surveyhero_element_id columns

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

Adds the required columns to the 'surveys' and 'survey_questions' tables. Remember to change the table names to your custom configured names if necessary.

```php
Schema::table('surveys', function (Blueprint $table) {
    $table->json('collector_ids')->after('name')->nullable();
    $table->json('question_mapping')->after('name')->nullable();
});

Schema::table('survey_questions', function (Blueprint $table) {
    $table->bigInteger('surveyhero_element_id')->after('surveyhero_question_id')->nullable();
});
```

--------------------------------

### Extend SurveyheroWebhookController

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

Extend the package's SurveyheroWebhookController to handle pre- and post-import logic. The base controller manages validation, survey lookup, collector filtering, import, and error wrapping. Throw UnwantedResponseNotImportedException in handlePreImport to skip the import and return 200 OK.

```php
use Statikbe\Surveyhero\Http\Controllers\Api\SurveyheroWebhookController as BaseWebhookController;
use Statikbe\Surveyhero\Models\Survey;
use Statikbe\Surveyhero\Services\Info\ResponseImportInfo;

class MyWebhookController extends BaseWebhookController
{
    protected function handlePreImport(Survey $survey, array $collectors, array $responseData): void
    {
        // Runs before the import. Throw UnwantedResponseNotImportedException to skip the import
        // and return 200 OK (so Surveyhero does not retry).
    }

    protected function handlePostImport(Survey $survey, array $collectors, array $responseData, ?ResponseImportInfo $responseInfo): void
    {
        // Runs after a successful import.
        // $responseInfo is null if the response was already imported previously.
    }
}
```

--------------------------------

### Set Surveyhero API credentials in .env

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Required environment variables for authenticating API requests. Set these in the .env file before using the package.

```plaintext
SURVEYHERO_API_USERNAME=1234567890
SURVEYHERO_API_PASSWORD=qwertyuiopasdfghjklzxcvbnm
```

--------------------------------

### New question_mapping config structure

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

New question_mapping config structure supporting a nested questions key and a use_resume_link flag. Existing entries with only survey_id and collectors continue to work, opting out of config-level question mapping.

```php
// New structure
[
    'survey_id'       => 1234567,
    'collectors'      => [9876543],
    'use_resume_link' => false,
    'questions'       => [
        // question mapping entries
    ],
],
```

--------------------------------

### Configure rate limit fallback duration

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Optional environment variable to set the fallback sleep duration (in seconds) when the Retry-After header is missing from a 429 response.

```plaintext
SURVEYHERO_RATE_LIMIT_FALLBACK=60
```

--------------------------------

### Configure custom table names and foreign keys in 'table_names' config

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Change table names and foreign key column names by editing the 'table_names' configuration variable. The 'foreign_key' value is the column name used to refer to the corresponding table.

```php
'table_names' => [
    'surveys' => [
        'name' => 'surveys',
        'foreign_key' => 'survey_id',
    ],
    'survey_questions' => [
        'name' => 'survey_questions',
        'foreign_key' => 'survey_question_id',
    ],
    'survey_answers' => [
        'name' => 'survey_answers',
        'foreign_key' => 'survey_answer_id',
    ],
    'survey_responses' => [
        'name' => 'survey_responses',
        'foreign_key' => 'survey_response_id',
    ],
    'survey_question_responses' => [
        'name' => 'survey_question_responses',
        'foreign_key' => 'survey_question_response_id',
    ],
],
```

--------------------------------

### Choice table mapping with subquestion_mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Maps a Likert scale choice table. Each row becomes a subquestion with its own 'question_id' and 'field'. The 'answer_mapping' operates identically to Choice List; you can specify a per-question 'answer_mapping' if the mapping differs.

```php
1000001 => [
    'question_id' => 1000001,
    'type' => 'choice_table',
    'subquestion_mapping' => [
        13509163 => [
            'question_id' => 13509163,
            'field' => 'question_1',
        ],
        13509164 => [
            'question_id' => 13509164,
            'field' => 'question_2',
        ],
        13509165 => [
            'question_id' => 13509165,
            'field' => 'question_3',
            'answer_mapping' => [
                13509163 => 3,
                13509164 => 2,
                13509165 => 1,
            ],
        ],
    ],
    'answer_mapping' => [
        13509163 => 1,
        13509164 => 2,
        13509165 => 3,
    ],
    'mapped_data_type' => 'int', //can also be string if the values are strings in answer_mapping
]
```

--------------------------------

### Image choice list mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Maps an image choice list question. Works identically to Choice List; images are stored in Surveyhero and not imported, only the selected choice ID is mapped.

```php
1000003 => [
    'question_id' => 1000003,
    'type' => 'image_choice_list',
    'field' => 'question_3',
    'answer_mapping' => [
        13509100 => 1,
        13509101 => 2,
        13509102 => 3,
    ],
    'mapped_data_type' => 'int',
],
```

--------------------------------

### Export responses command

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Use this artisan command to export survey responses to a spreadsheet. Customize the export by adding link parameters and extra response columns.

```shell
php artisan surveyhero:responses-export --survey=1451654 --linkParameter=organisation --extraResponseCol=survey_completed --extraResponseCol=survey_start_date
```

--------------------------------

### Configure surveyhero_link_parameters_mapping in config file

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Configuration array for mapping link parameters. The 'username' key maps directly to the 'user_name' column. The 'user_uuid' key maps to the 'user_id' column using the User model, comparing against the 'uuid' column and selecting the 'id' field. This configuration is placed in the Laravel config file after adding the necessary migration columns.

```php
'surveyhero_link_parameters_mapping' => [
     'username' => [
         'name' => 'user_name'                        (the target column name on the survey_response table)
     ],
     'user_uuid' => [
         'name' => 'user_id',                         (the target column name on the survey_response table)
         'entity' => \App\Models\User::class,         (the model to query)
         'value' => 'uuid',                           (the column on the entity to query)
         'field' => 'id',                             (the column on the entity to select)
     ],
],
```

--------------------------------

### Webhook handler route

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Add this route to your api.php file to handle response.completed webhooks. It uses the default SurveyheroWebhookController.

```php
use Statikbe\Surveyhero\Http\Controllers\Api\SurveyheroWebhookController;

Route::post('/process-surveyhero-response-completed', [SurveyheroWebhookController::class, 'handleResponseCompletedWebhook'])
    ->name('surveyhero_response_webhook');
```

--------------------------------

### File upload mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Maps a file upload question. Stores the full URL to the uploaded file (prepended with the Surveyhero API base URL) as a string in 'converted_string_value'. No 'answer_mapping' is needed; file name and size are not stored.

```php
1000004 => [
    'question_id' => 1000004,
    'type' => 'file_upload',
    'field' => 'question_4',
    'mapped_data_type' => 'string',
],
```

--------------------------------

### Add rate_limit_fallback_seconds config

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

Add the rate_limit_fallback_seconds key to your published config. It controls how long the connector sleeps when a 429 rate-limit response is received without a Retry-After header. In webhook/HTTP contexts, this sleep blocks a PHP-FPM worker, so keep it below your server's request timeout or queue the import job.

```php
// config/surveyhero.php
'rate_limit_fallback_seconds' => env('SURVEYHERO_RATE_LIMIT_FALLBACK', 60),
```

--------------------------------

### Numeric input mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Maps a numeric SurveyHero question to a field. Only integer support is currently implemented.

```php
1000006 => [
    'question_id' => 1000006,
    'type' => 'number',
    'field' => 'age',
    'mapped_data_type' => 'int',
],
```

--------------------------------

### Choice list mapping with answer_mapping

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Maps a choice list question. Requires an 'answer_mapping' that maps Surveyhero choice IDs to converted values. Set 'mapped_data_type' to 'int' or 'string' depending on the values data type of 'answer_mapping'.

```php
1000002 => [
    'question_id' => 1000002,
    'type' => 'choices',
    'field' => 'question_4',
    'answer_mapping' => [
        13509166 => 1,
        13509167 => 2,
        13509168 => 3,
    ],
    'mapped_data_type' => 'int',
],
```

--------------------------------

### Delete webhook command

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/README.md

Use this artisan command to delete a webhook from a survey. Provide the survey ID and webhook ID as parameters.

```shell
php artisan surveyhero:delete-webhook --survey=12345 --webhook=2553
```

--------------------------------

### Add return types to custom export sheets (Before/After)

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

Laravel-Excel 4 requires native types on every concern. Update your custom sheets' signatures as shown. The 'Before' block shows the v3 signatures without return types; the 'After' block shows the v4 signatures with return types. Other common methods to update include headings(): array, title(): string, array(): array, and registerEvents(): array.

```php
// Before (v3)
public function query() { ... }
public function collection() { ... }
public function map($row): array { ... }
```

```php
// After (v4)
public function query(): Builder|EloquentBuilder|Relation { ... }
public function collection(): Enumerable { ... }
public function map(mixed $row): array { ... }
```

--------------------------------

### Update models config to app models

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

Update the models array in your published config to reference your app models. Without this, the SurveyheroRegistrar resolves the vendor base models, bypassing your customisations such as soft deletes and extra relationships.

```php
'models' => [
    'survey'                   => \App\Models\Survey::class,
    'survey_question'          => \App\Models\SurveyQuestion::class,
    'survey_answer'            => \App\Models\SurveyAnswer::class,
    'survey_response'          => \App\Models\SurveyResponse::class,
    'survey_question_response' => \App\Models\SurveyQuestionResponse::class,
],
```

--------------------------------

### Remove HasFactory from custom models

Source: https://github.com/statikbe/laravel-surveyhero/blob/main/UPGRADING.md

Remove the HasFactory trait from models extending package models to avoid a PHP 8.2 fatal error. The parent class already applies the trait, so keeping it causes a declaration incompatibility.

```php
// Before
class SurveyResponse extends \Statikbe\Surveyhero\Models\SurveyResponse
{
    use HasFactory; // <-- remove this
    use SoftDeletes;
}

// After
class SurveyResponse extends \Statikbe\Surveyhero\Models\SurveyResponse
{
    use SoftDeletes;
}
```
Tokens:
Raw