Easy Faq Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require agence-adeliom/easy-faq-bundle
   

   Ensure your composer.json includes the GitHub recipes endpoint for Flex compatibility.

2. Database Setup Run migrations:

   php artisan migrate  # Laravel equivalent (adjust if using Symfony CLI)
   

   (Note: The bundle is Symfony-focused, but Laravel users can adapt Doctrine migrations via doctrine/dbal or laravel-doctrine/orm.)

3. First Use Case Access the FAQ CRUD interface in EasyAdmin (/admin/faq). Create a FAQ entry with:

   • Question (string)
   • Answer (text)
   • Order (integer, for sorting)
   • Active (boolean, visibility toggle)

Where to Look First

• Bundle Docs: GitHub README (Symfony-specific; adapt for Laravel).
• EasyAdmin Integration: Check config/packages/easy_admin.yaml for FAQ CRUD configuration.
• Entity Class: src/Entity/FAQ.php (customize fields/methods as needed).
• Templates: Override Twig templates in templates/easy_faq/ for frontend display.

Implementation Patterns

Core Workflows

1. Admin Management

   • Use EasyAdmin’s built-in CRUD to add/edit FAQs via /admin/faq.
   • Customize fields in config/easy_admin.yaml:

     easy_admin:
         entities:
             FAQ:
                 class: App\Entity\FAQ
                 list:
                     fields: ['question', 'active', 'order']
                 form:
                     fields: ['question', 'answer', 'active', 'order']
     

2. Frontend Display

   • Fetch FAQs in a controller:

     // Laravel (adapted from Symfony)
     $faqs = $entityManager->getRepository(FAQ::class)->findBy(['active' => true]);
     return view('faq.index', compact('faqs'));
     

   • Render with a Twig loop (or Blade in Laravel):

     {% for faq in faqs %}
         <div class="faq-item">
             <h3>{{ faq.question }}</h3>
             <p>{{ faq.answer }}</p>
         </div>
     {% endfor %}
     

3. API Access (Optional)

   • Expose FAQs via API (Laravel example):

     Route::get('/api/faqs', function () {
         return FAQ::where('active', true)->orderBy('order')->get();
     });
     

Integration Tips

• Laravel-Symfony Bridge:

  • Use doctrine/orm for Doctrine compatibility in Laravel:

    composer require doctrine/orm
    

  • Configure config/packages/doctrine.yaml to match Laravel’s database settings.

• Custom Fields: Extend the FAQ entity to add fields (e.g., category, tags):

  // src/Entity/FAQ.php
  #[ORM\Column(type: 'string', length: 255, nullable: true)]
  private ?string $category = null;
  

• EasyAdmin Extensions: Add filters/sorting in easy_admin.yaml:

  list:
      actions: ['show', 'edit', 'delete']
      filters: ['question', 'active']
      sort: ['order']
  

• Localization: Use Symfony’s translation system or Laravel’s trans() helper for multilingual FAQs.

Gotchas and Tips

Pitfalls

1. Doctrine Migrations in Laravel

   • The bundle assumes Symfony’s Doctrine setup. For Laravel:
     • Manually create migrations or use laravel-doctrine/orm.
     • Ensure App\Entity\FAQ is properly namespaced and annotated.

2. EasyAdmin Version Mismatch

   • The bundle targets EasyAdmin 3.x. Verify compatibility:

     composer require easycorp/easyadmin-bundle:^3.4
     

   • Laravel users: Use spatie/laravel-easyadmin as a wrapper.

3. Template Overrides

   • Twig templates in templates/easy_faq/ may not exist by default. Create them if extending:

     templates/
         easy_faq/
             crud/
                 index.html.twig
     

4. Ordering Quirks

   • The order field is numeric but may not auto-sort in EasyAdmin. Add a custom OrderableInterface or use a Sortable trait.

Debugging

• Missing CRUD Route: Ensure FAQ is listed in easy_admin.yaml and the bundle is enabled in config/bundles.php (Symfony) or config/app.php (Laravel).

• Database Errors: Check migration files in src/Migrations/ for Laravel or migrations/ for Symfony. Run:

  php artisan doctrine:migrations:migrate  # Laravel (if using doctrine/orm)
  

• Symfony-Specific Issues:

  • Clear cache after config changes:

    php bin/console cache:clear
    

  • Laravel equivalent: php artisan cache:clear.

Extension Points

1. Custom FAQ Types Extend the FAQ entity to support different content types (e.g., rich text, images):

   #[ORM\Column(type: 'json', nullable: true)]
   private ?array $media = null;
   

2. Event Listeners Hook into FAQ lifecycle events (e.g., log changes):

   // src/EventListener/FAQListener.php
   #[AsEventListener(event: 'prePersist', method: 'onPrePersist')]
   public function onPrePersist(FAQ $faq) {
       // Add logic (e.g., auto-generate slugs)
   }
   

3. API Resources (Laravel) Use Laravel’s API Resources to shape FAQ responses:

   php artisan make:resource FAQResource
   

   // app/Http/Resources/FAQResource.php
   public function toArray($request) {
       return [
           'question' => $this->question,
           'answer' => $this->answer,
           'active' => $this->active,
       ];
   }
   

4. Search Functionality Add a search field in EasyAdmin:

   list:
       fields: ['question', 'active']
       search:
           fields: ['question']
   

   For Laravel, use a scope:

   public function scopeSearch($query, $search) {
       return $query->where('question', 'LIKE', "%{$search}%");
   }