README

A comprehensive, production-ready Symfony bundle for converting distances between 49+ units across 6 major unit systems with full internationalization support.

Repository: https://gitlab.com/rodrysimportante/distance-converter-bundle.git

✨ Features

49 Distance Units across 6 categories (Metric, Imperial, Nautical, Sports, Astronomical, Historical)
Smart API - Default meter as source unit for cleaner, more intuitive code
100% Backward Compatible - Old and new APIs work seamlessly together
4 Languages - English, Spanish, French, German with automatic locale detection
Twig Integration - 6 ready-to-use filters for templates with unit symbols support
Zero Dependencies - Only requires Symfony components
Comprehensive Tests - 39 unit tests with full coverage
Production Ready - PSR-12 compliant, type-hinted, fully documented

📦 Supported Units

Category	Units	Examples
Metric (15)	femtometer, picometer, angstrom, nanometer, micrometer, millimeter, centimeter, decimeter, meter, decameter, hectometer, kilometer, megameter, gigameter, terameter	1 km = 1,000 m
Imperial (8)	barleycorn, link, hand, inch, foot, yard, pole, mile	1 mile ≈ 1.609 km
Nautical (2)	fathom, nautical_mile	1 NM = 1,852 m
Sports (2)	olympic_pool, marathon	Marathon = 42.195 km
Astronomical (5)	astronomical_unit, light_year, parsec, kiloparsec, megaparsec	1 AU = 149,597,870,700 m
Historical (12)	scottish_mile, irish_mile, swedish_mile, norwegian_mile, verst, greek_stadion, french_foot, french_toise, chain, rod, furlong, league	Regional & historical units

🚀 Quick Start

Installation

# 1. Copy bundle to your project
cp -r DistanceConverterBundle /path/to/your/project/bundles/

# 2. Register in config/bundles.php
DistanceConverterBundle\DistanceConverterBundle::class => ['all' => true],

No configuration needed - it works out of the box!

PHP Usage

use DistanceConverterBundle\Converter\DistanceConverter;

class MyController {
    public function convert(DistanceConverter $converter) {
        // NEW API: When 2 params given, 2nd is target unit, source defaults to 'meter'
        $km = $converter->convert(1000, 'kilometer');                    // 1000m → 1km
        $miles = $converter->convert(1609.344, 'mile', null, 2);         // 1609.344m → 1.0 mile

        // FULL API: Explicit source and target units
        $km = $converter->convert(1000, 'meter', 'kilometer');           // 1000m → 1km
        $miles = $converter->convert(5, 'kilometer', 'mile', 2);         // 5km → 3.11 miles

        // Helper methods
        $meters = $converter->toMeters(5, 'kilometer');                  // 5km → 5000m
        $miles = $converter->fromMeters(1609.344, 'mile', 2);            // 1609.344m → 1.0 mile
    }
}

Twig Templates

{# ===== CONVERT_DISTANCE FILTER ===== #}

{# Basic conversion (defaults to meters as source) #}
{{ 1000 | convert_distance('kilometer') }}                           {# Returns: 1 #}

{# With custom precision #}
{{ 1609.344 | convert_distance('mile', null, 2) }}                  {# Returns: 1.0 #}

{# With unit symbol #}
{{ 1000 | convert_distance('kilometer', null, 2, true) }}           {# Returns: "1 km" #}

{# Explicit source and target units #}
{{ 5 | convert_distance('kilometer', 'mile', 2) }}                  {# Returns: 3.11 #}

{# With symbol (explicit source and target) #}
{{ 5 | convert_distance('kilometer', 'mile', 2, true) }}            {# Returns: "3.11 mi" #}

{# ===== TO_METERS FILTER ===== #}

{# Convert any unit to meters #}
{{ 5 | to_meters('kilometer') }}                                     {# Returns: 5000 #}

{# With custom precision #}
{{ 1 | to_meters('mile', 2) }}                                       {# Returns: 1609.34 #}

{# With unit symbol #}
{{ 1 | to_meters('kilometer', 6, true) }}                           {# Returns: "1000 m" #}

{# ===== FROM_METERS FILTER ===== #}

{# Convert from meters to any unit #}
{{ 1609.344 | from_meters('mile', 2) }}                             {# Returns: 1.0 #}

{# With unit symbol #}
{{ 1000 | from_meters('kilometer', 2, true) }}                      {# Returns: "1 km" #}

{# ===== UNIT INFORMATION FILTERS ===== #}

{# Get localized unit name (auto-detects locale) #}
{{ 'kilometer' | distance_unit_name }}                              {# "Kilometer" (en) #}
{{ 'kilometer' | distance_unit_name('es') }}                        {# "Kilómetro" (es) #}
{{ 'kilometer' | distance_unit_name('fr') }}                        {# "Kilomètre" (fr) #}
{{ 'kilometer' | distance_unit_name('de') }}                        {# "Kilometer" (de) #}

{# Get unit category #}
{{ 'kilometer' | distance_unit_category }}                          {# Returns: "metric" #}
{{ 'mile' | distance_unit_category }}                               {# Returns: "imperial" #}
{{ 'light_year' | distance_unit_category }}                         {# Returns: "astronomical" #}

{# Get unit symbol #}
{{ 'kilometer' | distance_unit_symbol }}                            {# Returns: "km" #}
{{ 'mile' | distance_unit_symbol }}                                 {# Returns: "mi" #}
{{ 'light_year' | distance_unit_symbol }}                           {# Returns: "ly" #}

📚 Documentation

Document	Purpose
README.md	Overview & quick start (this file)
CHANGELOG.md	Version history & roadmap
docs/INSTALLATION.md	Detailed installation guide
docs/USAGE.md	Comprehensive usage examples
docs/FEATURES.md	In-depth feature documentation
docs/ARCHITECTURE.md	Project structure & organization
docs/TECHNICAL_DETAILS.md	Technical implementation details
docs/CONTRIBUTING.md	Development & contribution guidelines

💡 Common Use Cases

1. Display Distance in Multiple Units with Symbols

PHP:

$distance_m = 5000; // from database

$km = $converter->convert($distance_m, 'kilometer');           // 5
$miles = $converter->convert($distance_m, 'mile', null, 2);   // 3.11
$feet = $converter->convert($distance_m, 'foot', null, 0);    // 16404

Twig:

{% set distance_meters = 5000 %}

<ul>
  <li>{{ distance_meters | convert_distance('kilometer', null, 2, true) }}</li>     {# 5 km #}
  <li>{{ distance_meters | convert_distance('mile', null, 2, true) }}</li>          {# 3.11 mi #}
  <li>{{ distance_meters | convert_distance('foot', null, 0, true) }}</li>          {# 16404 ft #}
  <li>{{ distance_meters | from_meters('kilometer', 2, true) }}</li>                {# 5 km #}
</ul>

2. Convert User Input to Database Storage

// User enters in their preferred unit
$user_distance = 5;
$user_unit = 'mile';

// Store in database (always in meters)
$meters = $converter->convert($user_distance, 'meter', $user_unit);
$entity->distance = $meters;

3. Display Unit Information in Templates

{% set distance_meters = 8848 %} {# Mount Everest #}

<p>Mount Everest Height:</p>
<ul>
  <li>{{ distance_meters | convert_distance('kilometer', null, 0, true) }}</li>
  <li>{{ distance_meters | convert_distance('foot', null, 0, true) }}</li>
  <li>{{ distance_meters | from_meters('mile', 2, true) }}</li>
</ul>

<p>Categories:</p>
<ul>
  <li>{{ 'kilometer' | distance_unit_name }}: {{ 'kilometer' | distance_unit_symbol }}</li>
  <li>{{ 'foot' | distance_unit_name('es') }}: {{ 'foot' | distance_unit_symbol }}</li>
  <li>{{ 'light_year' | distance_unit_name('fr') }}: {{ 'light_year' | distance_unit_symbol }}</li>
</ul>

4. Astronomical Distance Display

{% set distance_km = 50000000 %} {# 50 million km #}

<p>Distance in light years:</p>
<ul>
  <li>Numeric only: {{ distance_km | convert_distance('kilometer', 'light_year', 15) }}</li>
  <li>With symbol: {{ distance_km | convert_distance('kilometer', 'light_year', 15, true) }}</li>
  <li>Scientific: {{ distance_km | convert_distance('kilometer', 'light_year', 8, true) }}</li>
</ul>

5. Unit Comparison Table

<table>
  <thead>
    <tr>
      <th>Unit</th>
      <th>Symbol</th>
      <th>Category</th>
      <th>Localized Name (ES)</th>
    </tr>
  </thead>
  <tbody>
    {% for unit in ['kilometer', 'mile', 'meter', 'foot', 'light_year'] %}
    <tr>
      <td>{{ unit }}</td>
      <td>{{ unit | distance_unit_symbol }}</td>
      <td>{{ unit | distance_unit_category }}</td>
      <td>{{ unit | distance_unit_name('es') }}</td>
    </tr>
    {% endfor %}
  </tbody>
</table>

🔧 Services

DistanceConverter

Main service for distance conversions:

// Conversion methods
$converter->convert($value, $fromUnit, $toUnit = null, $precision = 6)
$converter->toMeters($value, $fromUnit, $precision = 6)
$converter->fromMeters($value, $toUnit, $precision = 6)

// Unit information
$converter->getAvailableUnits()          // array of unit names
$converter->getUnitsByCategory()         // units grouped by category
$converter->getUnitSymbol($unit)         // get symbol for unit (e.g., 'km', 'mi')
$converter->getUnitSymbols()             // all units with their symbols

Examples:

use DistanceConverterBundle\Converter\DistanceConverter;

class MyController {
    public function convert(DistanceConverter $converter) {
        // Conversions
        $km = $converter->convert(1000, 'kilometer');              // 1
        $miles = $converter->convert(5, 'kilometer', 'mile', 2);   // 3.11

        // Convert to/from meters
        $meters = $converter->toMeters(5, 'kilometer');            // 5000
        $km = $converter->fromMeters(1000, 'kilometer');           // 1

        // Get unit information
        $symbol = $converter->getUnitSymbol('kilometer');          // 'km'
        $units = $converter->getAvailableUnits();                  // [...]
        $byCategory = $converter->getUnitsByCategory();            // [...]
        $allSymbols = $converter->getUnitSymbols();                // [...]
    }
}

UnitsRegistry

Access unit definitions directly:

// Get units and factors
$registry->getUnits()                    // all units with conversion factors to meters
$registry->hasUnit($unit)                // check if unit exists
$registry->getConversionFactor($unit)    // get factor to convert to meters
$registry->getUnitsByCategory()          // units grouped by category

// Get symbols
$registry->getUnitSymbol($unit)          // get symbol for a unit
$registry->getSymbols()                  // all units with their symbols

Examples:

$registry->hasUnit('kilometer');                   // true
$registry->getConversionFactor('kilometer');       // 1000
$registry->getUnitSymbol('mile');                  // 'mi'
$registry->getUnitsByCategory()['metric'];         // ['meter', 'kilometer', ...]

🎨 Twig Filters - Complete Reference

convert_distance

Converts a distance value from one unit to another.

Signature:

convert_distance(value, fromUnit, toUnit = null, precision = 6, includeSymbol = false): float|string

Parameters:

value (float) - The distance value to convert
fromUnit (string) - Source unit name (defaults to 'meter' if toUnit is null)
toUnit (string|null) - Target unit name. If null, fromUnit is treated as toUnit and source defaults to 'meter'
precision (int) - Number of decimal places (default: 6)
includeSymbol (bool) - Include unit symbol in output (default: false)

Examples:

{{ 1000 | convert_distance('kilometer') }}                    {# 1 #}
{{ 1000 | convert_distance('kilometer', null, 2) }}          {# 1 #}
{{ 1000 | convert_distance('kilometer', null, 2, true) }}    {# "1 km" #}
{{ 5 | convert_distance('kilometer', 'mile', 2) }}           {# 3.11 #}
{{ 5 | convert_distance('kilometer', 'mile', 2, true) }}     {# "3.11 mi" #}

to_meters

Converts a distance value from any unit to meters.

Signature:

to_meters(value, fromUnit, precision = 6, includeSymbol = false): float|string

Parameters:

value (float) - The distance value to convert
fromUnit (string) - Source unit name
precision (int) - Number of decimal places (default: 6)
includeSymbol (bool) - Include unit symbol in output (default: false)

Examples:

{{ 5 | to_meters('kilometer') }}              {# 5000 #}
{{ 1 | to_meters('mile', 2) }}               {# 1609.34 #}
{{ 1 | to_meters('kilometer', 6, true) }}    {# "1000 m" #}

from_meters

Converts a distance value from meters to any unit.

Signature:

from_meters(value, toUnit, precision = 6, includeSymbol = false): float|string

Parameters:

value (float) - The distance value in meters
toUnit (string) - Target unit name
precision (int) - Number of decimal places (default: 6)
includeSymbol (bool) - Include unit symbol in output (default: false)

Examples:

{{ 1609.344 | from_meters('mile', 2) }}             {# 1.0 #}
{{ 1000 | from_meters('kilometer', 2) }}            {# 1 #}
{{ 1000 | from_meters('kilometer', 2, true) }}      {# "1 km" #}

distance_unit_name

Gets the localized name of a unit based on the current or specified locale.

Signature:

distance_unit_name(unit, locale = null): string

Parameters:

unit (string) - Unit name
locale (string|null) - Locale code (en, es, fr, de). If null, uses app locale

Examples:

{{ 'kilometer' | distance_unit_name }}           {# "Kilometer" (en) #}
{{ 'kilometer' | distance_unit_name('es') }}     {# "Kilómetro" #}
{{ 'kilometer' | distance_unit_name('fr') }}     {# "Kilomètre" #}
{{ 'mile' | distance_unit_name('de') }}          {# "Meile" #}

distance_unit_category

Gets the category of a unit (metric, imperial, nautical, sports, astronomical, or historical).

Signature:

distance_unit_category(unit): string

Parameters:

unit (string) - Unit name

Examples:

{{ 'kilometer' | distance_unit_category }}       {# "metric" #}
{{ 'mile' | distance_unit_category }}            {# "imperial" #}
{{ 'fathom' | distance_unit_category }}          {# "nautical" #}
{{ 'marathon' | distance_unit_category }}        {# "sports" #}
{{ 'light_year' | distance_unit_category }}      {# "astronomical" #}
{{ 'verst' | distance_unit_category }}           {# "historical" #}

distance_unit_symbol

Gets the symbol or abbreviation for a unit (km, mi, ft, m, ly, etc.).

Signature:

distance_unit_symbol(unit): string

Parameters:

unit (string) - Unit name

Examples:

{{ 'kilometer' | distance_unit_symbol }}         {# "km" #}
{{ 'mile' | distance_unit_symbol }}              {# "mi" #}
{{ 'foot' | distance_unit_symbol }}              {# "ft" #}
{{ 'meter' | distance_unit_symbol }}             {# "m" #}
{{ 'light_year' | distance_unit_symbol }}        {# "ly" #}
{{ 'nautical_mile' | distance_unit_symbol }}     {# "nmi" #}

🌍 Internationalization

Automatic locale detection in Twig filters:

{{ 'kilometer' | distance_unit_name }}        {# uses app locale #}
{{ 'kilometer' | distance_unit_name('es') }}  {# Spanish: Kilómetro #}
{{ 'kilometer' | distance_unit_name('fr') }}  {# French: Kilomètre #}
{{ 'kilometer' | distance_unit_name('de') }}  {# German: Kilometer #}

Add more languages by creating translation files:

docs/CONTRIBUTING.md  # See "Adding New Languages" section

✅ Quality Assurance

✅ 30+ Unit Tests - All passing
✅ 100% Type Hints - Strict type safety
✅ PSR-12 Compliant - Code standard compliance
✅ Zero Dependencies - Only Symfony components
✅ Backward Compatible - Old API still works
✅ Production Ready - Battle-tested structure

📋 Requirements

PHP: 8.1 or higher
Symfony: 5.4, 6.0, or 7.0
Optional: Symfony Translation & Twig components (for full features)

🔄 Backward Compatibility

The bundle maintains 100% backward compatibility:

// These are equivalent
$result1 = $converter->convert(1000, 'kilometer');           // NEW
$result2 = $converter->convert(1000, 'meter', 'kilometer');  // OLD

// Both APIs can be mixed in the same application

🚀 Performance

⚡ All conversions use simple math (O(1) complexity)
💾 Minimal memory footprint
📦 No database queries
🎯 Can be cached effectively

📄 License

MIT License - Free for commercial and personal use. See LICENSE for details.

🤝 Contributing

Contributions are welcome! See docs/CONTRIBUTING.md for guidelines.

📞 Support

Documentation: See docs/ folder
Issues: Check existing issues or create a new one
Examples: See docs/USAGE.md

🎯 Roadmap

v1.1

Additional historical units
Configurable precision via configuration
More language translations

v2.0

Custom units via configuration
Batch conversion operations
API endpoint package
GraphQL support

Status: ✅ Production Ready | Version: 1.0.0 | License: MIT

Start converting distances today! 🌍

rodrysimportante / distance-converter-bundle

Maintainers

Package info

Statistics

Security

README

✨ Features

📦 Supported Units

🚀 Quick Start

Installation

PHP Usage

Twig Templates

📚 Documentation

💡 Common Use Cases

1. Display Distance in Multiple Units with Symbols

2. Convert User Input to Database Storage

3. Display Unit Information in Templates

4. Astronomical Distance Display

5. Unit Comparison Table

🔧 Services

DistanceConverter

UnitsRegistry

🎨 Twig Filters - Complete Reference

convert_distance

to_meters

from_meters

distance_unit_name

distance_unit_category

distance_unit_symbol

🌍 Internationalization

✅ Quality Assurance

📋 Requirements

🔄 Backward Compatibility

🚀 Performance

📄 License

🤝 Contributing

📞 Support

🎯 Roadmap

v1.1

v2.0