Astrel Laravel Laravel Package

Getting Started

astrel_env() is a thin convenience wrapper around the package's core astrel() helper. If you already use astrel(), upgrading is a drop-in — nothing existing changes, and you get a shorter way to express the common "slug maps to an env var" pattern.

Minimal adoption:

composer update vendor/astrel

Look first at your existing astrel() call sites where the second argument is literally env('SOMETHING', $default). Those are the prime refactor targets:

// Before
astrel('my-slug', env('MY_SLUG'));

// After
astrel_env('my-slug');

The first real use case: define a slug once, let ops point it at whatever environment variable they need in each deployment, and read it consistently across local, staging and production without branching on app()->environment() in your own code.

// config/services.php or a feature config
'checkout_v2' => astrel_env('checkout-v2', 'CHECKOUT_V2', false),

Implementation Patterns

Derived env key. The one-argument form derives the env key from the slug, so astrel_env('my-slug') resolves env('MY_SLUG'). Establish a slug convention (kebab-case in, SCREAMING_SNAKE env in) and use the one-arg form everywhere for consistency. Reach for the two-arg form only when the env name intentionally differs from the slug — e.g. legacy vars you cannot rename.

Explicit key, no default. Fine for required values; pair it with a validation or an exception at boot so a missing env fails loudly rather than resolving to null deep in a request:

$bucket = astrel_env('upload-bucket', 'UPLOAD_BUCKET');

Explicit key with default. The most defensive form and the one I would standardise on for anything user-facing:

astrel_env('checkout-v2', 'CHECKOUT_V2', false);
astrel_env('page-size', 'PAGE_SIZE', 25);

Centralise the registry. Rather than scattering astrel_env() calls through controllers and Blade views, wrap them in a config file or a small service so the set of slugs the app knows about is discoverable and testable in one place:

// config/features.php
return [
    'checkout_v2' => astrel_env('checkout-v2', 'CHECKOUT_V2', false),
    'new_nav'     => astrel_env('new-nav', 'NEW_NAV', false),
];

Then config('features.checkout_v2') in the app. This gives you normal Laravel config caching semantics (see gotchas) and Config::set() works in tests.

Testing. Because the wrapper ultimately calls env(), the predictable way to test is to stub via config or putenv() before the container boots, or to inject a fake/override the value in the service that reads it. Prefer the injected/faked route over putenv() in Pest/PHPUnit — mutated env vars leak between tests.

Gotchas and Tips

env() and config caching. This is the big one. Laravel's env() helper returns null once php artisan config:cache has run, unless the variable is also read inside a config file (which is where config caching captures it). If astrel_env() is called at runtime outside of a config file, it will work in local dev and silently return the default in production. Keep astrel_env() calls inside config files, or verify behaviour with php artisan config:cache in a staging environment before relying on it.

Default resolution timing. The third argument is passed straight through to env($key, $default). That means the default is only used when the env var is genuinely unset — an empty-string env var (MY_SLUG=) will resolve to '', not your default. Coerce explicitly if empty strings are meaningful to you: astrel_env(...) ?: $fallback.

Type coercion. env() applies its own casting — "true"/"false"/"null"/"empty" string literals become booleans/null. Don't double-cast the result by accident; if you need an int, cast once downstream rather than wrapping again.

Slug-to-env derivation. The one-arg form's slug conversion is a naming convention, not magic. If your slug contains dots, slashes, or mixed casing, do not assume it maps to what you expect — always pass the env key explicitly when the slug is anything other than plain kebab-case.

Extension points. If you need caching, per-tenant overrides, or a database-backed store behind the slug, wrap astrel()/astrel_env() in your own resolver class rather than calling the helpers directly from call sites. That keeps the package as a leaf dependency you can swap out later.

Upgrade safety. v1.0.2 is additive only — no signature changes, no deprecations. Safe to take on patch. No config or migration changes required.