Getting Started

Minimal Setup

Installation

composer require avoo/qcm-components

Add the package to your config/app.php providers (if not auto-discovered):

'providers' => [
    // ...
    Avoo\QcmComponents\QcmServiceProvider::class,
],

Publish Config (Optional) If the package includes default configurations:

php artisan vendor:publish --provider="Avoo\QcmComponents\QcmServiceProvider" --tag="config"

First Use Case: Basic Model Usage The package likely provides core QCM (Question, Choice, Model) interfaces/models. Start by inspecting the src/Models directory for classes like:
- Question
- Choice
- Answer
- Quiz
Example usage in a controller:
```
use Avoo\QcmComponents\Models\Question;

$question = Question::create([
    'title' => 'Sample Question',
    'description' => 'Test description',
]);
```
Key Entry Points
- Interfaces: Check src/Interfaces for contracts like QuestionInterface, ChoiceInterface.
- Traits: Look for reusable logic in src/Traits (e.g., HasChoices, HasAnswers).
- Service Classes: Inspect src/Services for business logic helpers (e.g., QuizEvaluator).

Implementation Patterns

Core Workflows

1. Building a Quiz System

Step 1: Define Questions Use the Question model to create questions with choices:

$question = Question::create(['title' => 'Capital of France?']);
$question->choices()->createMany([
    ['text' => 'Paris', 'is_correct' => true],
    ['text' => 'London', 'is_correct' => false],
]);

Step 2: Group Questions into Quizzes Attach questions to a Quiz model:

$quiz = Quiz::create(['title' => 'Geography Quiz']);
$quiz->questions()->attach([$question->id]);

Step 3: Evaluate Answers Use a service (e.g., QuizEvaluator) to score submissions:

$score = app(\Avoo\QcmComponents\Services\QuizEvaluator::class)
    ->evaluate($quiz, $userAnswers);

2. Extending Models

Custom Fields: Add attributes to models via accessors/mutators:

// In Question model
public function getFormattedTitleAttribute() {
    return strtoupper($this->title);
}

Relationships: Extend existing relationships (e.g., add tags to Question):

public function tags() {
    return $this->morphToMany(Tag::class, 'taggable');
}

3. API Integration

Resource Classes: Create API resources (e.g., QuestionResource) to shape responses:

namespace App\Http\Resources;
use Avoo\QcmComponents\Models\Question;
use Illuminate\Http\Resources\Json\JsonResource;

class QuestionResource extends JsonResource {
    public function toArray($request) {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'choices' => $this->choices,
        ];
    }
}

API Routes: Define routes for CRUD operations:

Route::apiResource('questions', QuestionController::class);

4. Validation

Form Requests: Validate quiz submissions:

namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;

class StoreQuizAnswerRequest extends FormRequest {
    public function rules() {
        return [
            'question_id' => 'required|exists:questions,id',
            'selected_choice' => 'required|exists:choices,id',
        ];
    }
}

5. Testing

Unit Tests: Mock models and services:

$question = Question::factory()->create();
$this->assertEquals('Paris', $question->choices->first()->text);

Feature Tests: Test API endpoints:

$response = $this->post('/api/quizzes', $quizData);
$response->assertStatus(201);

Integration Tips

Laravel Ecosystem

Eloquent: Leverage Laravel’s Eloquent features (e.g., hasMany, belongsTo) with the package’s models.

Events: Listen to model events (e.g., QuestionCreated) for side effects:

Question::created(function ($question) {
    Log::info("New question created: {$question->title}");
});

Policies: Secure models with Laravel’s authorization:

class QuestionPolicy {
    public function update(User $user, Question $question) {
        return $user->isAdmin();
    }
}

Frontend Integration

Blade Components: Create reusable components for rendering quizzes:

@component('qcm.question', ['question' => $question])
    @slot('choices')
        @foreach($question->choices as $choice)
            <label>{{ $choice->text }}</label>
        @endforeach
    @endslot
@endcomponent

Vue/React: Fetch data via API and use state management (e.g., Vuex) to track answers.

Performance

Caching: Cache quiz data if frequently accessed:

$quiz = Cache::remember("quiz:{$id}", now()->addHours(1), function () use ($id) {
    return Quiz::findOrFail($id);
});

Eager Loading: Avoid N+1 queries:

$questions = Question::with('choices', 'quiz')->get();

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

The package may use similar class names (e.g., Question). Ensure your app’s models are namespaced properly (e.g., App\Models\Question vs. Avoo\QcmComponents\Models\Question).

Fix: Use fully qualified names or aliases:

use Avoo\QcmComponents\Models\Question as QcmQuestion;

2. Missing Documentation

With no stars or dependents, assume minimal docs. Reverse-engineer usage by:
- Checking method signatures in src/Interfaces.
- Inspecting tests in tests/ (if any).
- Examining the src/Models directory for default behaviors.

3. Database Migrations

The package may not include migrations. Create your own:
```
php artisan make:migration create_questions_table
```

Example schema for questions:

Schema::create('questions', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('description')->nullable();
    $table->timestamps();
});

4. Service Binding

If the package uses service containers, bind interfaces to implementations in AppServiceProvider:

$this->app->bind(
    \Avoo\QcmComponents\Interfaces\QuizEvaluator::class,
    \Avoo\QcmComponents\Services\QuizEvaluator::class
);

5. License Compliance

The package is MIT-licensed, but ensure your app’s license aligns if redistributing.

Debugging Tips

1. Logging

Add debug logs to custom methods:

public function evaluate() {
    \Log::debug('Evaluating quiz', ['quiz_id' => $this->quiz->id]);
    // ...
}

2. DD/Dump

Use Laravel’s helpers to inspect objects:

dd($question->toArray()); // Dump and die
\Illuminate\Support\Facades\Log::debug(dump($quiz->questions));

3. Tinker

Test interactions in Tinker:

php artisan tinker
>>> $question = \Avoo\QcmComponents\Models\Question::first();
>>> $question->choices

Extension Points

1. Customizing Models

Override package models by publishing and modifying them:

php artisan vendor:publish --tag="qcm-components-migrations"

Then extend the published model:

namespace App\Models;
use Avoo\QcmComponents\Models\Question as BaseQuestion;

class Question extends BaseQuestion {
    // Add custom logic
}

2. Adding Behaviors

Use traits to add functionality:
```
trait
```

Qcm Components Laravel Package