Flashcard Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require moo/flashcard
   php artisan package:discover
   php artisan migrate
   

   Verify migrations added flashcards_categories and flashcards_cards tables.

2. First Use Case:

   • Create a category via Tinker:

     $category = \Moo\Flashcard\Models\Category::create(['name' => 'Programming']);
     

   • Create a card (associate with category):

     $card = \Moo\Flashcard\Models\Card::create([
         'question' => 'What is Laravel?',
         'answer' => 'A PHP framework',
         'category_id' => $category->id
     ]);
     

3. Test API:

   • Fetch categories: GET /api/categories
   • Fetch cards with category: GET /api/cards?include=category

Implementation Patterns

Core Workflows

1. CRUD via API:

   • Use /api/cards and /api/categories endpoints for RESTful operations.
   • Example: Create a card via POST:

     POST /api/cards
     {
         "question": "Laravel ORM?",
         "answer": "Eloquent",
         "category_id": 1
     }
     

2. Filtering & Inclusion:

   • Filter cards by category:

     GET /api/cards?filter[category_id]=1
     

   • Include nested resources (e.g., category details):

     GET /api/cards?include=category
     

3. Custom Search:

   • Search across all fields (question/answer/name) via custom filter:

     GET /api/cards?filter[custom]=laravel
     

4. Model Integration:

   • Extend Moo\Flashcard\Models\Card or Category for custom logic:

     use Moo\Flashcard\Models\Card;
     
     class ExtendedCard extends Card {
         public function getFormattedQuestion() {
             return strtoupper($this->question);
         }
     }
     

5. Seeding:

   • Publish migrations/seeds:

     php artisan vendor:publish --provider="Moo\Flashcard\FlashcardServiceProvider"
     

   • Add seed data in Database\Seeders\FlashcardSeeder:

     $category = Category::create(['name' => 'Testing']);
     Card::create([
         'question' => 'What is TDD?',
         'answer' => 'Test-Driven Development',
         'category_id' => $category->id
     ]);
     

Integration Tips

1. API Resource Customization:

   • Override default API responses by publishing config:

     php artisan vendor:publish --tag=flashcard-config
     

   • Extend Moo\Flashcard\Http\Resources\CardResource in config/flashcard.php:

     'resources' => [
         'card' => \App\Http\Resources\CustomCardResource::class,
     ]
     

2. Authentication:

   • Protect API endpoints with Laravel middleware (e.g., auth:api):

     Route::middleware('auth:api')->group(function () {
         Route::apiResource('cards', \Moo\Flashcard\Http\Controllers\CardController::class);
     });
     

3. Frontend Integration:

   • Use axios or fetch to consume API:

     axios.get('/api/cards?include=category')
         .then(response => console.log(response.data.data));
     

4. Testing:

   • Test API endpoints with Laravel Dusk or PHPUnit:

     $response = $this->getJson('/api/cards');
     $response->assertStatus(200)
              ->assertJsonStructure([...]);
     

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • Last release in 2016; verify compatibility with Laravel 8/9/10 (may require patches).
   • Check for breaking changes in newer Laravel versions (e.g., route caching, API resource syntax).

2. API Versioning:

   • No built-in versioning; manually prefix routes (e.g., /v1/cards) if needed.

3. Pagination:

   • Default pagination uses lengthAwarePaginator; customize in config/flashcard.php:

     'pagination' => [
         'default' => 15,
         'max' => 100,
     ]
     

4. Database Schema:

   • Migrations assume category_id is nullable on cards table. Add constraints if needed:

     $table->foreignId('category_id')->constrained()->nullable();
     

5. CORS Issues:

   • If using frontend frameworks, ensure CORS middleware is configured:

     use Illuminate\Http\Request;
     use Illuminate\Support\Facades\Header;
     
     Header::set('Access-Control-Allow-Origin', '*');
     

Debugging

1. API Errors:

   • Check storage/logs/laravel.log for validation or query errors.
   • Enable API debug mode in config/flashcard.php:

     'debug' => env('FLASHCARD_DEBUG', false),
     

2. Route Conflicts:

   • Publish routes to inspect:

     php artisan vendor:publish --tag=flashcard-routes
     

   • Override routes in routes/flashcard.php if conflicts arise.

3. Performance:

   • Add indexes to question/answer columns for custom searches:

     Schema::table('flashcards_cards', function (Blueprint $table) {
         $table->index('question');
         $table->index('answer');
     });
     

Extension Points

1. Custom Fields:

   • Add fields to flashcards_cards table (e.g., difficulty, tags):

     Schema::table('flashcards_cards', function (Blueprint $table) {
         $table->string('difficulty')->nullable();
         $table->json('tags')->nullable();
     });
     

   • Update Card model to cast fields:

     protected $casts = [
         'tags' => 'array',
     ];
     

2. Event Listeners:

   • Listen for card/category creation:

     use Moo\Flashcard\Events\CardCreated;
     
     CardCreated::listen(function ($event) {
         Log::info("New card created: {$event->card->question}");
     });
     

3. Service Providers:

   • Bind custom repositories or services:

     $this->app->bind(
         \Moo\Flashcard\Repositories\CardRepository::class,
         \App\Repositories\CustomCardRepository::class
     );
     

4. Testing Utilities:

   • Create helper traits for tests:

     trait CreatesFlashcards {
         public function createCard(array $data = []) {
             return \Moo\Flashcard\Models\Card::create([
                 'question' => 'Test Question',
                 'answer' => 'Test Answer',
                 'category_id' => 1,
                 ...$data,
             ]);
         }
     }