Math Laravel Package

Getting Started

Treat this as a legacy dependency, not a default Laravel package. hoa/math is archived, its release line stopped in 2017 (the latest being 1.17.05.16, which only expanded the arithmetic constant table), and it has no Laravel integration. Use it only when you specifically need one of its small math primitives and accept the maintenance risk.

Minimal steps:

1. Check whether it can coexist with your app before committing:

   composer require hoa/math --dry-run
   composer why-not hoa/math
   

   Expect possible conflicts with modern PHP and other hoa/* packages. Do not use --ignore-platform-reqs just to force it in.

2. Look first at the source and README for:

   • Hoa\Math\Set — set operations such as union, intersection, difference, Cartesian product, power set.
   • Hoa\Math\Combinatorics\Combination — combinations/arrangements for small combinatorics tasks.
   • Hoa\Math\Context and Hoa\Math\Visitor\Arithmetic — variable/function context and AST arithmetic evaluation, usually in conjunction with Hoa\Compiler.

3. Try the simplest useful case in php artisan tinker, e.g. comparing permission sets:

   use Hoa\Math\Set;
   
   $current = new Set(['read', 'write']);
   $required = new Set(['write', 'publish']);
   
   $missing = $required->difference($current);
   

The first realistic day-to-day use case is not “do math in Laravel”; it is “use one isolated set/combinatorics helper behind an adapter.” For expression evaluation, confirm the Hoa\Compiler dependency path first, because the arithmetic visitor is AST-oriented and may pull in more legacy surface than expected.

Implementation Patterns

Wrap Hoa types behind application-owned services. Do not let Hoa\Math\Set, visitors, or exceptions leak into controllers, models, or Blade views.

final class PermissionDiff
{
    /** @return string[] */
    public function missing(array $current, array $required): array
    {
        $currentSet = new \Hoa\Math\Set($current);
        $requiredSet = new \Hoa\Math\Set($required);

        return iterator_to_array($requiredSet->difference($currentSet));
    }
}

Bind adapters in a service provider so tests can replace them:

$this->app->bind(PermissionDiff::class, fn () => new PermissionDiff());

Use it at the boundaries of a workflow. Good fits:

• Small set comparisons in authorization or feature-flag logic.
• Generating small combinations for scheduling, product variants, or test matrices.
• One-off calculations in Artisan commands or Tinker, not web request hot paths.
• Legacy compatibility where an existing domain already depends on Hoa semantics.

Convert to Laravel-native structures at the edge. Turn Hoa sets into arrays or Collections before passing data to the rest of the app, and convert back only inside the adapter. This keeps serialization, validation, and testing familiar.

Guard combinatorial input. Combinations grow explosively. Validate n and k, cap results, and push heavier generation into queued jobs rather than synchronous requests.

If using Hoa\Math\Visitor\Arithmetic, keep parsing and evaluation separate. Parse/compile once where possible, validate allowed variables and functions against an allow-list, and cache results keyed by expression plus variable values. Treat it as an evaluator for trusted internal expressions, not as a sandbox for arbitrary user code. The arithmetic constant set is fixed at the library level and differs slightly between 1.17.x builds, so pin the version and assert the constants you rely on.

Test with the exact PHP version used in production. A package that worked on PHP 7-era runtimes may behave differently under PHP 8.x. Add a small smoke test for the specific set or arithmetic operation you depend on.

Gotchas and Tips

• Archived status is the main gotcha. There will be no security fixes or PHP compatibility updates. Pin the version, document why it is present, and plan an exit path.
• No Laravel auto-discovery or facade. Everything is manual namespace usage (Hoa\...), and there is no config file, Artisan integration, or framework-aware exception handling.
• Exceptions are Hoa exceptions, not Laravel exceptions. Catch them inside your adapter and rethrow domain exceptions so the rest of the app is not coupled to Hoa.
• Context state can leak. If you use Hoa\Math\Context, create a fresh context per evaluation or explicitly reset variables/functions. Reusing a mutable context across requests or jobs can produce subtle cross-contamination.
• Set membership semantics matter. Verify whether equality/hashing is strict or loose for your values, especially with objects, floats, and duplicate-looking strings. Test the exact values you will store.
• Objects and sets are a poor mix unless identity is controlled. Prefer scalar IDs or normalized strings inside Hoa sets, then resolve models afterward.
• Not arbitrary precision. This is not a money library. Use brick/math or integer minor units for currency; use hoa/math only for ordinary native numeric work.
• Combinatorics can exhaust memory. Compute counts first, enforce limits, and never expose raw combination generation directly to unbounded user input.
• Composer conflicts are likely. The hoa/* dependency family is old; check composer why-not hoa/math and avoid forcing installation into a modern Laravel dependency graph.
• The arithmetic visitor is not a complete expression-language product by itself. It is tied to Hoa AST concepts; if you need a maintained expression evaluator, consider Symfony ExpressionLanguage instead.
• Constants are a version-locked detail, not a feature you can lean on. The 1.17.05.16 patch only widened the arithmetic constant table (e.g. additional named constants available to Visitor\Arithmetic). Do not design around a constant being present unless your composer.lock pins that build and a test covers it; upgrading or downgrading the patch level can change which constants resolve.
• Extension points are minimal and undocumented. Prefer composition and adapters over subclassing Hoa classes. The source is the real documentation.
• Replacement guidance: for new Laravel work, use native arrays/Collections for simple set logic, brick/math for precision, and a maintained expression evaluator for user-defined formulas. Keep hoa/math only where existing legacy behavior must be preserved.