Tuieditor Bundle Laravel Package

Getting Started

The v1.0.4 release adds a form_theme config entry, which means theming is now driven by configuration rather than being hard-coded. Start there.

1. Install / update

   composer require <vendor>/<package>:^1.0
   # or, if already installed
   composer update <vendor>/<package>
   

2. Publish the config (first place to look):

   php artisan vendor:publish --provider="<Vendor>\\<Package>\\<Package>ServiceProvider" --tag=config
   

   Then open config/form_theme.php and read the comments — the new form_theme key is the single most important knob in the package.

3. Clear caches after publishing, since config is read at boot:

   php artisan config:clear && php artisan view:clear
   

4. First use case — render one form with the default theme, then flip the config value and re-render:

   // config/form_theme.php
   return [
       'form_theme' => env('FORM_THEME', 'default'),
   ];
   

   {{-- resources/views/contact.blade.php --}}
   {!! form_row($form->name) !!}
   

   Confirm the markup changes when you switch FORM_THEME. That single loop (edit config → clear cache → re-render) is the fastest way to build a mental model of the package.

Implementation Patterns

Global theme via environment. Put the theme name in .env (FORM_THEME=bootstrap) so staging and production can diverge without code changes. Keep the config file returning env(...) with a sane fallback so a missing variable never breaks rendering.

Per-form / per-view override. Prefer resolving the theme at the point of rendering rather than mutating global config:

config(['form_theme' => 'tailwind']);   // scoped, but remember to restore

For anything beyond a one-off, wrap this in a middleware or a small service so you don't leak state between requests (important under Octane).

Custom themes as view namespaces. Register your own theme directory and reference it by name instead of editing vendor views:

// AppServiceProvider::boot()
View::addNamespace('form-themes', resource_path('views/vendor/forms'));

This keeps you upgrade-safe: vendor publishes are overwritten on update, your namespace is not.

Override partials selectively. Copy only the partial you need from the package's theme folder into your own theme, and let the rest fall through to the package default. Fewer files to maintain, and upstream fixes keep landing.

Testing. Assert on rendered output rather than config internals:

$this->get('/contact')
     ->assertSee('form-control');   // marker of the bootstrap theme

Set the theme explicitly in the test (config(['form_theme' => 'default']) in setUp) so a developer's local .env can't change CI results.

CI / deploy. Run php artisan config:cache as part of the deploy step, after .env is in place. If you're on a containerised setup, bake the theme into the image's environment rather than editing files on the host.

Gotchas and Tips

• Config caching bites first. config/form_theme.php changes do nothing until php artisan config:clear (or a re-run of config:cache). This is the number one "the new feature doesn't work" report. Verify with php artisan tinker --execute="dump(config('form_theme'));".
• The exact key shape is worth confirming. v1.0.4 introduces the form_theme config; depending on how it's nested it may be config('form_theme') (a string) or config('form_theme.default') (an array with a default key). Dump the config once after publishing rather than assuming — the release note describes the addition, not its final structure.
• View cache on theme switches. If you switch themes and see stale markup, php artisan view:clear. Compiled Blade views are keyed by path, not by theme name.
• Vendor publishes are disposable. Anything you edit inside resources/views/vendor/... will be silently replaced on composer update. Keep customisations in your own namespace or a fork-tracked directory.
• State leakage under Octane / long-running workers. A config([...]) override made during one request persists into the next. If you allow per-request themes, reset in a terminating callback or middleware finally block.
• Fallback behaviour. Test with a deliberately invalid theme name and note what happens — an exception is preferable to a silent fallback to unstyled markup, but you need to know which you'll get before it happens in production.
• Extension points to prefer, in order: (1) config value, (2) own view namespace, (3) overriding a single partial, (4) subclassing/replacing the theme resolver, (5) patching vendor code — essentially never.
• Debugging checklist when a theme doesn't apply: config cached? view cached? correct env var quoted in .env (values with spaces need quotes)? theme name matches the directory name exactly (case-sensitive on Linux)? service provider registered in config/app.php or auto-discovered?
• Watch the changelog for the next 1.0.x. A config key added in a patch release can be renamed before 1.1; pin to ~1.0.4 and read release notes before bumping.