Disqus Bundle Laravel Package

Getting Started

1. Installation: Add the package via Composer:

   composer require aureka/disqus-bundle:dev-master
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3/2):

   Aureka\DisqusBundle\AurekaDisqusBundle::class => ['all' => true],
   

2. Basic Configuration: Add the minimal short_name to config/packages/aureka_disqus.yaml:

   aureka_disqus:
       short_name: 'your_disqus_shortname'
   

3. First Use Case: Implement Disqusable on your entity (e.g., BlogPost) and use the disqus() Twig function in a template:

   {{ disqus(blogPost) }}
   

Implementation Patterns

Entity Integration

• Implement Disqusable: Extend your entity (e.g., BlogPost) with getDisqusId() to uniquely identify threads:

  class BlogPost implements Disqusable {
      public function getDisqusId() {
          return $this->slug; // or UUID, ID, etc.
      }
  }
  

• Dynamic IDs: Generate IDs on-the-fly (e.g., using uniqid() or UUID) if not persisted.

Twig Integration

• Thread Rendering: Use {{ disqus(entity) }} in templates to embed Disqus threads. Place this after page content (Disqus requires DOM elements to exist).

• Comment Count: Add {{ disqus_count() }} to display comment counts (e.g., in search results or lists).

Single Sign-On (SSO)

1. Enable SSO: Configure config/packages/aureka_disqus.yaml:

   aureka_disqus:
       short_name: 'your_shortname'
       sso:
           enabled: true
           api_key: '%env(DISQUS_API_KEY)%'
           private_key: '%env(DISQUS_PRIVATE_KEY)%'
   

2. User Integration: Implement DisqusUser on your User entity:

   class User implements DisqusUser {
       public function getDisqusId() {
           return $this->id;
       }
   }
   

3. Authentication Hook: Extend the bundle’s DisqusSSOListener or create a custom event subscriber to sync Symfony users with Disqus during login/logout.

Caching

• Thread Scripts: The bundle dynamically loads Disqus scripts. For performance, cache the rendered output of disqus() in a fragment or Varnish if used frequently.

Gotchas and Tips

Pitfalls

1. Missing short_name: Without short_name in config, Twig functions will throw errors. Validate this early.

2. SSO Misconfiguration:

   • Ensure api_key and private_key are correctly set in Disqus admin under Applications > Single Sign-On.
   • Test SSO locally by simulating Disqus callbacks (use tools like ngrok for HTTPS).

3. Thread ID Collisions: getDisqusId() must return unique, URL-safe strings (e.g., avoid spaces or special chars). Sanitize IDs if needed:

   public function getDisqusId() {
       return strtolower(str_replace(' ', '-', $this->title));
   }
   

4. Script Loading Order: Disqus scripts must load after the DOM elements they target. Place {{ disqus() }} near the end of your template or use {{ disqus()|raw }} with JavaScript defer.

5. Symfony 4+ Kernel Changes: If upgrading from Symfony 3, ensure the bundle is registered in config/bundles.php (not AppKernel).

Debugging

• Check Console Errors: Disqus scripts may fail silently. Inspect browser console for 404 errors (missing scripts) or ReferenceError (missing DISQUS global).

• SSO Debugging: Enable Disqus debug mode in your app settings to log SSO issues. Use bin/console debug:config aureka_disqus to verify config.

Extension Points

1. Custom Twig Functions: Extend the bundle by overriding the DisqusTwigExtension or adding your own:

   // src/Service/CustomDisqusExtension.php
   class CustomDisqusExtension extends \Aureka\DisqusBundle\Twig\DisqusTwigExtension {
       public function getFunctions() {
           return array_merge(parent::getFunctions(), [
               new \Twig\TwigFunction('custom_disqus', [$this, 'customDisqusMethod']),
           ]);
       }
   }
   

2. Event Listeners: Subscribe to aureka.disqus.sso.login or aureka.disqus.sso.logout events to customize SSO behavior:

   // src/EventListener/DisqusSSOListener.php
   class DisqusSSOListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               'aureka.disqus.sso.login' => 'onSSOLogin',
           ];
       }
   }
   

3. Configuration Overrides: Override bundle config via config/packages/override/aureka_disqus.yaml:

   aureka_disqus:
       sso:
           enabled: false # Disable SSO for specific environments
   

Performance Tips

• Lazy-Load Threads: Use JavaScript to load Disqus threads only when clicked (e.g., via AJAX) to reduce initial load time.
• Environment-Specific Config: Disable SSO in dev environments:

  # config/packages/dev/aureka_disqus.yaml
  aureka_disqus:
      sso:
          enabled: false