Coindesk Laravel Package

Getting Started

1. Install the package with Composer using the package name from its README/Packagist listing, then let Laravel auto-discover the service provider. If the package ships a config file, publish it and set any required API base URL, timeout, or cache values in .env.
2. Look first at the README’s quick-start example, the package service provider, the main client/service class, and—for v1.2.0—the figure formatter used by the price response. The formatter is the main changed surface in this release.
3. First use case: fetch a spot price and render it with the package formatter. The v1.2.0 behavior is: values below 1 are shown to 2 significant figures, while values at or above 1 keep 2 decimal places.

// Exact method names depend on the package README.
$price = $coinDesk->price('BTC', 'USD');

$raw = $price->amount();      // keep numeric value for calculations
$display = $price->formatted(); // v1.2.0 formatting rules

Use the raw value for arithmetic, comparisons, and storage; use the formatted value only for display.

Implementation Patterns

• Inject the client, not the facade, in application services. This keeps price lookups testable and makes it easy to swap a fake client in tests.
• Cache upstream responses, not formatted strings. Cache the raw API payload or numeric value for a short TTL (for example 30–60 seconds), then format per request. This avoids stale display formatting and reduces rate-limit pressure.
• Keep raw and formatted values together. A small DTO or value object with raw, currency, formatted, and fetchedAt fields prevents accidentally doing math on a display string.
• Use the formatter consistently across assets. The new rules are especially useful for mixed portfolios: sub-dollar altcoin prices get significant-figure precision, while BTC/ETH-scale values stay readable with 2 decimal places.
• Blade integration: expose a component or view helper that accepts the raw value and returns the package-formatted string. Avoid calling the API directly from Blade templates.
• Testing pattern: use Laravel’s Http::fake() to return fixed CoinDesk responses, then assert both raw values and formatted output at boundary values.
• Integration tip: if the application already has a money/currency formatting layer, wrap the package formatter behind an interface rather than scattering direct calls. That makes it possible to replace the formatter later without touching views.

Gotchas and Tips

• Formatting boundary at 1: v1.2.0 switches rules at 1. Test values just below and above it, such as 0.999, 0.9999, 1.0, 1.001, and 1.005.
• Significant figures can round up across the threshold. A value like 0.999 formatted to 2 significant figures may become 1.0; confirm whether the formatter re-applies the “above 1” decimal-place rule or simply outputs the rounded significant-figure result.
• Trailing zeros and scientific notation: “2 significant figures” can be implemented with sprintf, number_format, or a decimal library, and each produces different trailing-zero behavior. Check the actual output for very small values such as 0.00001234.
• Locale and decimal separators: the package formatter likely uses . as the decimal separator. If the UI needs comma separators or localized currency symbols, format after the package call or wrap it with NumberFormatter.
• Floating-point precision: for very small altcoin prices, PHP floats can lose precision. If exact display matters, keep the API’s string value where possible and format from that.
• Do not cache formatted output when the formatter can change. Cache raw numbers; format at render time. This also makes future formatter changes take effect immediately.
• Handle API failures around price widgets. Catch connection/timeout exceptions and provide a fallback display so a price lookup cannot break an entire page.
• Config changes need a cache clear. After publishing or editing package config, run php artisan config:clear during development.
• Extension point: if the built-in formatter does not meet your locale or asset-specific needs, bind a custom formatter/wrapper in a service provider rather than forking the package. Keep the package formatter as the default for standard spot prices.
• Debugging tip: log both the raw API value and the formatted result when investigating display bugs. The most common issue will be confusing decimal places with significant figures, not the API response itself.