Nova Config Laravel Package

Getting Started

• Install into an existing Nova app: composer require illuminatech/nova-config. This package assumes Nova 3/4-era conventions, so confirm Nova version compatibility before adopting.
• Publish the package config and any frontend assets with php artisan vendor:publish --provider="Illuminatech\\NovaConfig\\NovaConfigServiceProvider" (vendor tag likely nova-config). Check config/ and public/vendor/ after publishing.
• Register the tool in app/Providers/NovaServiceProvider.php → tools():

  public function tools()
  {
      return [
          new \Illuminatech\NovaConfig\NovaConfig(),
      ];
  }
  

• First place to look: the published config file under config/ (or the package README's blueprint section). It defines which config keys are exposed as form fields — this is the source of truth for the UI, not the database.
• Define your first settings file (e.g. config/site-settings.php) returning a flat array, and point the tool at it. The file must be present and writable by the PHP user.
• First use case: expose a handful of admin-editable values — support email, phone, maintenance-mode toggle, social links — that non-developers need to change without a deploy. This package is not a replacement for a full settings/Database package; it edits PHP config files.

Implementation Patterns

• Blueprint-driven fields. Define each editable key with a label, type (text/toggle/select/number), default, and validation rules. The tool renders Nova fields from that blueprint and writes the resulting array back to disk. Keep the blueprint close to the config file it manages so they stay in sync.
• Read through config() normally. After a save, resolve values with config('site-settings.support_email'). Business code does not depend on the package at all — that is the main appeal: settings are plain config values, easy to inject, mock, and test.
• Group related settings. Use one config file per domain (mail, social, billing) and register multiple tool instances or logical groups so admin screens stay focused. Avoid one giant settings blob — it becomes a merge-conflict magnet.
• Validation and casting at the boundary. Put rules on each field and cast booleans/numbers explicitly on read ((bool) config(...)). Nova's checkbox state and PHP's "false" string are easy to confuse; normalize once on save.
• Authorization. Gate the tool behind a Nova policy/permission (viewNovaConfig) so only trusted admins can edit config. Editing a PHP config file is effectively code-adjacent privilege.
• Workflow fit. Use it for values that change without a deploy but don't warrant their own table: feature flags, hero copy, contact details, rate limits. For anything transactional, per-tenant, or high-volume, use a real settings package or Eloquent — config files are a single global scope.
• Deploy integration. Include the settings config file in your release artifact (or symlink it), so changes survive deployments and aren't overwritten by a fresh checkout. Many teams keep it in a shared directory outside the release folder.

Gotchas and Tips

• Writable file, not config:cache. Writes go to a PHP file on disk. Once php artisan config:cache runs, Laravel serves the cached array and ignores file edits until re-cached. Either re-cache after saves (custom button/hook) or accept a stale UI read. This is the single most common surprise.
• Permissions. The web user needs write access to the target config file. Read-only deployments, containerized filesystems, and read-only bind mounts will silently fail or throw. Test in staging with the same user as production.
• Version control churn. Every admin save rewrites the file, producing dirty working trees and noisy diffs. Consider excluding the settings file from VCS, or committing it deliberately and treating saves as auditable changes.
• Concurrency. File-based writes are not transactional; two admins saving simultaneously can lose an edit. Low-traffic admin panels are fine; high-traffic or multi-admin setups need a lock or a DB-backed alternative.
• Security. There is no license metadata in the package descriptor (NOASSERTION) — verify the actual license in the repo LICENSE file before commercial use. Also treat arbitrary config keys as potentially dangerous: never let non-admins define new keys, and validate types strictly.
• Escape/type pitfalls. PHP values written back must be valid PHP (true, null, integers, escaped strings). A stray quote or unescaped apostrophe in a text field can corrupt the file. Keep validation rules strict and test edits with quotes and backslashes.
• Caching of the tool's own output. If you read settings in hot paths, consider a small cached accessor (Cache::remember('settings', ...)) and invalidate on save, since each read otherwise relies on the config repository already being loaded.
• Extending. The tool is small; if a field type is missing, subclass the tool or add custom Nova fields rather than forking the package. Check the blueprint/factory extension points in the source before patching.
• Maturity signal. 13 stars and a low activity score mean you're an early adopter: pin the exact version, read the source (it's small), and have a fallback plan (a custom Nova page or a well-known settings package) if it stalls. For a low-risk settings screen it's fine; for a critical admin surface, budget for maintenance.
• Debugging. When a save "does nothing," check three things in order: (1) config:cache status, (2) file permissions/owner, (3) the target file path resolved by the published config. Laravel logs will usually surface the write failure, but permission errors are easy to miss behind Nova's generic success toast.