Laravel Astronomy Library Laravel Package

Getting Started

Install the package and let Laravel's package discovery register the service provider and Magnitude facade — no manual wiring is normally required:

composer require <vendor>/<package>

Look first at the Magnitude class itself (the class behind the facade). It is a small collection of static conversion helpers — the surface area you will actually use day-to-day is a handful of methods such as nelmToSqm(), so read the class top-to-bottom rather than hunting for docs. The bundled tests are the best specification of accepted input ranges and units.

A sensible first use case: you record an observer's naked-eye limiting magnitude (NELM) on a session/observation model and want a comparable SQM (mag/arcsec²) value for reporting, filtering, or charts.

use ...\Facades\Magnitude;

$sqm = Magnitude::nelmToSqm($session->nelm, $session->observer_offset);

$session->update(['sqm' => $sqm]);

Store the derived value rather than recomputing it in every view, and treat it as a denormalised cache of the input.

Implementation Patterns

Wrap the facade in your own service. Call Magnitude:: from one small application service (or a SkyQuality value object), not from controllers and Blade templates. That gives you one place to clamp inputs, handle the saturation ceiling, and swap the implementation later.

final class SkyQuality
{
    public static function fromNelm(float $nelm, float $offset = 0.0): float
    {
        return Magnitude::nelmToSqm(
            max(0.0, min(8.0, $nelm)),
            $offset,
        );
    }
}

Derive on write, not on read. Convert in a model observer / saving hook or a queued job so historical rows stay stable even if the underlying formula changes in a future major version. Recompute only during an explicit backfill.

Validate at the boundary. Add a FormRequest rule that bounds NELM to a physically plausible range (between:0,8) and constrains the offset. This is cheaper than defending against bad numbers at every call site, and it keeps garbage out of your aggregates.

Use a cast or accessor for presentation. A SkyQualityCast that returns a small DTO with nelm, offset, and sqm keeps rounding policy (e.g. round($sqm, 2)) in one place and prevents raw floats leaking into API payloads.

Backfills and imports: chunk them. If you are recomputing sqm across a large observations table, use chunkById() plus updateQuietly() (or a raw CASE update) rather than instantiating and saving every model.

Test with data providers. Conversion maths is pure — a @dataProvider with boundary values (0, ~6.6, 7.93, 8.0, and the offset variants) is a far better regression net than feature tests through HTTP.

Gotchas and Tips

Upgrade to v6.8.6 if you accept high NELM values. Prior to this patch, nelmToSqm() returned NAN once the NELM plus observer offset exceeded roughly 7.93, because the logarithm's argument went negative. Any code that persisted that value wrote a broken float into the database, and — more painfully — json_encode() refuses to encode NAN, so an API response containing a converted value would fail or return false with no obvious stack trace pointing at the cause. If you have historic rows with NAN, INF, or 0 where you expected a plausible SQM, audit and backfill them after upgrading.

The mapping saturates and is not invertible. SQM already reaches its ceiling of 22 at a NELM of about 6.6, so every NELM from 6.6 upward now maps to exactly 22. Do not round-trip: nelmToSqm() followed by the inverse will not return your original input in the dark-sky regime. If you need to preserve an observer's reported NELM, always store the input column — never reconstruct it from the derived SQM.

Watch the offset's sign and units. The observer offset is folded into the NELM before the log is taken, so an offset in the wrong direction silently shifts every result. Confirm the convention (additive vs. subtractive, magnitudes vs. something else) against the tests before wiring it into a form.

Clamp rather than assert. Because the ceiling is a legitimate, documented outcome rather than an error, prefer clamping inputs at the edges of your own domain over throwing exceptions in the conversion path — a session recorded at an exceptionally dark site should not break your save.

Float precision and column types. Use decimal(5,2) or double deliberately; float columns compared with = in queries will bite you. Round once, at write time, and compare with tolerances.

Extension points. If you need different photometric assumptions, bind your own implementation of the conversion service in a service provider and depend on the interface rather than the facade. If the facade is macroable, resist adding app-specific macros to it — that re-couples your domain code to the vendor namespace and makes the eventual v7 upgrade harder to reason about.