WAK-1723: Update readme

readme.md

@@ -1,60 +1,166 @@
-# Units in php
+# Unit Conversion Library for PHP
 
-## to do:
+## Introduction
 
-- [ ] Add more units
-- [ ] Add conversion ratios
+This package provides a powerful and flexible way to handle unit conversion in PHP. It supports parsing units from strings, performing conversions, and working with both simple and compound units.
 
-```php
-<?php
+## Supported Conversions
+
+Our library supports a wide range of unit conversions, covering both fundamental and derived physical quantities.
+
+- 📏 **Length (Distance)**
+- 📐 **Area**
+- ⚖️ **Mass**
+- ⏳ **Time**
+- 🌡 **Temperature**
+- ⚡ **Energy**
+- 🔥 **Power**
+- 📊 **Pressure**
+- 📡 **Frequency**
+- 🏋️ **Force**
+- 🔆 **Luminous Intensity**
+- 🧪 **Amount of Substance**
+- 🥤 **Volume**
+## Why Use This Library?
+
+- **Simple string-based unit parsing**
+- **Supports SI prefixes and derived units**
+- **Handles compound unit conversions** (e.g., speed, density, force)
+- **Extendable** - Easily add new units and dimensions
+- **Integration with Laravel**
+
+## Installation
+
+Install via Composer:
+
+```sh
+  composer require vesper/unit-conversion
+```
 
-Use Vesper\UnitConversion\Converter;
-Use Vesper\UnitConversion\Dimension;
-Use Vesper\UnitConversion\Parser;
-Use Vesper\UnitConversion\Registry;
-Use Vesper\UnitConversion\RegistryBuilder;
+## Usage
+
+### Parsing a Unit
+
+```php
+use Vesper\UnitConversion\Parser;
+use Vesper\UnitConversion\Registry;
 
 $registry = new Registry();
+$parser = new Parser($registry);
+
+$unit = $parser->parse('m/s'); // Returns an instance of Unit
+```
+
+### Regular Conversion
+
+```php
+use Vesper\UnitConversion\Converter;
+
+$converter = new Converter();
+$cm = $parser->parse('cm');
+$m = $parser->parse('m');
+
+$result = $converter->convert($cm, $m, 100); // Converts 100cm to 1m
+```
+
+### Compound Unit Conversion
+
+```php
+$ms = $parser->parse('m/s');
+$kmh = $parser->parse('km/h');
+
+$result = $converter->convert($ms, $kmh, 10); // Converts 10m/s to 36km/h
+```
+
+### Creating and Adding Custom Units
+
+The `RegistryBuilder` class provides a set of predefined units and allows for easy extension.
+
+#### Using `RegistryBuilder::build()`
 
-// Setup basic units
+The `build()` method initializes a `Registry` instance with common units like length, mass, time, temperature, force, etc.
+
+```php
+use Vesper\UnitConversion\Registry;
+use Vesper\UnitConversion\RegistryBuilder;
+
+$registry = new Registry();
 RegistryBuilder::build($registry);
+```
+
+This method ensures that a wide range of units are available for use immediately.
+
+#### Registering a Custom Unit
+
+The `register()` method is used to add new units to the registry, and `alias()` allows you to specify alternative names.
+
+```php
+use Vesper\UnitConversion\Registry;
+use Vesper\UnitConversion\Unit;
+use Vesper\UnitConversion\Dimension;
+use Vesper\UnitConversion\UnitPart;
+
+$registry = new Registry();
+
+$registry->register(
+    'furlong',
+    new Unit(new UnitPart(201.168, Dimension::LENGTH, 1) // 1 furlong = 201.168 meter
+);
+$registry->alias('furlong', ['fur']);
+```
+
+#### Using `registerSiUnit()`
+
+The `registerSiUnit()` method allows you to define SI units along with their prefixed versions (e.g., kilogram, milligram, etc.).
+
+```php
+use Vesper\UnitConversion\RegistryBuilder;
+use Vesper\UnitConversion\Unit;
+use Vesper\UnitConversion\UnitPart;
+use Vesper\UnitConversion\Dimension;
 
-// Register a si unit including all the si prefixes.
-// When specifying symbols, it will also add prefixed symbols.
 RegistryBuilder::registerSiUnit(
     $registry,
-    'meter^2', // Full name of the unit
-    symbols: ['m^2'], // Symbols for the unit
-    ratio: 1 // The relation to the base unit
-    dimension: Dimension::LENGTH
-    power: 2
+    'gram', // Base unit
+    ['g'], // Aliases
+    new Unit(new UnitPart(0.001, Dimension::MASS, 1)) // 1 gram = 0.001 kilogram
 );
+```
 
-$parser = new Parser($registry);
-$converter = new Converter();
+This automatically registers `gram` and generates prefixed versions like `kilogram (kg)`, `milligram (mg)`, etc.
 
-// Simple units
-$cm = $parser->parse('cm');
-$m = $parser->parse('m');
+### Using in Laravel
 
-$converter->convert($cm, $m, 100);
+This package provides a service provider, `ConversionServiceProvider`, which is auto-discovered by Laravel. This means you don’t need to manually register it.
+`ConversionServiceProvider` include `Converter`, `Parser` and `Registry` classes.
 
-// Compound units
-$ms = $parser->parse('m/s');
-$kmh = $parser->parse('km/h'),
+Additionally, a facade `Converter` is provided for easy access.
+
+#### Example Usage
+
+```php
+use Vesper\UnitConversion\Converter;
+use Vesper\UnitConversion\Parser;
+
+class UnitController
+{
+    public function __construct(
+        protected Converter $converter,
+        protected Parser $parser
+    ) {}
+
+    public function convert()
+    {
+        $from = $this->parser->parse('kg');
+        $to = $this->parser->parse('g');
+        $value = 5;
 
-$converter->convert($ms, $kmh);
+        return $this->converter->convert($from, $to, $value); // Converts 5kg to 5000g
+    }
+}
+```
 
-// Convert density
-$kg = $parser->parse('kg');
-$m3 = $parser->parse('m^3');
-$kgm3 = $parser->parse('kg/m^3');
+## License
 
-[$amount, $volumeUnit] = $converter->multiply(1, $m3, 19320, $kgm3)
+This package is open-source and available under the MIT License. See the [LICENSE](./LICENSE) file for more details.
 
-$converter->convert(
-    $amount,
-    $volumeUnit,
-    $parser->parse('cm^3'),
-)
-```

src/RegistryBuilder.php

@@ -144,7 +144,7 @@ protected static function initLength(Registry $registry): void
         $registry->alias('inch', ['in']);
 
         $registry->register('foot', new Unit(new UnitPart(0.3048, Dimension::LENGTH, 1)));
-        $registry->alias('foot', ['fe']);
+        $registry->alias('foot', ['ft']);
 
         $registry->register('yard', new Unit(new UnitPart(0.9144, Dimension::LENGTH, 1)));
         $registry->alias('yard', ['yd']);