Time Distance Bundle Laravel Package

Product Decisions This Supports

• Feature Development for Fitness/Activity Apps:

  • Enable dynamic, user-friendly display of distance (e.g., "5 miles" vs. "8,073 meters") and time-based metrics (e.g., "01:23:45" for stopwatch formats) without custom backend logic.
  • Support pace/speed calculations (e.g., "5:30/km pace") for running/cycling apps, reducing frontend complexity.
  • Form validation/handling for distance/time inputs (e.g., stopwatch timers, race distances) via built-in Symfony form types.

• Roadmap Prioritization:

  • Buy vs. Build: Justify adopting this package over custom Twig extensions or JavaScript solutions if the team lacks PHP/Twig expertise or time to maintain bespoke logic.
  • Localization/Unit Flexibility: Leverage the configurable normalized_distance_unit to support global audiences (e.g., switch between metric/imperial units via config).
  • Performance: Offload distance/time calculations to the server layer, reducing client-side processing for complex apps.

• Use Cases:

  • Fitness Trackers: Display real-time pace/speed for users (e.g., Strava-like interfaces).
  • Logistics/Transport Apps: Convert distances for route planning (e.g., "Delivery in 2.3 miles").
  • Sports Leagues: Format stopwatch times for event timers (e.g., swimming meets).
  • E-commerce: Show shipping estimates (e.g., "Delivered in 3–5 business days" → {{ delivery_seconds|seconds_to_stopwatch }}).

When to Consider This Package

• Adopt If:

  • Your app heavily relies on distance/time calculations (e.g., fitness, logistics, sports) and needs consistent formatting across Twig templates.
  • You’re using Symfony/Laravel and want to avoid reinventing Twig filters/form types for common use cases.
  • Your team lacks bandwidth to maintain custom distance/time utilities or prefers batteries-included solutions.
  • You need unit conversion (e.g., meters ↔ miles) with minimal code changes.

• Look Elsewhere If:

  • You require high-performance client-side calculations (e.g., real-time GPS tracking; this is server-side).
  • Your stack doesn’t use Twig/Symfony forms (e.g., React/Vue frontends with custom APIs).
  • You need advanced features like geodesic distance calculations (this uses planar approximations).
  • The package’s maturity/star count concerns you (low adoption may imply untested edge cases).
  • You’re building a non-web app (e.g., CLI tools, mobile apps with native UI components).

How to Pitch It (Stakeholders)

For Executives: "This package lets us deliver polished, accurate distance/time displays (e.g., ‘5K in 25:30’ or ‘3.2 miles’) with zero frontend dev effort. For example, a fitness app could show real-time pace updates without custom JavaScript, while logistics tools could auto-convert shipping distances. It’s a low-risk way to add professional-grade metrics—like a ‘Twig plugin’ for common calculations—while keeping our stack lean. The config-driven unit system also future-proofs us for global markets."

For Engineers: *"This gives us:

• 4 Twig filters (format_distance, seconds_to_stopwatch, average_pace, average_speed) to replace ad-hoc JS/PHP logic.
• 2 form types for distance/stopwatch inputs, cutting validation boilerplate.
• Configurable units (meters/miles) via dtl_time_distance bundle settings. Tradeoff: Minimal stars/maturity, but the code is straightforward (100 LOC). We’d own any edge cases, but it’s a drop-in for 80% of use cases. Alternative: Build custom Twig extensions (3–5x effort)."*