Hmmmath Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require lstrojny/hmmmath
   

   No additional configuration is required—just autoload the package.

2. First Use Case: Basic Math Operations

   use Lstrojny\HmmMath\Math;
   
   $result = Math::sum([1, 2, 3]); // 6
   $result = Math::avg([1, 2, 3]); // 2
   

3. Where to Look First

   • Core Class: Lstrojny\HmmMath\Math (static methods for operations).
   • Documentation: Check the GitHub repo (if available) or run php artisan vendor:publish --tag=hmmmath-config (if config exists).
   • Examples: Explore the tests/ directory in the package for usage patterns.

Implementation Patterns

Common Workflows

1. Basic Arithmetic

   $sum = Math::sum([10, 20, 30]);
   $product = Math::product([2, 3, 4]); // 24
   $mean = Math::avg([1, 2, 3, 4, 5]); // 3
   

2. Statistical Functions

   $median = Math::median([1, 3, 2]); // 2
   $mode = Math::mode([1, 2, 2, 3]); // 2
   $stdDev = Math::stdDev([1, 2, 3, 4, 5]); // ~1.41
   

3. Integration with Laravel

   • Service Provider Binding (if extending functionality):

     $this->app->bind('math', function () {
         return new \Lstrojny\HmmMath\Math();
     });
     

   • Helper Function (in app/Helpers/MathHelper.php):

     if (!function_exists('math')) {
         function math($operation, $data) {
             return \Lstrojny\HmmMath\Math::$operation($data);
         }
     }
     

     Usage:

     $result = math('sum', [1, 2, 3]); // 6
     

4. Batch Processing

   $data = [10, 20, 30, 40, 50];
   $stats = [
       'sum' => Math::sum($data),
       'avg' => Math::avg($data),
       'max' => Math::max($data),
   ];
   

5. Custom Logic with Chaining

   $result = Math::sum([1, 2, 3])
                ->multiply(2) // 12
                ->subtract(4); // 8
   

Gotchas and Tips

Pitfalls

1. Input Validation

   • The package assumes valid numeric input. Always sanitize data:

     $cleanData = array_filter($rawData, fn($val) => is_numeric($val));
     $result = Math::sum($cleanData);
     

2. Edge Cases

   • Empty arrays may return null or throw errors (check method docs).
   • Math::mode() returns the first mode if multiple exist (behavior may vary).

3. Performance

   • For large datasets, consider chunking or using generators:

     $generator = function() {
         yield 1; yield 2; yield 3; // etc.
     };
     $sum = Math::sum(iterator_to_array($generator()));
     

Debugging Tips

1. Enable Error Reporting

   error_reporting(E_ALL);
   ini_set('display_errors', 1);
   

   • Useful for catching silent failures (e.g., invalid inputs).

2. Log Intermediate Results

   $data = [1, 2, 3];
   \Log::debug('Input data:', ['data' => $data]);
   $result = Math::sum($data);
   \Log::debug('Result:', ['result' => $result]);
   

3. Test Edge Cases

   $this->assertEquals(0, Math::sum([])); // If supported
   $this->assertNull(Math::mode([]));    // If unsupported
   

Extension Points

1. Custom Functions

   • Extend the Math class or create a wrapper:

     class ExtendedMath extends \Lstrojny\HmmMath\Math {
         public static function customOperation($data) {
             return self::sum($data) * 2;
         }
     }
     

2. Configuration

   • If the package supports config (unlikely for this lightweight lib), publish it:

     php artisan vendor:publish --tag=hmmmath-config
     

   • Modify config/hmmmath.php (if exists) for defaults (e.g., precision for stdDev).

3. Integration with Laravel Collections

   $collection = collect([1, 2, 3]);
   $sum = $collection->sum(); // Native Laravel
   // OR
   $sum = Math::sum($collection->toArray());
   

4. Precision Handling

   • For financial calculations, use bcmath or gmp:

     $result = Math::sum([1.1, 2.2], 2); // Round to 2 decimal places