README

Units For Laravel

Laravel integration for knppy/units: Eloquent casts, validation, localized parsing and formatting, and migration helpers.

Installation

You can install the package via Composer:

composer require knppy/units-laravel

You may publish all of the package's resources at once:

php artisan vendor:publish --tag="units-laravel"

Or, you may publish each resource individually:

Publishing the Configuration File

php artisan vendor:publish --tag="units-laravel-config"

Publishing the Translations

php artisan vendor:publish --tag="units-laravel-lang"

Usage

Migrations

unit() adds {name}_amount (a decimal(38, 0)) and {name}_unit (a string) columns. Pass nullable: true for optional units; dropUnit() drops both.

Schema::create('products', function (Blueprint $table) {
    $table->id();
    $table->unit('weight');
    $table->unit('volume', nullable: true);
});

Eloquent

Cast the attribute with UnitCast. It reads and writes both columns and returns a Knppy\Units\Unit:

use Knppy\LaravelUnits\Casts\UnitCast;

class Product extends Model
{
    protected function casts(): array
    {
        return [
            'weight' => UnitCast::class,
            'volume' => UnitCast::class.':ml', // "250" is stored as 250 ml
        ];
    }
}

$product->weight = new Unit(100, new UnitOfMeasurement('kg'));
$product->weight = '100 kg';                    // strings are parsed
$product->weight->getAmount();                  // "100"
$product->weight->convertTo(new UnitOfMeasurement('g')); // 100000 g

Because the value lives in two columns, add the attribute to $appends and hide the columns to include it in toArray() and toJson() as {"amount": "100", "unit": "kg"}:

protected $appends = ['weight'];
protected $hidden = ['weight_amount', 'weight_unit'];

Validation

use Knppy\LaravelUnits\Rules\UnitRule;
use Knppy\Units\Quantity;

$request->validate([
    'weight' => ['required', UnitRule::make()->quantity(Quantity::Mass)],
    'volume' => [UnitRule::make()->in('ml', 'l')->fallback('ml')],
]);

Input is read with the localized names of the application locale first, then as symbols. Use ->locale('nl') to override it.

Parsing, formatting and converting

use Knppy\LaravelUnits\Facades\LaravelUnits;

LaravelUnits::parse('2 kilogram');                  // Unit(2, kg)
LaravelUnits::format(LaravelUnits::make(1500, 'm')); // "1,500 metres", or "1.500 meters" with the nl locale
LaravelUnits::convert(LaravelUnits::make(5, 'km'), 'm'); // 5000 m

UnitParser, UnitFormatter, UnitConverter and UnitNames are bound in the container and follow the configuration (locale, names, converter, grouping, columns).

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Units For Laravel! Please review our contributing guide to get started.

knppy / units-laravel

Package info

Security

Fund package maintenance!

Statistics