Laravel Nps Laravel Package

Getting Started

Install the package and publish its assets:

composer require maize-tech/laravel-nps:^2.2
php artisan vendor:publish --provider="Maize\Nps\NpsServiceProvider"
php artisan migrate

Publish config, migrations, and (optionally) views using the tags documented in the README; then wire the package into your user model:

use Maize\Nps\Traits\HasNps;

class User extends Authenticatable
{
    use HasNps;
}

Point config/nps.php at your user model (nps.models.user) and adjust the survey question, scale, route prefix/middleware, and the command timings (delay, expire, frequency).

Look at these first, in order:

1. config/nps.php — every behavioral knob lives here.
2. src/Console/Commands/ — the nps:send command decides who gets a survey and when.
3. src/Models/Survey.php and SurveyAnswer.php — the data contract and route key.
4. routes/ and resources/views/ — what the recipient actually sees.
5. The HasNps trait — the relationship and helpers exposed on your user model.

First real use case: schedule the send command and let the package do the rest.

// routes/console.php (Laravel 11) or app/Console/Kernel.php
Schedule::command('nps:send')->daily();

Eligible users then get a survey record with a unique link; their submitted score and comment land in the survey-answer table, ready for reporting.

Implementation Patterns

Command-driven lifecycle. The package is not "always on." Surveys are created by running nps:send, which skips users who are too new (delay), already have an open survey (expire), or were surveyed too recently (frequency). Run it daily and treat those three config values as your product policy, not as infrastructure settings.

Custom models. Extend the package Survey/SurveyAnswer models when you need extra columns or casts, then swap the class names in config/nps.php. Keep the parent casts, route key, and table names intact.

Custom delivery channel. The package persists the survey; how it reaches the user is your call. Listen for the survey-created event (or override the mailable/notification in config) to send via your own notification, Slack, in-app banner, etc. This is the cleanest seam for multi-channel delivery without forking the package.

Custom UI. Publish the views and restyle them, or point the route at your own controller/view. Keep the form posting to the package endpoint, or replicate the answer-creation logic (score, comment, answered_at) so reporting stays consistent.

Reporting. NPS is computed from answers, not stored: promoters are 9–10, passives 7–8, detractors 0–6, and NPS = %promoters − %detractors. Build a small query/action around SurveyAnswer and scope it by date range and by the morph relation to your user model. Cache or snapshot the score per period if you display it on a dashboard.

Multi-tenant / segmented surveys. Because the survey belongs to the user via a morph relation, segment by adding a whereHas/global scope on your user model inside a custom command that wraps the package logic—or run nps:send per tenant with a scoped query.

Testing. Use RefreshDatabase, Carbon::setTestNow() to control the delay/frequency windows, and assert on survey records rather than on emails. For HTTP tests, act as the user and hit the generated survey URL (pull it from the model) rather than hand-building the route.

Gotchas and Tips

• Laravel 11 support only landed in 2.2.0. On Laravel 11 you must be on ^2.2; if you previously pinned --ignore-platform-reqs or a fork to install on L11, drop that workaround and upgrade properly. Re-publish migrations only if the package's stubs changed—compare before overwriting.
• "Nothing happens" usually means the scheduler. The command must be scheduled and the scheduler must actually run (schedule:run cron, or schedule:work locally). Check php artisan schedule:list before debugging package code.
• Config caching. Any change to config/nps.php requires php artisan config:cache (or a cache clear) in cached environments.
• Trait name collisions. HasNps adds relationships/helpers to your User; if you already have an nps method or relationship, alias the trait method or rename yours.
• Morph maps. If you call Relation::enforceMorphMap(), register the survey/user morph aliases or the polymorphic relation will fail to resolve.
• Published views go stale. Once published, upgrades won't touch your copies. Diff the package views against yours after each minor release, especially around form fields and CSRF/validation markup.
• Don't change the route key. The survey link is keyed on a non-sequential identifier; swapping route-model binding to id leaks volume and enables enumeration of other users' surveys.
• Timezones. delay, expire, and frequency are evaluated against timestamps; schedule the command in the same timezone you reason about in config, and be consistent with app.timezone.
• User deletion. The survey tables reference users polymorphically and typically won't cascade. Add a cleanup job/listener or a scheduled prune, or you'll accumulate orphaned surveys and skew reporting.
• Upgrade checklist for 2.2.0: bump the constraint, run the test suite, verify the service provider boots on L11, confirm scheduled command registration, and re-check that published config keys still match (config merges are shallow—new keys added upstream may need to be copied into your published file).