Faq Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dylvn/faq-bundle
   php bin/console dylvn:faq:install
   

   • Verify the bundle is enabled in config/bundles.php (OroCommerce compatibility assumed).

2. First Use Case

   • Navigate to Admin Panel > Content > FAQ to create a category and add FAQ items.
   • Localize questions/answers via the Localization tab (Oro’s standard workflow).
   • Publish the FAQ page at /faq (auto-configured route).

3. Where to Look First

   • Admin UI: src/Dylvn/FaqBundle/Resources/config/oro/navigation.yml (check for custom menu entries).
   • Templates: Override faq/index.html.twig in templates/DylvnFaqBundle/ for custom styling.
   • Services: dylvn.faq.manager for programmatic access to FAQ items/categories.

Implementation Patterns

Core Workflows

1. Admin Integration

   • CRUD: Extend Dylvn\FaqBundle\Entity\FaqItem or FaqCategory via Oro’s DataTransformer for custom fields.
   • Grids: Modify src/Dylvn/FaqBundle/Resources/config/oro/grid.yml to add columns (e.g., is_published).
   • Workflow: Use Oro’s Workflow system to add approval steps for FAQ items.

2. Frontend Display

   • Page Route: /faq is auto-configured via routing.yml. Override with:

     # config/routes/dylvn_faq.yaml
     dylvn_faq_index:
         path: /custom-faq
         defaults: { _controller: 'DylvnFaqBundle:Faq:index' }
     

   • Widget Integration: Insert FAQs into CMS pages via the faq_widget Twig function:

     {{ faq_widget({ category: 'support', limit: 3 }) }}
     

     • Configure widget settings in src/Dylvn/FaqBundle/Resources/config/oro/widget.yml.

3. API Access

   • Expose FAQ data via Oro’s REST API by extending src/Dylvn/FaqBundle/Resources/config/oro/api.yml:

     faq_items:
         type: Dylvn\FaqBundle\Entity\FaqItem
         short_name: faqitem
         api_doc:
             collection: true
             item: true
     

4. Localization

   • Localize questions/answers using Oro’s Localization tab in the admin.
   • Programmatic access:

     $faqItem = $faqManager->getItem($id);
     $question = $faqItem->getQuestion('en_US'); // Fallback to default locale
     

Integration Tips

• OroCommerce Catalog: Link FAQs to products via ProductFaqAssociation (extend FaqItem entity).
• Search: Index FAQ items in Oro’s Search system by implementing SearchableInterface.
• Events: Listen for faq.item.create or faq.category.update events:

  $dispatcher->addListener('faq.item.create', function ($event) {
      // Send notification or log FAQ creation
  });
  

Gotchas and Tips

Pitfalls

1. OroCommerce Dependency

   • Issue: Bundle assumes OroCommerce’s Content and Cms bundles. If using vanilla Laravel, expect missing services (e.g., oro_content.manager).
   • Fix: Override service definitions in config/packages/dylvn_faq.yaml or fork the bundle.

2. Localization Quirks

   • Issue: Localized fields may not sync if Oro’s Localization workflow is misconfigured.
   • Fix: Run php bin/console oro:localization:update after adding new locales.

3. Widget Caching

   • Issue: FAQ widgets may cache aggressively, causing stale content.
   • Fix: Clear cache after updates:

     php bin/console oro:cache:clear
     

4. Route Conflicts

   • Issue: /faq may conflict with existing routes (e.g., Symfony’s profiler).
   • Fix: Customize the route as shown in the Implementation Patterns section.

Debugging

• Admin UI Issues:
  • Check var/log/dev.log for Dylvn\FaqBundle errors.
  • Verify oro_entity_config and oro_entity_extension tables for entity mappings.
• Twig Errors:
  • Ensure DylvnFaqBundle is loaded before TwigBundle in config/bundles.php.

Extension Points

1. Custom Fields

   • Add fields to FaqItem via Doctrine extensions:

     // src/Dylvn/FaqBundle/Entity/FaqItem.php
     use Doctrine\ORM\Mapping as ORM;
     /**
      * @ORM\Column(type="boolean")
      */
     private $is_featured;
     

   • Update src/Dylvn/FaqBundle/Resources/config/oro/datagrids.yml to include the new field.

2. Custom Templates

   • Override templates in templates/DylvnFaqBundle/ (e.g., faq/item.html.twig for per-item styling).

3. Business Logic

   • Extend the FaqManager service:

     // src/Dylvn/FaqBundle/DependencyInjection/Compiler/FaqManagerPass.php
     public function process(ContainerBuilder $container) {
         $definition = $container->findDefinition('dylvn.faq.manager');
         $definition->addMethodCall('setCustomLogic', [$customLogic]);
     }
     

4. API Extensions

   • Add custom API actions by extending src/Dylvn/FaqBundle/Api/Action/FaqItemAction.php.

Performance Tips

• Batch Loading: Use FaqManager::getItemsByCategory($category, $limit) to avoid N+1 queries.
• Database Indexes: Add indexes to faq_item.category_id and faq_item.is_published for large datasets:

  CREATE INDEX idx_faq_item_category ON faq_item(category_id);