README

master:

介绍

这是一个用于表示和转换物理单位的 PHP 库。该库的用途在于将物理量封装起来，这样您就不必跟踪它们所表示的单位。例如

use PhpUnitsOfMeasure\PhysicalQuantity\Length;

$height = new Length(6.16, 'feet');
echo $height->toUnit('m');

// would print 1.87757, which is 6.16 feet in meters.

这种抽象允许您创建接受物理量而不要求它们以特定单位表示的接口。例如，此函数假设高度是一个特定单位的浮点数（可能是英尺）

// Tied to a specific unit of measure
function isTooTallToRideThisTrain( $height )
{
  return $height > 5;
}

// Calling the function requires that you first convert whatever quantity you have into the expected units:
isTooTallToRideThisTrain(2 / 0.3048);

而此版本允许高度以任何方便的单位提供

use PhpUnitsOfMeasure\PhysicalQuantity\Length;

// Free to operate on lengths in any unit of measure
function isTooTallToRideThisTrain( Length $height )
{
  return $height->toUnit('ft') > 5;
}

// Calling the function now allows any unit to be used:
isTooTallToRideThisTrain( new Length(2, 'm') );

安装

建议通过 composer 将此库包含在您的项目中。有关详细信息，请参阅Composer 网站，并查看Packagist.org 网站上的此库。

使用

转换

如上例所示，此库的基本用法是表示物理量并在典型单位之间进行转换。例如

$quantity = new \PhpUnitsOfMeasure\PhysicalQuantity\Mass(6, 'lbs');
echo $quantity->toUnit('g');

还可以隐式地将数量转换为字符串，这将显示其原始值

$quantity = new \PhpUnitsOfMeasure\PhysicalQuantity\Mass(6, 'pounds');
echo $quantity; // '6 lbs'

算术运算符

还支持加法和减法。由于 PhysicalQuantity 对象是不可变的，因此这些算术方法返回表示结果的新数量对象

$first  = new \PhpUnitsOfMeasure\PhysicalQuantity\Volume(6, 'liters');
$second = new \PhpUnitsOfMeasure\PhysicalQuantity\Volume(6, 'cups');

$sum = $first->add($second);
echo $sum; // 7.4195292 l

$difference = $first->subtract($second);
echo $difference; // 4.5804708 l

向现有数量添加新单位

有时，您需要向现有数量添加新单位。

例如，假设在一个项目中您需要一个名为“cubits”的新长度度量。您有两个选择：您可以将新单位永久添加到 \PhpUnitsOfMeasure\PhysicalQuantity\Length 类的新子类（或将其直接添加到该类并提交拉取请求以将其添加到上游，如果适用），或者您可以在调用代码中临时添加单位。

在运行时添加新单位

要在运行时向现有数量添加新单位，您会这样做

use \PhpUnitsOfMeasure\PhysicalQuantity\Length;
use \PhpUnitsOfMeasure\PhysicalQuantity\UnitOfMeasure;

// It's ok to use cubits here, since the conversion doesn't happen until later
$length = new Length(14, 'cubits');

// Build a new Unit of Measure object which represents the new unit, and which knows how to convert between
// the new unit and the quantity's native unit (in this case, meters).
$cubit = new UnitOfMeasure(

    // This is the official name of this unit - typically it's the standard abbreviation
    'cb',

    // The second parameter is a closure that converts from the native unit to this unit
    function ($x) {
        return $x / 0.4572;
    },

    // The third parameter is a closure that converts from this unit to the native unit
    function ($x) {
        return $x * 0.4572;
    }
);

// Any alias names for this unit can be added here, to make it easier to use variations
$cubit->addAlias('cubit');
$cubit->addAlias('cubits');

// Register the new unit of measure with the quantity object
$length->registerUnitOfMeasure($cubit);

// Now that the unit is registered, you can cast the measurement to any other measure of length
echo $length->toUnit('feet'); // '21'

永久向物理量添加新单位

上述方法仅适用于特定的长度对象，因此是临时的；每次创建新的测量并想要使用 cubits 时，都需要重复此过程。

可以通过基本相同的过程将新单位永久添加到物理量类，只需在数量类的构造函数中进行即可。例如

namespace PhpUnitsOfMeasure\PhysicalQuantity;

use \PhpUnitsOfMeasure\PhysicalQuantity;
use \PhpUnitsOfMeasure\UnitOfMeasure;

class Length extends PhysicalQuantity
{
    public function __construct($value, $unit)
    {
        parent::__construct($value, $unit);

        // ...
        // ...
        // Here's all the pre-existing unit definitions for Length
        // ...
        // ...

        // Build a new Unit of Measure object which represents the new unit, and which knows how to convert between
        // the new unit and the quantity's native unit (in this case, meters).
        $cubit = new UnitOfMeasure(

            // This is the official name of this unit - typically it's the standard abbreviation
            'cb',

            // The second parameter is a closure that converts from the native unit to this unit
            function ($x) {
                return $x / 0.4572;
            },

            // The third parameter is a closure that converts from this unit to the native unit
            function ($x) {
                return $x * 0.4572;
            }
        );

        // Any alias names for this unit can be added here, to make it easier to use variations
        $cubit->addAlias('cubit');
        $cubit->addAlias('cubits');

        // Register the new unit of measure with the quantity object
        $this->registerUnitOfMeasure($cubit);
    }
}

现在任何新的 Length 类对象都将内置 cubits 单位。

添加新的物理量

物理量是可测量值的类别，如质量、长度、力等。

对于本库中尚未存在的物理量，需要编写一个类来支持新的物理量。所有物理量都扩展了\PhpUnitsOfMeasure\PhysicalQuantity类，并且通常只有一个构造函数，用于创建物理量的度量单位。请参见上面的示例，了解如何向物理量类添加新单位。

注意，每个物理量都有一个选定的“本地单位”，通常为国际单位制（SI）标准。这个单位的主要作用是，所有其他单位的度量都会转换为所选的本地单位。在编写新单位的转换时，了解物理量的本地单位非常重要。

为现有单位添加新别名

可能存在这样的情况：对于正确的物理量确实存在合适的度量单位，但缺少了该单位的别名。例如，如果你认为'footses'是长度单位'ft'显然缺少的别名，你可以临时添加该别名，如下所示

use \PhpUnitsOfMeasure\PhysicalQuantity\Length;

// It's ok to use footses here, since the conversion doesn't happen until later
$length = new Length(4, 'footses');

// Fetch the unit of measure object that represents the 'ft' unit
$foot = $length->findUnitDefinition('ft');

// Any alias names for this unit can be added here, to make it easier to use variations
$foot->addAlias('footses');

// Now that the unit is registered, you can cast the measurement to any other measure of length
echo $length->toUnit('m'); // '1.2192'

当然，如果你需要永久添加别名，可以在物理量类的构造函数中这样做。

API 文档

API 文档（如果有的话）通过GitApiDoc处理。

http://gitapidoc.com/api/triplepoint/php-units-of-measure

测试和贡献

欢迎提交拉取请求，特别是关于新单位或新物理量的请求。但是，请注意，有许多来源提供了转换系数，并非所有都严格遵守已知精度。

在美国，计量标准机构为国家计量研究院（NIST），他们已发布NIST 特殊出版物 1038 "国际单位制（SI） - 通用转换系数"。本指南包含了各种单位与基本SI单位之间的批准转换系数。

请注意，任何新的物理量都应该为其本地度量单位选择适当的SI单位。

测试设置

在克隆此存储库后，安装Composer

cd {path_to_project_root}
php -r "eval('?>'.file_get_contents('https://getcomposer.org.cn/installer'));"

由于这是用于开发，因此使用开发依赖项进行安装

./composer.phar install --verbose --prefer-dist --dev

持续集成

持续集成通过Travis-CI处理。

https://travis-ci.org/triplepoint/php-units-of-measure

单元测试

可以使用以下方式手动运行与此项目相关的所有测试

vendor/bin/phpunit -c ./tests/phpunit.xml.dist ./tests

CodeSniffer

Codesniffer验证是否满足编码标准。一旦使用开发依赖项构建了项目，可以使用以下方式运行检查

vendor/bin/phpcs --encoding=utf-8 --extensions=php --standard=./tests/phpcs.xml -nsp ./

myfarms/php-units-of-measure

维护者

详细信息