nystudio107 / craft-units

src/models/UnitsData.php

<?php
/**
 * Units plugin for Craft CMS
 *
 * A plugin for handling physical quantities and the units of measure in which
 * they're represented.
 *
 * @link      https://nystudio107.com/

The tag in position 1 should be the @copyright tag

 * @copyright Copyright (c) nystudio107

@copyright tag must contain a year and the name of the copyright holder

 */

PHP version not specified

Missing @category tag in file comment

Missing @package tag in file comment

Missing @author tag in file comment

Missing @license tag in file comment

namespace nystudio107\units\models;

use craft\base\Model;
use nystudio107\units\Units;
use PhpUnitsOfMeasure\AbstractPhysicalQuantity;
use PhpUnitsOfMeasure\Exception\NonNumericValue;
use PhpUnitsOfMeasure\Exception\NonStringUnitName;
use PhpUnitsOfMeasure\PhysicalQuantityInterface;
use PhpUnitsOfMeasure\UnitOfMeasure;
use PhpUnitsOfMeasure\UnitOfMeasureInterface;
use yii\base\InvalidArgumentException;
use function call_user_func_array;
use function get_class;

/**

Missing short description in doc comment

 * @author    nystudio107

The tag in position 1 should be the @package tag

Content of the @author tag must be in the form "Display Name <username@example.com>"

Tag value for @author tag indented incorrectly; expected 2 spaces but found 4

 * @package   Units

Tag value for @package tag indented incorrectly; expected 1 spaces but found 3

 * @since     1.0.0

The tag in position 3 should be the @author tag

Tag value for @since tag indented incorrectly; expected 3 spaces but found 5

 *
 * @property string $valueFraction
 * @property array|float[] $valueParts
 * @property array|string[] $valuePartsFraction
 */

Missing @category tag in class comment

Missing @license tag in class comment

Missing @link tag in class comment

class UnitsData extends Model implements PhysicalQuantityInterface
{
    // Public Properties
    // =========================================================================

    /**

Missing short description in doc comment

     * @var ?string The fully qualified class name of the unit of measure
     */
    public ?string $unitsClass = null;

    /**

Missing short description in doc comment

     * @var ?float The value of the unit of measure
     */
    public ?float $value = null;

    /**

Missing short description in doc comment

     * @var ?string The units that the unit of measure is in
     */
    public ?string $units = null;

    /**

Missing short description in doc comment

     * @var AbstractPhysicalQuantity
     */
    public AbstractPhysicalQuantity $unitsInstance;

    // Public Methods
    // =========================================================================

    /**
     * Call through to the appropriate method in the AbstractPhysicalQuantity
     * class in $unitsInstance, if it exists
     *
     * @param string $method

Missing parameter comment

     * @param array $args

Missing parameter comment

Expected 2 spaces after parameter type; 1 found

     *
     * @return mixed
     * @throws InvalidArgumentException
     * @throws NonNumericValue
     * @throws NonStringUnitName
     */
    public function __call($method, $args)
    {
        $unitsInstance = $this->unitsInstance;
        if (method_exists($unitsInstance, $method)) {
            return call_user_func_array([$unitsInstance, $method], $args);
        }

        throw new InvalidArgumentException("Method {$method} doesn't exist");
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public function init(): void
    {
        parent::init();
        /** @var Settings $settings */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

        $settings = Units::$plugin->getSettings();
        $this->unitsClass = $this->unitsClass ?? $settings->defaultUnitsClass;
        $this->value = $this->value ?? $settings->defaultValue;
        $this->units = $this->units ?? $settings->defaultUnits;

        if ($this->unitsClass !== null) {
            $this->unitsInstance = new $this->unitsClass($this->value, $this->units);
        }
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public function rules(): array
    {
        $rules = parent::rules();
        $rules = array_merge($rules, [

The opening parenthesis of a multi-line function call should be the last content on the line.

            ['unitsClass', 'string'],
            ['value', 'number'],
            ['units', 'string'],
        ]);

For multi-line function calls, the closing parenthesis should be on a new line.

        return $rules;
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public function fields(): array
    {
        $fields = parent::fields();
        $fields = array_diff_key(
            $fields,
            array_flip([

The opening parenthesis of a multi-line function call should be the last content on the line.

                'unitsInstance',
            ])

For multi-line function calls, the closing parenthesis should be on a new line.

        );

        return $fields;
    }

    /**

Missing short description in doc comment

Parameter $unit should have a doc-comment as per coding-style.

     * @inheritdoc
     */

Missing @return tag in function comment

    public function toUnit($unit)
    {
        return $this->unitsInstance->toUnit($unit);
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public function toNativeUnit()
    {
        return $this->unitsInstance->toNativeUnit();
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public function __toString(): string
    {
        return $this->unitsInstance->__toString();
    }

    /**

Missing short description in doc comment

Parameter $quantity should have a doc-comment as per coding-style.

     * @inheritdoc
     */

Missing @return tag in function comment

    public function add(PhysicalQuantityInterface $quantity)
    {
        /** @var UnitsData $quantity */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

        return $this->physicalQuantityToUnitsData($this->unitsInstance->add($quantity->unitsInstance));
    }

    /**

Missing short description in doc comment

Parameter $quantity should have a doc-comment as per coding-style.

     * @inheritdoc
     */

Missing @return tag in function comment

    public function subtract(PhysicalQuantityInterface $quantity)
    {
        /** @var UnitsData $quantity */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

        return $this->physicalQuantityToUnitsData($this->unitsInstance->subtract($quantity->unitsInstance));
    }

    /**

Missing short description in doc comment

Parameter $testQuantity should have a doc-comment as per coding-style.

     * @inheritdoc
     */

Missing @return tag in function comment

    public function isEquivalentQuantity(PhysicalQuantityInterface $testQuantity)
    {
        /** @var UnitsData $testQuantity */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

        return $this->unitsInstance->isEquivalentQuantity($testQuantity->unitsInstance);

Accessing unitsInstance on the interface PhpUnitsOfMeasure\PhysicalQuantityInterface suggest that you code against a concrete implementation. How about adding an instanceof check?

    }

    /**

Missing short description in doc comment

Parameter $includeAliases should have a doc-comment as per coding-style.

     * @inheritdoc
     */

Missing @return tag in function comment

    public function availableUnits(bool $includeAliases = true)
    {
        $availableUnits = [];
        $units = $this->unitsInstance::getUnitDefinitions();
        /** @var UnitOfMeasure $unit */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

        foreach ($units as $unit) {
            $name = $unit->getName();
            $aliases = $unit->getAliases();
            $availableUnits[$name] = $includeAliases ? $aliases : $aliases[0] ?? $name;
        }

        return $availableUnits;
    }

    /**
     * Return the measurement as a fraction, with the units appended
     *
     * @return string
     */
    public function toFraction(): string
    {
        return trim(Units::$variable->fraction($this->value) . ' ' . $this->units);

It seems like $this->value can also be of type null; however, parameter $value of nystudio107\units\variables\UnitsVariable::fraction() does only seem to accept double, maybe add an additional type check?

    }

    /**
     * Return the measurement as a fraction, in the given unit of measure
     *
     * @param UnitOfMeasureInterface|string $unit The desired unit of measure,
     *                                             or a string name of one

Parameter comment not aligned correctly; expected 44 spaces but found 45

     *
     * @return string The measurement cast in the requested units, as a
     *                fraction
     */
    public function toUnitFraction($unit): string
    {
        $value = $this->toUnit($unit);

        return Units::$variable->fraction($value);
    }

    /**
     * Return the value as a fraction
     *
     * @return string
     */
    public function getValueFraction(): string
    {
        return Units::$variable->fraction($this->value);

It seems like $this->value can also be of type null; however, parameter $value of nystudio107\units\variables\UnitsVariable::fraction() does only seem to accept double, maybe add an additional type check?

    }

    /**
     * Return an array of the whole number and decimal number ports of the value
     * [0] has the whole number part, and [1] has the decimal part
     *
     * @return float[]
     */
    public function getValueParts(): array
    {
        return Units::$variable->float2parts($this->value);

It seems like $this->value can also be of type null; however, parameter $number of nystudio107\units\variables\UnitsVariable::float2parts() does only seem to accept double, maybe add an additional type check?

    }

    /**
     * Return an array of the whole number and decimal number ports of the
     * value with the decimal part converted to a fraction. [0] has the whole
     * number part, and [1] has the fractional part
     *
     * @return string[]
     */
    public function getValuePartsFraction(): array
    {
        $parts = Units::$variable->float2parts($this->value);

It seems like $this->value can also be of type null; however, parameter $number of nystudio107\units\variables\UnitsVariable::float2parts() does only seem to accept double, maybe add an additional type check?

        $parts[0] = (string)$parts[0];
        $parts[1] = Units::$variable->float2ratio($parts[1]);

        return $parts;
    }

    // Protected Methods
    // =========================================================================

    /**
     * Convert a PhysicalQuantity object into a UnitsData object
     *
     * @param PhysicalQuantityInterface $quantity

Missing parameter comment

     *
     * @return UnitsData
     */
    protected function physicalQuantityToUnitsData(PhysicalQuantityInterface $quantity): UnitsData
    {
        $unitsClass = get_class($quantity);
        list($value, $units) = explode(' ', (string)$quantity);
        $config = [
            'unitsClass' => $unitsClass,
            'value' => $value,
            'units' => $units,
        ];

        return new UnitsData($config);
    }
}