Verseoftheday Laravel Package

Getting Started

v1.1.0 adds Bible version support and defaults to NIV. Treat this as a behaviorally significant feature release: existing calls that do not specify a version will now resolve through the NIV default, while new code can opt into other translations.

Start by checking:

1. The package README for the exact version-selection API (version(...), translation(...), request option, or config key).
2. The publishable config file, likely config/bible.php, for the default version and supported-version list.
3. The package service provider / facade binding if you inject the client rather than using a facade.
4. Existing tests and snapshots that assert verse text, because the default output may now be NIV.

Minimal setup:

composer require <vendor>/<package>:^1.1
php artisan vendor:publish --tag=bible-config
php artisan config:clear

Set the default explicitly in .env if the app should not silently inherit NIV:

BIBLE_VERSION=NIV

First use case: render a verse using the configured default, then allow an override per request.

// Defaults to NIV via package config.
$verse = Bible::verse('John 3:16');

// Per-call override, using the package's actual version API.
$verse = Bible::version('ESV')->verse('John 3:16');

If the package exposes a helper or injected client instead of a facade, keep the same pattern: resolve the client, select a version, then fetch the passage.

Implementation Patterns

Set one application default, then override deliberately. Put the default in config/env so staging and production are explicit. Avoid scattering 'NIV' literals through controllers.

// config/bible.php
return [
    'default_version' => env('BIBLE_VERSION', 'NIV'),
    // ...
];

Pass version as a request-level concern. For user-facing Bible readers, validate the requested version against the package's supported list before passing it to the client.

$data = $request->validate([
    'version' => ['nullable', 'string', Rule::in(config('bible.versions', ['NIV']))],
    'reference' => ['required', 'string'],
]);

$verse = Bible::version($data['version'] ?? config('bible.default_version'))
    ->verse($data['reference']);

Persist user preference separately from package config. Store the user's chosen version on the user/profile/settings table, then resolve it at the edge of the request.

$version = $user->bible_version ?: config('bible.default_version');

$passage = Bible::version($version)->verse($reference);

Cache per version and reference. Version support makes cache keys more important. Never cache a verse under a key that omits the translation.

$version = $user->bible_version ?: config('bible.default_version');

$passage = Cache::remember(
    "bible:{$version}:{$reference}",
    now()->addDay(),
    fn () => Bible::version($version)->verse($reference)
);

Expose the effective version in API resources and view data. Clients and templates should know which translation produced the text.

return [
    'reference' => $reference,
    'version' => $version,
    'text' => $passage->text,
];

Keep version selection out of domain logic. Resolve the version in controllers, form requests, jobs, or dedicated services, then pass a simple value object or string into the rest of the app.

Test with a fixed default. In phpunit.xml, set BIBLE_VERSION=NIV so tests do not depend on a developer's local .env. Add coverage for default resolution, explicit override, invalid version handling, and cache-key separation.

Gotchas and Tips

• Default change is the main upgrade risk. v1.1.0 defaults to NIV. If the prior release had a different implicit translation or returned translation-agnostic content, existing screens and snapshot tests may change. Audit assertions on verse text after upgrading.
• Do not assume version codes equal display names. NIV, ESV, etc. are likely identifiers. Validate against the package's supported list rather than accepting arbitrary strings.
• Clear config cache after publishing or changing defaults. php artisan config:clear prevents stale bible.default_version values in local and deployed environments.
• Include the version in every cache key. Otherwise an NIV verse can be served to a user who requested ESV.
• Verse text and numbering can differ by translation. Do not assume the same wording, footnotes, or even verse boundaries across versions. Keep formatting and footnote handling translation-aware.
• Check licensing and API limits per translation. A translation that is available in the package may still have attribution, caching, or rate-limit requirements.
• Log or expose the effective version during debugging. When output looks wrong, confirm whether the app resolved the user preference, request override, or config default.
• Prefer the package's extension points over editing vendor code. If the package supports a custom version resolver or config-driven supported-version list, use that for tenant-specific or user-specific defaults.
• Upgrade path: if the release note is sparse, review the package diff and README before relying on the new API. Confirm whether the NIV default is configurable and whether omitted-version calls are intentionally backwards-compatible.