Accesseo Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev elao/accesseo:^1.0@beta
   

   Add to config/bundles.php:

   Elao\Bundle\Accesseo\ElaoAccesseoBundle::class => ['dev' => true],
   

2. First Use Case

   • Access the Symfony Profiler (/_profiler/) in your dev environment.
   • Navigate to the "Accesseo" tab to see Accessibility and SEO insights.
   • No additional configuration is required for basic usage.

3. Where to Look First

   • Profiler Tab: Check the "Accesseo" panel for real-time insights.
   • Configuration: Review config/packages/elao_accesseo.yaml for customization.

Implementation Patterns

Workflows

1. Integrating with CI/CD

   • Use Accesseo in local development and staging to catch issues early.
   • Example: Add a script in phpunit.xml to fail builds if accessibility/SEO issues exceed a threshold:

     <env name="ACCESSEO_THRESHOLD" value="5"/>
     

2. Customizing Insights

   • Extend the bundle by creating a custom profiler panel that integrates Accesseo data:

     use Elao\Bundle\Accesseo\Panel\AccessibilityPanel;
     use Elao\Bundle\Accesseo\Panel\SeoPanel;
     
     // In a custom bundle's ProfilerSubscriber
     public function onCollect(ProfilerSectionEvent $event) {
         $event->getPanel()->add(AccessibilityPanel::createFromRequest($event->getRequest()));
         $event->getPanel()->add(SeoPanel::createFromRequest($event->getRequest()));
     }
     

3. Icon Readability Checks

   • Configure custom icon classes in elao_accesseo.yaml:

     elao_accesseo:
       icons:
         - fa-icon
         - custom-icon
     

   • Ensure icons have proper ARIA labels or alt text for screen readers.

4. Disabling Panels Selectively

   • Disable SEO or Accessibility panels in dev/staging:

     elao_accesseo:
       enabled_seo_panel: false
       enabled_accessibility_panel: true
     

Integration Tips

• Pair with PHP-CS-Fixer: Enforce accessibility attributes (e.g., alt, aria-*) via static analysis.
• Symfony UX: Combine with Webpack Encore to audit frontend assets for contrast/readability.
• API Endpoints: Use Accesseo’s data to log issues to a centralized dashboard (e.g., Sentry, Datadog).

Gotchas and Tips

Pitfalls

1. Profiler Overhead

   • Accesseo runs only in dev mode (enabled: true in bundles.php).
   • Avoid enabling in production—it’s designed for debugging.

2. False Positives in Accessibility

   • Custom icons without aria-hidden="true" may trigger false alerts.
   • Fix: Exclude non-critical icons via config or add aria-hidden manually.

3. SEO Panel Limitations

   • Relies on Symfony’s HTTP cache—clear cache (php bin/console cache:clear) if insights don’t update.
   • Meta tags: Ensure your templates use Twig’s {% block meta %} for consistent SEO audits.

4. Beta Package Quirks

   • No LTS: The package is in beta; monitor for breaking changes in minor updates.
   • Symfony Version Lock: Tested on Symfony 4.4–5.4; may need adjustments for older/new versions.

Debugging

• Blank Profiler Tab?

  • Verify ElaoAccesseoBundle is enabled in bundles.php.
  • Check elao_accesseo.yaml for syntax errors (YAML is strict).

• Missing Icons in Accessibility

  • Ensure icon classes in config match those in your HTML (case-sensitive).

• SEO Issues Not Updating

  • Clear Symfony cache and restart the dev server:

    php bin/console cache:clear
    symfony-server-start
    

Extension Points

1. Custom Insights

   • Extend the bundle by creating a new panel class (e.g., PerformancePanel) that reuses Accesseo’s data structure:

     namespace App\Panel;
     use Elao\Bundle\Accesseo\Panel\AbstractPanel;
     
     class CustomPanel extends AbstractPanel {
         protected function getInsights() {
             return [
                 'custom_metric' => $this->getCustomValue(),
             ];
         }
     }
     

2. Hook into Data Collection

   • Override the AccesseoCollector service to inject custom logic:

     # config/services.yaml
     Elao\Bundle\Accesseo\Collector\AccesseoCollector:
       tags: [data_collector]
       arguments:
         $customService: '@app.custom_service'
     

3. Export Insights

   • Use the collector’s data to generate CSV/JSON reports:

     $collector = $container->get('elao_accesseo.collector');
     $insights = $collector->collect($request);
     file_put_contents('accesseo_report.json', json_encode($insights));