Faq Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation via utils/prepare_vendors script (preferred): Run the project-specific script to symlink the bundle into /src/Awaresoft. Alternative: Manually clone the repo into /vendor and symlink /src/Awaresoft.

2. Clear Cache:

   php bin/console cache:clear
   

3. Register the Bundle: Add to config/bundles.php:

   return [
       // ...
       Awaresoft\FaqBundle\AwaresoftFaqBundle::class => ['all' => true],
   ];
   

4. Database Setup: Run migrations (if using Doctrine):

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

5. First Use Case: Access the FAQ admin panel via /admin/app/faq (SonataAdmin integration). Create a category (e.g., "General") and add questions/answers.

Key Files to Review

• Configuration: config/packages/awaresoft_faq.yaml (if auto-generated).
• Entities: /src/Awaresoft/FaqBundle/Entity/ (e.g., FaqCategory, FaqItem).
• Admin Class: /src/Awaresoft/FaqBundle/Admin/FaqAdmin.php (SonataAdmin configuration).

Implementation Patterns

Core Workflows

1. CRUD via SonataAdmin

• Create/Edit FAQs: Use the SonataAdmin UI (/admin/app/faq) to manage categories/questions/answers. Example: Add a "Troubleshooting" category with nested FAQ items.

• Custom Fields: Extend the FaqItem entity to add fields (e.g., isFeatured, priority):

  // src/Entity/FaqItemExtension.php
  use Doctrine\ORM\Mapping as ORM;
  
  class FaqItemExtension {
      /**
       * @ORM\Column(type="boolean")
       */
      private $isFeatured = false;
  }
  

  Update the FaqAdmin class to include the new field in the form.

2. Frontend Display

• Twig Integration: Fetch FAQs by category in templates:

  {% set faqs = app.service('awaresoft_faq.faq_manager').findByCategory('general') %}
  {% for faq in faqs %}
      <h3>{{ faq.question }}</h3>
      <p>{{ faq.answer }}</p>
  {% endfor %}
  

• API Endpoint: Create a controller to expose FAQs as JSON:

  // src/Controller/FaqController.php
  use Awaresoft\FaqBundle\Manager\FaqManager;
  
  class FaqController extends AbstractController {
      public function index(FaqManager $faqManager) {
          return $this->json($faqManager->findAll());
      }
  }
  

3. Search Functionality

• Doctrine QueryBuilder: Search FAQs by keyword:

  $faqManager->createQueryBuilder('f')
      ->where('f.question LIKE :query')
      ->setParameter('query', '%' . $searchTerm . '%')
      ->getQuery()
      ->getResult();
  

4. Fixtures for Testing

• Load Sample Data: Use DoctrineFixturesBundle to populate FAQs:

  // src/DataFixtures/FaqFixtures.php
  public function load(ObjectManager $manager) {
      $category = new FaqCategory();
      $category->setName('Support');
  
      $faq = new FaqItem();
      $faq->setQuestion('How do I reset my password?')
          ->setAnswer('Visit /reset-password.')
          ->setCategory($category);
  
      $manager->persist($category);
      $manager->persist($faq);
      $manager->flush();
  }
  

  Load fixtures with:

  php bin/console doctrine:fixtures:load
  

Integration Tips

• Translation Support: Extend the FaqItem entity to support translations (e.g., using gedmo/translatable):

  # config/packages/gedmo_translatable.yaml
  gedmo_translatable:
      default_lifecycle: translate
  

• Event Listeners: Trigger actions on FAQ updates (e.g., log changes):

  // src/EventListener/FaqUpdateListener.php
  use Awaresoft\FaqBundle\Entity\FaqItem;
  use Doctrine\Common\EventSubscriber;
  use Doctrine\ORM\Event\LifecycleEventArgs;
  
  class FaqUpdateListener implements EventSubscriber {
      public function postUpdate(LifecycleEventArgs $args) {
          $faq = $args->getObject();
          if ($faq instanceof FaqItem) {
              // Log or notify about changes
          }
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\FaqUpdateListener:
          tags: [doctrine.event_subscriber]
  

Gotchas and Tips

Pitfalls

1. Symlink Issues:

   • If the /src/Awaresoft symlink breaks, clear Composer autoload:

     composer dump-autoload
     

   • Ensure autoload_psr4.php removes old vendor paths before symlinking.

2. SonataAdmin Conflicts:

   • If the admin panel fails to load, check:
     • Bundle registration order in config/bundles.php (SonataAdmin must load before AwaresoftFaqBundle).
     • Permissions in FaqAdmin.php:

       protected function configureTabMenu(TabsMenuBuilder $builder, array $options) {
           $builder
               ->add('List', 'list')
               ->add('Create', 'create');
       }
       

3. Doctrine Entity Mapping:

   • Avoid naming conflicts with existing entities. Prefix custom fields (e.g., app_is_featured).

4. Version Lock:

   • The bundle targets Symfony 2.x (deprecated). Test thoroughly if upgrading Symfony.

Debugging

• Enable Debug Mode:

  # config/packages/dev/awaresoft_faq.yaml
  awaresoft_faq:
      debug: true
  

  Logs SQL queries and admin actions to var/log/dev.log.

• Common Errors:

  • "Class not found": Verify symlinks and run composer dump-autoload.
  • Admin panel blank: Check browser console for JS errors (SonataAdmin dependencies).
  • Migration failures: Run php bin/console doctrine:schema:validate to validate entities.

Extension Points

1. Custom Query Methods: Add methods to FaqManager:

   // src/Manager/FaqManager.php
   public function findFeaturedFaqs() {
       return $this->createQueryBuilder('f')
           ->where('f.isFeatured = :featured')
           ->setParameter('featured', true)
           ->getQuery()
           ->getResult();
   }
   

2. Override Templates: Copy SonataAdmin templates to templates/bundles/awaresoftfaq/ to customize rendering.

3. Add Validation: Extend FaqItem validation in setUp() of FaqAdmin:

   protected function configureFormFields(FormMapper $formMapper) {
       $formMapper
           ->add('question', 'text', [
               'constraints' => [
                   new NotBlank(),
                   new Length(['min' => 10]),
               ],
           ]);
   }
   

4. API Filtering: Use Symfony Serializer for custom JSON output:

   // src/Serializer/FaqNormalizer.php
   use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
   
   class FaqNormalizer implements NormalizerInterface {
       public function normalize($object, $format = null, array $context = []) {
           return [
               'question' => $object->getQuestion(),
               'answer' => $object->getAnswer(),
               'slug' => $object->getSlug(),
           ];
       }
   }
   

   Register in services.yaml:

   services:
       App\Serializer\FaqNormalizer:
           tags: [serializer.normalizer]
   

Configuration Quirks

• Default Category: The bundle may auto-create a "Default" category. Disable in config:

  awaresoft_faq:
      auto_create_default_category: false
  

• Slug Generation: Customize slug behavior in FaqItem:

  use Gedmo\Mapping\Annotation as Gedmo;
  
  /**
   * @Gedmo\Slug(fields={"question"})
   */
  private $slug;
  

• Caching: Clear SonataAdmin cache after changes:

  php bin/console sonata:admin:cache:clear