bugs & features

added lots of length,area and volume units

inversed factor for relative units as thats more logical

added tests for (relative) factors on custom units

Author: pimlie

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 As this package is still very much a work in progress, any help adding more unit's and unit tests is really appreciated!
 
 A couple of things are important when submitting a Pull Request:
-- Use the PSR-2 Coding Standard
+- Use PSR-2 Coding Standard
 - Add tests
 - Use the method of implementation as described below
 
@@ -25,23 +25,15 @@ imperial / usc systems.
 Now create a folder `Unit/XXX/` in which we will place all the unit classes for this unit type, after this proceed with adding a base unit
 
 #### Adding a base unit
-We prefer the base unit to be a unit from the metric system. This way we can easily add all SI prefixed units by extending them from the base
-unit and only implement a `PhpUnitConversion\Prefix\Metric\<SI_Prefix>` interface. E.g. the implementation of `Mass\MilliGram` is:
-```php 
-class MilliGram extends Gram implements Metric, Milli
-{}
-```
-You should not set a `FACTOR` on the `BASE_UNIT`, otherwise the above implementation will fail because the interface `Prefix\Metric\Milli` 
-cannot overwrite an already defined class constant.
-
-See `Gruntfile.js` for a quick way to add all prefixed classes to your unit.
+We prefer the base unit to be a unit from the SI and/or metric system. If your unit should use the SI prefixes, please use the `Gruntfile.js` for a 
+quick way to add all prefixed classes to your unit.
 
 #### Add an new unit to a unit type
 When adding a unit `YYY` to unit type `XXX` start by creating the file `Unit/XXX/YYY.php`.
 
 If your unit has a linear correspondence to the base unit, just set the class constant `FACTOR` to its correct value.
-If your unit has an offset to the base unit, you can add a class constant `ADDITION`. 
-(Conversion to the BASE_UNIT value is done by first applying the `FACTOR`, then adding the `ADDITION`)
+If your unit has an offset to the base unit, you can add a class constant `ADDITION_PRE` or `ADDITION_POST`. 
+These correspond to the following formula: `BaseUnitValue = (ThisUnitValue + ADDITION_PRE) * FACTOR + ADDITION_POST`
 
 Please also set the class constant `SYMBOL` and `LABEL`. When your unit does not have a `SYMBOL`, omit it or set it to an empty string. `LABEL` is often equal to your lower case classname.
 
@@ -56,14 +48,14 @@ class AvoirdupoisPound extends Mass
 {
     use HasFactor;
 
-    const FACTOR = 453.59237; // FACTOR is relative to Mass\Gram, 453.6 Gram in a Pound
+    const FACTOR = 453.59237; // FACTOR is relative to Mass\Gram, 1 Avoirdupois Pound is 453.6 Gram
 }
 
 class Ounce extends Pound
 {
     use HasRelativeFactor;
 
-    const FACTOR = 16; // FACTOR is relative to Mass\Pound, 16 Ounce in a Pound
+    const FACTOR = 1/16; // FACTOR is relative to Mass\Pound, 1 Ounce is 1/16 Pound (or 16 Ounce in a Pound)
 }
 ```
 
@@ -111,4 +103,4 @@ composer test
 or
 ```
 vendor/bin/phpunit
-```
+```

Gruntfile.js

@@ -31,19 +31,20 @@ module.exports = function(grunt) {
         fileExt = '.php',
         baseUnits = {},
         units = [
-            { unit: 'Mass',   symbol: 'g', label: 'gram', prefix: '' }, 
-            { unit: 'Length', symbol: 'm', label: 'meter', prefix: '' }, 
-            { unit: 'Area',   symbol: 'm', label: 'meter', prefix: 'Square' },
-            { unit: 'Volume', symbol: 'm', label: 'meter', prefix: 'Cubic' },
+            { unit: 'Mass',   base: 1, relative: 0, symbol: 'g', label: 'gram', prefix: '' }, 
+            { unit: 'Length', base: 1, relative: 0, symbol: 'm', label: 'meter', prefix: '' }, 
+            { unit: 'Area',   base: 1, relative: 0, symbol: 'm', label: 'meter', prefix: 'Square' },
+            { unit: 'Volume', base: 1, relative: 0, symbol: 'm', label: 'meter', prefix: 'Cubic' },
+            { unit: 'Volume', base: 1, relative: 1, symbol: 'l', label: 'liter', prefix: '' },
          ];
     phpTemplate = `<?php
 namespace PhpUnitConversion\\Unit\\<%= unit %>;
 
 use PhpUnitConversion\\System\\Metric;
-
+<%= extraIncludes %>
 class <%= baseUnitPrefix %><%= prefixSI %><%= baseUnit %> extends <%= baseUnitPrefix %><%= baseUnit %> implements Metric
 {
-    const FACTOR = <%= factor %>;
+<%= extraUses %>    const FACTOR = <%= factor %>;
 
     const SYMBOL = '<%= symbol %>';
     const LABEL = '<%= label %>';
@@ -52,20 +53,26 @@ class <%= baseUnitPrefix %><%= prefixSI %><%= baseUnit %> extends <%= baseUnitPr
     var baseRegex = /BASE_UNIT\s*=\s*([^:]+)::/,
         replaceExt = new RegExp(fileExt);
 
-    //grunt.file.recurse(siPrefixes, function(abspath, rootdir, subdir, filename) {
     for (var u = 0; u < units.length; u++) {
       var baseUnitPrefix = units[u].prefix,
           baseUnit = units[u].label.replace(/\b./g, function(m){ return m.toUpperCase(); })
 
       if(baseUnit) {
         for (var i = 0; i < siPrefixes.length; i++) {
           siPrefix = siPrefixes[i]
-          var prefixSI = siPrefix.label.replace(/\b./g, function(m){ return m.toUpperCase(); }) /*filename.replace(replaceExt, '')*/,
+          var prefixSI = siPrefix.label.replace(/\b./g, function(m){ return m.toUpperCase(); }),
               phpFileName = unitFolder + units[u].unit + '/' + baseUnitPrefix + prefixSI + baseUnit + fileExt,
-              factor = '1E' + siPrefix.factor * (baseUnitPrefix === 'Cubic' ? 3 : (baseUnitPrefix === 'Square' ? 2 : 1)),
+              factor = units[u].base + 'E' + siPrefix.factor * (baseUnitPrefix === 'Cubic' ? 3 : (baseUnitPrefix === 'Square' ? 2 : 1)),
               symbol = siPrefix.symbol + units[u].symbol + (baseUnitPrefix === 'Cubic' ? '3' : (baseUnitPrefix === 'Square' ? '2' : '')),
               label = (baseUnitPrefix ? baseUnitPrefix.toLowerCase() + ' ' : '') + siPrefix.label + units[u].label;
 
+          extraIncludes = ''
+          extraUses = ''
+          if (units[u].relative) {
+            extraIncludes = 'use PhpUnitConversion\\Traits\\HasRelativeFactor;\n';
+            extraUses = '    use HasRelativeFactor;\n\n';
+          }
+
           if(true||!grunt.file.exists(phpFileName)) {
             console.log(phpFileName);
             grunt.file.write(phpFileName, 
@@ -74,6 +81,8 @@ class <%= baseUnitPrefix %><%= prefixSI %><%= baseUnit %> extends <%= baseUnitPr
                   factor: factor,
                   symbol: symbol,
                   label: label,
+                  extraIncludes: extraIncludes,
+                  extraUses: extraUses,
                   prefixSI: prefixSI,
                   baseUnit: baseUnit,
                   baseUnitPrefix: baseUnitPrefix
@@ -83,6 +92,5 @@ class <%= baseUnitPrefix %><%= prefixSI %><%= baseUnit %> extends <%= baseUnitPr
         }
       }
     }
-    //});
   });
 };

composer.json

@@ -25,7 +25,8 @@
         "myclabs/php-enum": "^1.5"
     },
     "require-dev": {
-        "phpunit/phpunit": "^6.0.7"
+        "phpunit/phpunit": "^6.0.7",
+        "squizlabs/php_codesniffer": "^3.1"
     },
     "autoload": {
         "psr-4": {
@@ -38,6 +39,7 @@
         }
     },
     "scripts": {
-        "test": "vendor/bin/phpunit"
+        "test": "vendor/bin/phpunit",
+        "cs": "vendor/bin/phpcs src/*"
     }
 }

phpunit.xml.dist

@@ -22,7 +22,7 @@
         </whitelist>
     </filter>
 
-    <logging>
+    <!-- logging>
         <log type="coverage-text" target="php://stdout" showUncoveredFiles="true"/>
-    </logging>
+    </logging -->
 </phpunit>

src/System.php

@@ -4,4 +4,4 @@
 interface System
 {
 
-}
+}

src/System/Imperial.php

@@ -6,4 +6,4 @@
 interface Imperial extends System
 {
 
-}
+}

src/System/Metric.php

@@ -6,4 +6,4 @@
 interface Metric extends System
 {
 
-}
+}

src/System/USC.php

@@ -6,4 +6,4 @@
 interface USC extends System
 {
 
-}
+}

src/Traits/BaseUnit.php

@@ -10,4 +10,4 @@ protected function toBaseUnit()
         }
         return parent::toBaseUnit();
     }
-}
+}

src/Traits/HasFactor.php

@@ -8,38 +8,68 @@ public function getFactor()
         return self::FACTOR;
     }
 
-    public function getAddition()
+    public function getAdditionPre()
     {
-        if (defined('static::ADDITION')) {
-            return self::ADDITION;
+        if (defined('self::ADDITION_PRE')) {
+            return self::ADDITION_PRE;
         }
 
         return false;
     }
 
-    protected function fromBaseValue($value)
+    public function getAdditionPost()
     {
-        $value/= self::getFactor();
-        
-        $addition = self::getAddition();
+        if (defined('self::ADDITION_POST')) {
+            return self::ADDITION_POST;
+        }
+
+        return false;
+    }
+
+    protected function fromBaseValue($baseValue)
+    {
+        $value = $baseValue;
+
+        $addition = self::getAdditionPost();
+        if ($addition !== false) {
+            $value-= $addition;
+        }
+
+        $factor = self::getFactor();
+        if ($factor !== false) {
+            $value/= $factor;
+        }
+
+        $addition = self::getAdditionPre();
         if ($addition !== false) {
             $value-= $addition;
         }
 
         return $value;
     }
+
 
     protected function toBaseValue($value = null)
     {
-        if($value === null) $value = $this->value;
+        if ($value === null) {
+            $value = $this->value;
+        }
+
+        $addition = self::getAdditionPre();
+        if ($addition !== false) {
+            $value+= $addition;
+        }
+
+        $factor = self::getFactor();
+        if ($factor !== false) {
+            $value*= $factor;
+        }
 
-        $addition = self::getAddition();
+        $addition = self::getAdditionPost();
         if ($addition !== false) {
             $value+= $addition;
         }
 
-        $value*= self::getFactor();
-        
         return $value;
     }
-}
+}

src/Traits/HasRelativeFactor.php

@@ -8,39 +8,69 @@ public function getFactor()
         return self::FACTOR;
     }
 
-    public function getAddition()
+    public function getAdditionPre()
     {
-        if (defined('static::ADDITION')) {
-            return self::ADDITION;
+        if (defined('self::ADDITION_PRE')) {
+            return self::ADDITION_PRE;
+        }
+
+        return false;
+    }
+
+    public function getAdditionPost()
+    {
+        if (defined('self::ADDITION_POST')) {
+            return self::ADDITION_POST;
         }
 
         return false;
     }
 
     protected function fromBaseValue($baseValue)
     {
-        $value = parent::fromBaseValue($baseValue);
-        $value*= self::getFactor();
-        
-        $addition = self::getAddition();
+        $value = $baseValue;
+
+        $addition = self::getAdditionPost();
         if ($addition !== false) {
             $value-= $addition;
         }
-        
-        return $value;
+
+        $factor = self::getFactor();
+        if ($factor !== false) {
+            $value/= $factor;
+        }
+
+        $addition = self::getAdditionPre();
+        if ($addition !== false) {
+            $value-= $addition;
+        }
+
+        return parent::fromBaseValue($value);
     }
-    
+
     protected function toBaseValue($value = null)
     {
-        if($value === null) $value = $this->value;
-        
-        $addition = self::getAddition();
+        if ($value === null) {
+            $value = $this->value;
+        }
+
+        $value = parent::toBaseValue($value);
+
+        $addition = self::getAdditionPre();
+        if ($addition !== false) {
+            $value+= $addition;
+        }
+
+        $factor = self::getFactor();
+        if ($factor !== false) {
+            $value*= $factor;
+        }
+
+        $addition = self::getAdditionPost();
         if ($addition !== false) {
             $value+= $addition;
         }
-        
-        $baseValue = $value / self::getFactor();
-        
-        return parent::toBaseValue($baseValue);
+
+        return $value;
     }
-}
+}