Converter Laravel Package

Getting Started

• Install via Composer: composer require cartalyst/converter
• First use: Create a Converter instance and chain conversions:

  $converter = new \Cartalyst\Converter\Converter();
  $result = $converter->convert(100, 'cm', 'm'); // 1.0
  

• Common initial use case: Normalizing user input (e.g., product dimensions entered in inches → store in cm or m):

  $lengthInches = 24.5;
  $lengthCm = $converter->convert($lengthInches, 'in', 'cm');
  

• Start here in docs: Check src/Converter.php source or the examples/ folder for quick start snippets; full Laravel integration is covered in the README under Laravel Integration.

Implementation Patterns

• Centralize unit definitions: Use custom unit sets for domain-specific needs (e.g., e-commerce products):

  $units = [
      'product_weight' => [
          'g' => 1,
          'oz' => 28.3495,
          'lb' => 453.592,
      ],
  ];
  $converter = new Converter($units);
  $weight = $converter->convert(16, 'oz', 'g', 'product_weight');
  

• Fluent chain in service classes:

  // In a service like OrderProcessor
  $displayWeight = $this->converter
      ->setPrecision(2)
      ->convert($orderItem->weight, 'g', 'lb')
      ->format('%.2f lbs');
  

• Laravel-specific pattern: Bind Converter as a singleton in AppServiceProvider:

  $this->app->singleton(\Cartalyst\Converter\Converter::class, function ($app) {
      return new \Cartalyst\Converter\Converter([
          'custom' => require base_path('config/custom-units.php'),
      ]);
  });
  

• Normalize DB input/output: In Eloquent accessors/mutators:

  public function setWeightAttribute($value)
  {
      $this->attributes['weight_grams'] = $this->converter
          ->convert($value, 'kg', 'g');
  }
  
  public function getWeightAttribute($value)
  {
      return $this->converter->convert($value, 'g', 'kg');
  }
  

Gotchas and Tips

• Case sensitivity matters: Unit names are case-sensitive ('kg' ≠ 'Kg'); define units consistently and validate inputs.
• Missing units cause exception: Always validate unit keys before conversion (e.g., use hasUnitType() and hasUnit()), especially when accepting arbitrary strings from user input:

  if ($converter->hasUnitType('product_weight') && $converter->hasUnit('product_weight', $inputUnit)) {
      // proceed
  }
  

• Precision ≠ formatting: Set precision before formatting; setPrecision() affects internal math, while format() uses sprintf-style masks:

  $result = $converter->setPrecision(3)
      ->convert(10.001, 'm', 'km')
      ->format('%.3f km'); // "0.010 km"
  

• Custom unit types override built-ins: Defining 'length' in your custom set replaces default length units. To extend, merge $converter::getDefaultUnits() first.
• Extension point: Implement Cartalyst\Converter\ConverterInterface for custom logic (e.g., dynamic exchange rates), or use Converter::extend() for runtime monkey-patching (use sparingly).