Elasticsearch Bundle Laravel Package

Getting Started

1. Update the dependency:

   composer require <vendor>/<package>:^6.0.4
   

   Confirm the installed version:

   composer show <vendor>/<package>
   

2. Review the package’s service provider and configuration first. Look for:

   • Config publishing: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   • Default score precision, rounding, or threshold settings
   • Any casts, DTOs, or value objects used for score results

3. Run the package’s test suite or a small local integration test before using the new float score behavior in production.

4. First use case: replace integer-only score handling in a ranking, matching, validation, or recommendation flow with float scores where finer ordering matters.

   Example pattern:

   $result = $scorer->score($subject);
   
   // v6.0.4 supports float results
   $score = (float) $result->score();
   

Implementation Patterns

• Use float scores for ordering, not identity. Treat the score as a ranking value and avoid using it as a cache key, unique identifier, or exact-match discriminator.
• Persist scores with an appropriate column type. If scores are stored in the database, use decimal rather than float when exact decimal behavior matters:

  $table->decimal('score', 8, 4)->nullable();
  

  For ephemeral ranking only, a PHP float is usually sufficient.
• Normalize at the boundary. If the package now returns float scores, cast once when consuming the result:

  $score = (float) $result->score();
  

  Avoid repeated casting throughout views, jobs, and API resources.
• Use explicit rounding for presentation. Keep full precision internally and round only at the display layer:

  number_format($score, 2);
  

• Update comparisons and thresholds deliberately. Replace strict integer expectations with tolerance-based checks:

  if (abs($score - $expected) < 0.0001) {
      // treat as equal
  }
  

• API resources should declare score format. Avoid leaking unstable float representations directly:

  return [
      'score' => round($result->score(), 4),
  ];
  

• Queue and job payloads should carry scalar scores. If passing results between jobs, pass the float score and relevant metadata rather than serializing the entire result object.
• Use feature tests around ordering. Add tests that assert relative ordering rather than exact scores:

  $this->assertGreaterThan($low->score(), $high->score());
  

• Integration tip: If the package powers search or recommendations, compare old integer results with new float results on a representative dataset before rollout. Float scores can change tie-breaking behavior.

Gotchas and Tips

• Floating-point equality is unreliable. Do not use ===, ==, or direct database equality against float scores unless you control precision and storage format.
• JSON serialization may expose long decimals. PHP floats can serialize with more precision than expected. Round explicitly in API resources if consumers expect stable output.
• Database drivers differ. MySQL, PostgreSQL, and SQLite may handle float/decimal comparisons and sorting differently. Test ordering queries on the production database engine.
• Casts can silently truncate. Check Eloquent casts such as integer, decimal:2, or custom casts. An integer cast will discard the new fractional score.
• Validation rules may reject floats. Rules like integer or numeric|max:100 may need adjustment. Prefer numeric and explicit bounds.
• Caching can mask behavior changes. If scores are cached, clear score-related cache keys after upgrading and verify TTLs do not preserve old integer-shaped results.
• Tie-breaking behavior changes. Floats reduce ties, but they do not eliminate them. Add deterministic secondary sorting, such as ID or timestamp, when ordering scored results.
• Debugging tip: Log both the raw score and the rounded score during rollout:

  logger()->debug('score result', [
      'raw' => $result->score(),
      'rounded' => round($result->score(), 4),
  ]);
  

• Configuration quirks: Check whether precision, rounding, or threshold values are configurable. If so, publish the config and set them explicitly rather than relying on package defaults.
• Extension points: If the package exposes score formatters, result DTOs, or ranking contracts, prefer extending those over monkey-patching vendor code. Keep custom formatting in your application layer.
• Patch-release caution: v6.0.4 is a patch release, but changing score return types can still affect strict comparisons, database casts, cached payloads, and API contracts. Treat it as behaviorally relevant and regression-test score-consuming paths.