Survey Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ekyna/survey-bundle
   

   Add to config/bundles.php:

   Ekyna\SurveyBundle\EkynaSurveyBundle::class => ['all' => true],
   

2. Database Migration: Run migrations (check vendor/ekyna/survey-bundle/migrations/ for SQL files or adapt to Laravel’s schema builder).

3. First Use Case: Create a survey via the bundle’s CLI or manually via the Survey model:

   use Ekyna\SurveyBundle\Entity\Survey;
   
   $survey = new Survey();
   $survey->setTitle('Customer Feedback');
   $survey->setDescription('Quick feedback on our service');
   $survey->setActive(true);
   $survey->setCreatedAt(new \DateTime());
   $surveyManager->saveSurvey($survey); // Inject SurveyManager service
   

4. Key Classes to Explore:

   • SurveyManager: Core service for CRUD operations.
   • Question/Answer entities: Define survey structure.
   • SurveyResponse: Store participant submissions.

Implementation Patterns

Workflows

1. Survey Creation:

   • Use SurveyManager to create surveys programmatically or via a form (e.g., Symfony forms in Laravel’s context).
   • Example:

     $question = new \Ekyna\SurveyBundle\Entity\Question();
     $question->setTitle('How satisfied are you?');
     $question->setType('multiple_choice'); // Limited to basic types per README
     $question->addAnswer(new \Ekyna\SurveyBundle\Entity\Answer('Very satisfied'));
     $survey->addQuestion($question);
     

2. Participant Responses:

   • Store responses via SurveyResponse:

     $response = new \Ekyna\SurveyBundle\Entity\SurveyResponse();
     $response->setSurvey($survey);
     $response->setParticipantEmail('user@example.com');
     $response->setSubmittedAt(new \DateTime());
     $response->addAnswer(new \Ekyna\SurveyBundle\Entity\ResponseAnswer($question, 'Very satisfied'));
     $surveyManager->saveResponse($response);
     

3. Displaying Surveys:

   • Fetch active surveys:

     $activeSurveys = $surveyManager->findActiveSurveys();
     

   • Render questions/answers in a view (e.g., Blade):

     @foreach($survey->getQuestions() as $question)
         <h3>{{ $question->getTitle() }}</h3>
         @foreach($question->getAnswers() as $answer)
             <label>{{ $answer->getText() }}</label>
         @endforeach
     @endforeach
     

4. Integration with Laravel:

   • Service Provider: Bind the bundle’s services to Laravel’s container in AppServiceProvider:

     $this->app->bind(
         \Ekyna\SurveyBundle\Manager\SurveyManager::class,
         \Ekyna\SurveyBundle\Manager\SurveyManager::class
     );
     

   • Middleware: Restrict survey access (e.g., logged-in users only):

     public function handle($request, Closure $next) {
         if (!$request->user()) abort(403);
         return $next($request);
     }
     

5. API Endpoints (if needed):

   • Use Laravel’s routes to expose survey data:

     Route::get('/surveys/{id}', [SurveyController::class, 'show']);
     

Gotchas and Tips

Pitfalls

1. Outdated Codebase:

   • Last release in 2015: Expect missing features (e.g., no support for modern Laravel versions or PHP 8+). Test thoroughly.
   • Question/Answer Types: README mentions "TODO" for types like text or integer. Only basic types (e.g., multiple_choice) may work out-of-the-box.

2. Database Schema:

   • Migrations are not Laravel-compatible by default. Adapt SQL to Laravel’s schema builder or use raw queries:

     Schema::create('survey_questions', function (Blueprint $table) {
         $table->id();
         $table->string('title');
         $table->string('type')->default('multiple_choice');
         // ... other fields
     });
     

3. Service Injection:

   • The bundle assumes Symfony’s dependency injection. Manually bind services in Laravel’s container (see Implementation Patterns).

4. No Built-in Admin Panel:

   • No pre-built backend for managing surveys. Create a custom admin interface or use Tinker for quick testing:

     php artisan tinker
     >>> $survey = new \Ekyna\SurveyBundle\Entity\Survey();
     >>> $survey->setTitle('Test');
     >>> $surveyManager->saveSurvey($survey);
     

5. Responses vs. Submissions:

   • Clarify the distinction between SurveyResponse (participant submissions) and ResponseAnswer (individual answers). Ensure data is saved hierarchically:

     $response->addAnswer(new \Ekyna\SurveyBundle\Entity\ResponseAnswer($question, $selectedAnswerText));
     

Debugging Tips

1. Enable Debugging:

   • Add logging to track survey operations:

     \Log::info('Survey saved', ['id' => $survey->getId()]);
     

2. Check Entity Relationships:

   • Use dd() to inspect relationships:

     dd($survey->getQuestions()->first()->getAnswers());
     

3. Override Bundle Classes:

   • Extend entities (e.g., Survey) to add missing methods:

     namespace App\Entity;
     use Ekyna\SurveyBundle\Entity\Survey as BaseSurvey;
     
     class Survey extends BaseSurvey {
         public function getActiveQuestions() {
             return $this->getQuestions()->filter(fn($q) => $q->isActive());
         }
     }
     

Extension Points

1. Custom Question Types:

   • Override the Question entity to support new types (e.g., text, rating):

     namespace App\Entity;
     use Ekyna\SurveyBundle\Entity\Question as BaseQuestion;
     
     class Question extends BaseQuestion {
         const TYPE_RATING = 'rating';
     
         public function isRatingQuestion() {
             return $this->getType() === self::TYPE_RATING;
         }
     }
     

2. Validation:

   • Add Laravel validation rules to survey submissions:

     use Illuminate\Support\Facades\Validator;
     
     $validator = Validator::make($request->all(), [
         'email' => 'required|email',
         'answers.*' => 'required',
     ]);
     

3. Events:

   • Listen for survey events (if the bundle emits them) or create custom events:

     event(new \App\Events\SurveySubmitted($response));
     

4. Testing:

   • Write feature tests for survey flows:

     public function test_survey_submission() {
         $response = $this->post('/surveys/1/submit', [
             'answers' => ['q1' => 'option1']
         ]);
         $response->assertStatus(200);
     }