Speedtest Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require efficience-it/speedtest-bundle
   

   Ensure EfficienceIt\SpeedtestBundle\SpeedtestBundle::class is registered in config/bundles.php.

2. Route Configuration: Create config/routes/speedtest.yaml with:

   speedtest:
       resource: '@SpeedtestBundle/Resources/config/routes.yaml'
       prefix: /speedtest
   

   This auto-generates /speedtest routes (e.g., /speedtest, /speedtest/results).

3. First Use Case: Embed the speedtest in a Twig template by calling the service in a controller:

   use EfficienceIt\SpeedtestBundle\Service\SpeedtestService;
   
   public function index(SpeedtestService $speedtest): Response
   {
       return $this->render('home/index.html.twig', [
           'speedtest' => $speedtest->displaySpeedtest(),
       ]);
   }
   

   Include the output in Twig:

   {{ speedtest|raw }}
   

Implementation Patterns

Core Workflows

1. Standalone Speedtest Page: Use the predefined routes (/speedtest, /speedtest/results) for a dedicated page. No additional controller logic required.

2. Embedding in Existing Pages:

   • Call displaySpeedtest() in any controller and pass the output to Twig.
   • Customize appearance via CSS/JS (the bundle outputs a self-contained iframe-like widget).

3. Programmatic Testing: Use the SpeedtestService to trigger tests programmatically:

   $results = $speedtest->runTest(); // Returns raw data (download/upload speeds, latency)
   

   Format results for display:

   <div class="speedtest-results">
       Download: {{ results.download }} Mbps
       Upload: {{ results.upload }} Mbps
   </div>
   

4. Configuration Overrides: Override default settings (e.g., test servers, UI theme) via config/packages/speedtest.yaml:

   speedtest:
       servers: ['us', 'eu']  # Custom server regions
       theme: 'dark'          # 'light' or 'dark'
   

Integration Tips

• Symfony Flex: Works seamlessly with Symfony 5.4+ (Flex auto-configures routes/bundles).
• Asset Management: Bundle includes its own JS/CSS. Use {{ EncoreEntryLink }} if integrating with Webpack Encore.
• Caching: Results are cached by default (configurable via speedtest.cache.ttl in YAML).

Gotchas and Tips

Pitfalls

1. Route Conflicts: The /speedtest prefix may clash with existing routes. Verify uniqueness in config/routes.yaml.

2. JavaScript Dependencies: The bundle relies on external JS libraries (e.g., Chart.js). Ensure no global conflicts if your app uses the same libraries.

3. CORS Issues: Speedtest results depend on external servers. If testing behind a proxy/firewall, whitelist required domains (e.g., librespeed.org).

4. Twig Auto-escaping: displaySpeedtest() outputs raw HTML. Escape dynamically if embedding in unsafe contexts:

   {{ speedtest|striptags }}  {# Sanitize if needed #}
   

Debugging

• No Output?: Check:

  • bundles.php registration.
  • Route dump (php bin/console debug:router | grep speedtest).
  • Browser console for JS errors (bundle assets may fail to load).

• Slow Tests: Limit servers in config to reduce latency:

  speedtest:
      servers: ['eu-west']
  

Extension Points

1. Custom Templates: Override Twig templates in templates/speedtest/ (e.g., speedtest.html.twig).

2. API Extensions: Extend SpeedtestService to add custom metrics:

   // src/Service/CustomSpeedtestService.php
   class CustomSpeedtestService extends SpeedtestService
   {
       public function getPing(): float
       {
           // Custom logic
       }
   }
   

   Bind in services.yaml:

   EfficienceIt\SpeedtestBundle\Service\SpeedtestService: '@custom_speedtest_service'
   

3. Localization: Translate UI strings by overriding translations/speedtest.en.yaml (if supported in future updates).

4. Headless Mode: Disable UI and use raw data via runTest() for CLI tools or APIs.