Turbine Ui Core Laravel Package

Getting Started

This release is primarily an upgrade-and-packaging release: it adds Laravel 13 support and relocates the Breeze/profile publish templates into stubs/, so they are copied at publish time rather than resolved at runtime. That change is what makes php artisan view:cache safe in production.

1. Upgrade the constraint. Bump the package to ^2.1.6 and confirm your laravel/framework constraint allows v13. Laravel 13 raises the PHP floor, so check php -v against the new requirement before touching composer.json.
2. Re-publish stubs. Run the package's install/publish command with the same tags you used originally (typically vendor:publish --tag=<package>-stubs and --tag=<package>-config). Read the console output — it will list every file that was skipped because it already exists.
3. Migrate if needed. If the package ships migrations, run php artisan migrate and confirm no duplicate-table errors from previously published copies.
4. Look here first: the package's config/<package>.php (the knobs you will actually turn), the new stubs/ directory in vendor/ (the source of truth for what gets published), and your app's resources/views/ for any previously published Breeze/profile templates now shadowing the stubs.
5. First use case: on a Breeze-scaffolded app, publish the stubs, open the generated profile views, and adjust markup. Because the templates now originate from stubs/, the published output is ordinary application code you own — edit it freely.

Implementation Patterns

Publish-then-own. The idiomatic workflow is publish once, then treat the generated files as first-class application code. Use the package's publish tags rather than copying files out of vendor/ by hand; tags are what the maintainers keep stable across releases.

Stub-first customization for teams. If you maintain multiple apps, keep your customized copies of the published templates in a shared internal package or a resources/views/vendor/<package>/ override directory, and let the vendor stubs remain untouched. This gives you a clean diff on the next upgrade instead of merge conflicts in vendor/.

Deployment ordering. The release exists to make view caching correct, so wire the deploy pipeline accordingly:

php artisan vendor:publish --tag=<package>-stubs --force   # only if you intentionally re-sync
php artisan config:cache
php artisan route:cache
php artisan view:cache

Cache after publishing and after config:cache, never before — a cached view set built against the old stub layout is the exact failure mode this release addresses.

Breeze stack variants. If your app uses the Livewire or Inertia flavors of Breeze, verify the published profile templates target the correct stack. Publish into a scratch branch first and diff, since template names and component structure differ between stacks.

CI matrix. Add Laravel 13 to your test matrix alongside your current version and assert the suite passes on both during the transition. The package now supports both, so a green run on 12 and 13 is a reasonable acceptance gate before merging the upgrade.

Verification step. After deploying, hit the profile routes as an authenticated user and confirm the pages render from the cached view set (storage/framework/views populated, no runtime template resolution errors).

Gotchas and Tips

Silent staleness is the big one. Moving templates into stubs/ means previously published copies in your application are no longer refreshed automatically. vendor:publish will not overwrite existing files without --force. If profile pages look unchanged after upgrading, you are almost certainly rendering your old published copies, not the new stubs. Diff before forcing:

php artisan vendor:publish --tag=<package>-stubs --force   # back up first

Clear caches on both sides of the upgrade. php artisan view:clear and php artisan config:clear before and after the composer update. Compiled views generated under the old resolution mechanism can mask whether the fix actually landed.

Laravel 13 dependency conflicts. The most common upgrade blocker is a transitive dependency still pinned to laravel/framework ^10|^11|^12. Run composer why-not laravel/framework 13.* to identify the culprit before assuming the package is at fault.

PHP version drift. Laravel 13's PHP floor is higher than earlier majors. Local dev may pass while a CI image or a production container lags — pin the PHP version in both.

Don't cache views in local development. view:cache hides template edits until you clear. Keep it out of your local scripts; use it only in deploy pipelines.

Extension points worth knowing: the package config file (published, versioned in your repo), the publish tags (stable identifiers for stubs and config), and the stubs themselves (copy them into your own scaffold if you need organization-wide defaults). If you need behavior the config does not expose, prefer a view override in resources/views/vendor/<package>/ over editing vendor/ directly — edits there vanish on the next composer update.

When to suspect a publishing bug: if vendor:publish reports success but a template is missing, check the tag name against the package's service provider — tag names occasionally change between majors, and a wrong tag fails quietly for some tags.