Cumulus Laravel Package

Getting Started

• Install with composer require orrison/cumulus (v1.1.0 or later — the ENV support added in this release is worth having from day one).
• Publish the config: php artisan vendor:publish --tag=cumulus-config. This drops config/cumulus.php into your app, which is the first place to look when behaviour is unexpected.
• As of v1.1.0, values in that config file can be driven from .env. Rather than editing the published config, add the corresponding keys to .env (and .env.example) and let the config read them. This is now the recommended setup path for anything environment-specific — credentials, endpoints, feature toggles.
• Clear cached config after wiring up env vars: php artisan config:clear (or config:cache in deploy).
• First use case: configure a single default connection/profile in .env, resolve the package from the container (or its facade if provided), and run one end-to-end call in a tinker session or a throwaway artisan command before wiring it into a controller.

Implementation Patterns

• Env-first configuration. With ENV support in place, treat .env as the source of truth for anything that differs between local/staging/production, and keep config/cumulus.php as the mapping layer only. Avoid hardcoding values into the published config — it makes deployments and secret rotation painful.
• Per-environment overrides. Laravel loads .env.{APP_ENV} style setups (via your own bootstrap tweaks) cleanly now that config is env-driven; keep a .env.testing with safe/dummy values so the test suite never touches real services.
• Service-layer wrapping. Don't call the package directly from controllers. Put a thin wrapper (e.g. app/Services/CumulusService.php) around it so config resolution, retries, and logging live in one place and the package can be swapped or upgraded without touching call sites.
• Testing. Override config in tests with config(['cumulus.…' => 'fake']) in setUp() or via phpunit.xml <env> entries — since v1.1.0, env vars declared in phpunit.xml will actually reach the package, which removes the previous need for manual config() juggling.
• Queues and long-running workers. Env-backed config is resolved once per process. If you change .env during local development, restart queue:work/horizon — a running worker won't pick up the new values.
• Deployment. Ship .env values via your secret manager/CI variables, then php artisan config:cache as the last deploy step. This is now the supported happy path rather than a workaround.

Gotchas and Tips

• env() outside config files returns null when config is cached. The v1.1.0 change works because the config file calls env(). If you're tempted to call env('CUMULUS_…') directly in your own application code, don't — use config('cumulus.…').
• Config cache is the #1 cause of "the env var isn't being picked up". Run php artisan config:clear after every .env edit in local dev. In production, forgetting to re-run config:cache after adding a key means the old file stays cached.
• Published configs go stale. Upgrading from v1.0.x to v1.1.0 may add new env(...) entries to the shipped config file; your already-published config/cumulus.php will not have them. Diff the package's config/cumulus.php against yours after upgrading, or republish with --force and re-apply customisations.
• Env var naming conventions. Expect a package prefix (e.g. CUMULUS_*). Keep the names identical across .env, .env.example, CI secrets, and any container/orchestration config — typos here fail silently as null rather than throwing.
• Booleans and lists from env. env() returns strings; if the package casts them internally, fine — but if you're passing env-derived values further, be explicit ((bool), explode(',', ...)) to avoid "false" evaluating truthy.
• Extension points. Prefer binding a subclass or a custom driver through the container over editing the published config; that survives upgrades. If the package exposes a manager/driver pattern, register custom drivers in a service provider rather than in config/cumulus.php.
• Debugging. php artisan tinker → config('cumulus') shows exactly what the package sees after env resolution and config caching. That single command resolves most "why isn't my env var working" questions.
• Version pinning. v1.1.0 is additive (env support only, no breaking changes per the changelog), so ^1.1 is safe for new and existing installs. Existing v1.0.x configs continue to work unchanged since the hardcoded defaults remain as fallbacks.