Upgrading

Upgrading a Laravix installation is one command. This article explains what that command does, how update notifications work, and what to do when an upgrade step fails.

Before you upgrade#

• Back up the database. The upgrade runs migrations; a backup is your undo button.
• Read the changelog — Laravix is under active development and breaking changes are possible before the first stable release.

Running the upgrade#

php artisan laravix:upgrade

The command shows your current version, asks you to confirm you've backed up (skip the prompt with --force), and then runs:

1. Composer. If a newer release is available, the command runs composer require laravix/cms:^<new version> --with-all-dependencies — which raises the constraint in your composer.json so the upgrade isn't blocked by the range you originally installed with. It tells you when it does this. If you're already on the newest release, or running a dev version, it falls back to composer update laravix/cms --with-all-dependencies. Either way it prints a table of changed package versions.
2. php artisan migrate --force — applies new database migrations.
3. php artisan vendor:publish --tag=laravix-assets --force — republishes the admin assets.
4. php artisan filament:assets — rebuilds Filament's published assets.
5. php artisan optimize:clear — clears the caches.

If a later step fails, the command tells you which one — run the remaining steps from the list above manually.

Expected result: Laravix CMS upgraded: 0.13.1 → 0.13.2.

When Composer reports an error. The command checks whether laravix/cms actually changed version despite the error — a failing post-install script, for example. If the package did update, it warns you and finishes the remaining steps rather than leaving your installation half-upgraded. Only when the version is genuinely unchanged does it stop with nothing else touched.

Note: The command looks for Composer in this order: the COMPOSER_BINARY environment variable, then an executable on the PATH, then a composer.phar in the project root.

Update notifications in the admin#

The admin panel checks Packagist for new laravix/cms releases (cached for 12 hours) and shows a banner with the upgrade command when one is available. To disable the check — for example on air-gapped servers — set:

CMS_UPDATE_CHECK=false

The same check feeds the upgrade command's decision in step 1, so disabling it also means laravix:upgrade will only ever run composer update and never raise your constraint.

What the upgrade does not touch#

• Your theme. themes/ belongs to you; the upgrade never overwrites it. New default-theme features arrive only in fresh installations — adopt them manually if you want them. The upgrade also doesn't re-run laravix:theme:link, so if you add a theme's dist/ directory afterwards, run that command yourself — see Theme Structure.
• Your content and settings — apart from schema migrations, data stays as it is.
• Your custom code — app-level providers, resources and plugins are yours.

Troubleshooting#

Composer reports version conflicts. Since the command raises the laravix/cms constraint itself, a conflict now usually means another dependency in your project pins something the new core needs. Inspect with composer why-not laravix/cms <version> and relax the conflicting constraint.

The admin looks broken after upgrading. Assets didn't republish. Run steps 3–5 manually and hard-refresh the browser.

Related articles#

• Installation
• Deployment
• CLI Commands