Variables Module Laravel Package

Getting Started

1. Install into a Streams Platform application (this module is an addon, not a standalone Laravel package):

   composer require anomaly/variables-module
   php artisan addon:install anomaly/variables-module
   php artisan migrate
   

   If your app uses addon discovery, confirm the module appears in Admin → Addons before continuing.

2. Look here first, in this order:

   • src/VariablesModuleServiceProvider.php — bindings, route registration, helper/plugin registration.
   • The repository/model classes under src/ (e.g. VariableRepository, VariableModel or similar) — this is the actual API surface you will call.
   • src/Http/Controller/Admin/ and resources/views/ — the admin CRUD you get for free.
   • Whatever registers the Twig function / Blade helper (variables(...)) — that's your template-facing entry point.

3. First use case: create a single global variable such as support_email or footer_disclaimer in the admin UI, then render it:

   {{ variables('support_email') }}
   

   {{ variables('support_email') }}
   

   Once that round-trip works, you have validated install, migration, caching, and the helper in one shot.

Verify exact method names against the source before writing anything significant — this package has effectively no documentation, no stars, and no dependents, so the code is the spec.

Implementation Patterns

Treat it as a key/value settings store with an admin UI. The day-to-day value is not the data model, it's that non-developers can edit copy without a deploy.

• Group related variables. Use the group field to cluster variables (footer, contact, legal). It keeps the admin list navigable once you pass ~15 entries and gives you a natural way to fetch a whole set.

• Centralise access behind your own façade. Don't sprinkle variables('x') through 40 templates. Add a thin service or Blade directive with typed accessors and defaults:

  class SiteContent
  {
      public function supportEmail(): string
      {
          return variables('support_email') ?: config('site.default_email');
      }
  }
  

  This is your escape hatch if the package dies — you swap the body, not every template.

• Seed variables in migrations/seeders, not by hand, so staging and production stay in sync:

  // migration or seeder
  $repo->updateOrCreate(['key' => 'support_email'], ['value' => '[email protected]']);
  

  New environments then bootstrap with sensible values instead of nulls.

• Override per environment via .env or config() where the variable is editorial copy vs. genuinely environment-specific. Don't put API keys in the variables table — it's an admin-editable surface.

• Cache aggressively at the call site if the repository isn't already caching:

  $footer = Cache::rememberForever('vars.footer', fn () => variables()->group('footer'));
  

  Then flush that key in a model observer / saved hook so editors see changes immediately.

• Template integration: use it for hero text, legal disclaimers, contact blocks, social URLs. Avoid it for anything structured (repeaters, relations) — that's Streams fields' job.

Gotchas and Tips

• Keys are permanent identifiers. Renaming a key silently breaks every template referencing it. Keep keys immutable snake_case; change only the human-readable label. Consider a key prefix convention (footer_*) so ownership is obvious.
• Missing keys return null/empty, not an exception. Always supply a fallback in the template or accessor, otherwise a deleted variable becomes an invisible blank region in production.
• Escaping surprises. Variables containing HTML need {!! !!} in Blade or |raw in Twig. Decide deliberately — raw output of admin-editable content is an XSS vector if non-admins can reach that screen.
• Caching will bite you during QA. If edits don't appear, clear the app cache and any per-request memoisation in the repository before assuming the save failed. Check whether the module caches on boot.
• Version/compatibility risk is the headline issue. Zero stars, zero dependents, low opportunity score — this package is tied to a specific Streams Platform generation. Pin an exact version in composer.json, check the composer.json constraints of the module against your Laravel/Streams versions before composer require, and expect no upstream fixes.
• Permissions are easy to forget. Lock the admin routes behind the module's permission slugs; otherwise any admin user can rewrite site copy or inject markup.
• Not a localisation tool. If you need per-locale values, you'll likely be modelling that yourself (one variable per locale, or a JSON value plus your own resolution layer). Don't assume the module does it.
• Extension points are thin. There is no documented plugin/field-type API surface you should rely on. If you need typed variables (booleans, images, links), store strings and cast in your accessor layer rather than subclassing internals.
• Debugging tip: when a template renders empty, dump variables()->all() (or the equivalent) from a route or php artisan tinker first — that instantly distinguishes "variable not saved" from "helper not registered" from "template syntax wrong".