SI units and prefixes

Quantities that use the HasSIUnits trait can convert between any metric-prefixed form of their base unit without registering each prefixed unit individually. For example, Length registers m as its native unit, and the trait resolves km, cm, mm, μm, and so on at conversion time.

Declaring the base unit

A quantity opts in by using the trait and overriding getSIBaseUnit():

class Mass extends PhysicalQuantity
{
    use HasSIUnits;

    protected function getSIBaseUnit(): string
    {
        return 'g'; // grams, not the SI kilogram
    }

    // ...
}

If getSIBaseUnit() is not overridden, it returns m by default.

How resolution works

When a unit name is not found among the registered units, the trait attempts to split it into a prefix and the base unit. If the prefix is a known metric prefix and the remainder matches the base unit, the value is scaled by the corresponding power of ten.

Construction and toUnit() both use this fallback. The lookup order is: registered units first, then SI prefix resolution.

Supported prefixes

The full range from quecto (10⁻³⁰) to quetta (10³⁰) is supported.

Prefix	Symbol	Factor	Prefix	Symbol	Factor
quetta	Q	10³⁰	deci	d	10⁻¹
ronna	R	10²⁷	centi	c	10⁻²
yotta	Y	10²⁴	milli	m	10⁻³
zetta	Z	10²¹	micro	μ	10⁻⁶
exa	E	10¹⁸	nano	n	10⁻⁹
peta	P	10¹⁵	pico	p	10⁻¹²
tera	T	10¹²	femto	f	10⁻¹⁵
giga	G	10⁹	atto	a	10⁻¹⁸
mega	M	10⁶	zepto	z	10⁻²¹
kilo	k	10³	yocto	y	10⁻²⁴
hecto	h	10²	ronto	r	10⁻²⁷
deca	da	10¹	quecto	q	10⁻³⁰

The empty prefix (the base unit itself) maps to 10⁰.

Power notation

The trait detects whether a base unit carries a power and applies the conversion accordingly. For area and volume, the linear scale factor is raised to the power of the unit:

• cm² to m² uses a factor of (10⁻²)² = 10⁻⁴.
• mm³ to m³ uses a factor of (10⁻³)³ = 10⁻⁹.

Both the superscript form (m²) and the numeric form (m2) are accepted.

A conversion between two prefixed units of different powers — for instance cm² to m³ — is rejected with an InvalidArgumentException.

Composite base units

Composite units such as m/s (Velocity) or kg/m³ (Density) can also be used as the base unit symbol. Prefix resolution still applies to the whole symbol as declared.