Navitia Profiler Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require canaltp/navitia-profiler-bundle
   

   Register the bundle in config/app.php under extra.bundles (if using Symfony/Laravel bridge) or follow Laravel-specific integration instructions (if applicable).

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="CanalTP\NavitiaProfilerBundle\NavitiaProfilerBundle" --tag="config"
   

   Update config/navitia_profiler.php with your Navitia API credentials and endpoint:

   'navitia' => [
       'url' => env('NAVITIA_API_URL', 'https://api.navitia.io'),
       'app_id' => env('NAVITIA_APP_ID'),
       'app_secret' => env('NAVITIA_APP_SECRET'),
   ],
   

3. First Use Case Profile a route query in a controller:

   use CanalTP\NavitiaProfilerBundle\Services\NavitiaProfiler;
   
   public function profileRoute(Request $request, NavitiaProfiler $profiler)
   {
       $data = $profiler->profileRoute(
           $request->input('origin'),
           $request->input('destination'),
           $request->input('datetime', now()->format('Y-m-d\TH:i:s'))
       );
       return response()->json($data);
   }
   

Implementation Patterns

Workflows

1. Real-Time Profiling Use the profiler in API endpoints to log and analyze route queries dynamically:

   $profiler->profileJourney(
       $origin,
       $destination,
       $datetime,
       ['co2_optimized' => true]
   );
   

2. Batch Processing Process historical data in a queue job:

   public function handle()
   {
       $profiler = app(NavitiaProfiler::class);
       $routes = $this->getHistoricalRoutes(); // Fetch from DB
       foreach ($routes as $route) {
           $profiler->profileRoute($route['origin'], $route['destination'], $route['datetime']);
       }
   }
   

3. Integration with Laravel Scout Extend Scout’s search logic with Navitia’s data:

   class NavitiaScoutEngine extends ScoutEngine
   {
       public function performSearch($query)
       {
           $profiler = app(NavitiaProfiler::class);
           $results = $profiler->search($query);
           return $this->mapResults($results);
       }
   }
   

Tips for Seamless Integration

• Caching Responses Cache profiled routes to reduce API calls:

  $cacheKey = "navitia_route_{$origin}_{$destination}_{$datetime}";
  return Cache::remember($cacheKey, now()->addHours(1), function() use ($profiler, $origin, $destination, $datetime) {
      return $profiler->profileRoute($origin, $destination, $datetime);
  });
  

• Event Listeners Trigger actions post-profiling (e.g., log to a database):

  public function handle(NavitiaProfiled $event)
  {
      \App\Models\RouteProfile::create([
          'origin' => $event->origin,
          'destination' => $event->destination,
          'data' => $event->data,
      ]);
  }
  

  Register in EventServiceProvider:

  protected $listen = [
      \CanalTP\NavitiaProfilerBundle\Events\NavitiaProfiled::class => [
          \App\Listeners\LogNavitiaProfile::class,
      ],
  ];
  

• Middleware for API Rate Limiting Use Laravel’s throttle middleware to limit Navitia API calls:

  Route::middleware(['throttle:10,1'])->group(function () {
      Route::post('/profile', [YourController::class, 'profileRoute']);
  });
  

Gotchas and Tips

Common Pitfalls

1. API Rate Limits

   • Navitia’s API has strict rate limits. Monitor usage with:

     $profiler->getRateLimitStatus(); // Hypothetical method; check docs
     

   • Fix: Implement exponential backoff in retries or use a queue system.

2. Data Mismatches

   • Ensure origin/destination coordinates are in the correct format (e.g., 48.8566,2.3522).
   • Fix: Validate inputs:

     $coordinates = explode(',', $request->input('origin'));
     if (count($coordinates) !== 2) {
         throw new \InvalidArgumentException("Invalid coordinates format.");
     }
     

3. Time Zone Handling

   • Navitia expects UTC timestamps. Convert local time:

     $datetime = now()->timezone('UTC')->format('Y-m-d\TH:i:s');
     

4. Deprecated Methods

   • The bundle may evolve. Check the changelog for breaking changes.

Debugging Tips

• Enable Verbose Logging Configure Monolog in config/logging.php to log Navitia API responses:

  'channels' => [
      'navitia' => [
          'driver' => 'single',
          'path' => storage_path('logs/navitia.log'),
          'level' => 'debug',
      ],
  ],
  

  Then log responses:

  \Log::channel('navitia')->debug('Profiled data:', $data);
  

• Test with Mock Data Use Laravel’s HTTP client to mock Navitia responses during testing:

  $this->mockNavitiaApi()
       ->shouldReceive('get')
       ->with('v1/coverage/fr-idf/journeys')
       ->andReturn(response()->json($mockData));
  

Extension Points

1. Custom Profiler Logic Extend the base profiler class:

   class CustomNavitiaProfiler extends \CanalTP\NavitiaProfilerBundle\Services\NavitiaProfiler
   {
       public function profileWithCustomLogic($origin, $destination, $datetime)
       {
           $data = parent::profileRoute($origin, $destination, $datetime);
           // Add custom processing
           return $this->enrichData($data);
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(
       \CanalTP\NavitiaProfilerBundle\Services\NavitiaProfiler::class,
       \App\Services\CustomNavitiaProfiler::class
   );
   

2. Add Custom Metrics Extend the profiler to include domain-specific metrics (e.g., "walking distance"):

   $profiler->addMetric('walking_distance', function ($data) {
       return $data['sections'][0]['duration'] * 0.005; // km/h estimate
   });
   

3. Webhook Integration Listen for Navitia API updates via webhooks (if supported) and sync data in real-time:

   Route::post('/navitia-webhook', function (Request $request) {
       $profiler = app(NavitiaProfiler::class);
       $profiler->handleWebhook($request->all());
   });