LaravelUi5
Get Started

Upgrading ​

The SDK has followed strict semantic versioning since 1.0.0. That is a promise with teeth, and it is what makes upgrading a short procedure rather than a project:

  • Patch — a fix. Nothing you wrote changes.
  • Minor — additions. Nothing you wrote changes.
  • Major — a contract breaks, deliberately and with notice.

There is no longer any convention under which a breaking change ships as a patch. The 0.x line had one — SemVer credit spent, while every consumer was in-house — and it was retired at 1.0.0 across the whole stack.

Before you run anything: read the head of the changelog ​

Each release opens with a sentence naming what it was about, and — this is the part worth reading — the intro paragraph says what to run. A typical one ends:

Nothing here requires action on upgrade beyond the usual ui5:sync, ui5:help --all and ui5:nav.

When a release needs more than that, this is where it says so, and that is the kind of thing you cannot infer from the version number. Read it.

The procedure ​

bash
composer update laravelui5/sdk
php artisan migrate --force
php artisan ui5:sync
php artisan ui5:cache && php artisan ui5:nav
php artisan ui5:help --all
php artisan ui5:publish --force

It is the deploy chain — an upgrade is a deploy, and running the shorter version of it is how installations end up in half-states.

The shell upgrades itself

The bundle ships inside the package and is served from there, at a URL carrying the SDK version. So an upgrade moves the URL by construction: the browser requests a file it has never seen, and there is no cache to purge and no hard reload to remember. ui5:publish still belongs in the chain — it carries the fonts and the fallback avatar the bundle references — but the shell itself is current the moment composer update finishes.

What a minor may do to you ​

Nothing — by contract. But two kinds of addition are worth a look, because they change what is possible rather than what works:

  • A new #[Access] or #[Act] on a shipped app. The ability is new, so nobody holds it yet, and the surface it guards is closed until you grant it. The changelog says so when it happens.
  • A new default binding. The SDK binds defaults with bindIf or plain bind; your own binding in your own provider always wins. If a release adds a default for a port you already bound, you keep yours.

What @internal means for you ​

From 1.2.0 the SDK marks its machinery @internal — classes and interfaces that are implementation detail rather than contract. The marker changes no behaviour and breaks no code today.

What it changes is the promise: an @internal class may change or disappear in a minor. So it is worth one grep before an upgrade:

bash
grep -rn 'LaravelUi5\\Sdk' app/ --include='*.php' | grep -vE 'Contracts|Attributes|Enums|Models|Exceptions'

Anything that turns up wants checking against the release notes. The rule of thumb the marking follows: if a host names a class in config/ui5.php, it is public. Attributes, enums, models and most contracts and exceptions are public; resolvers, workers, controllers, producers and command classes are not. The exceptions to the folder rule are marked: the Sync and Help contracts, the Settings reader and writer interfaces and six Settings exceptions are @internal, so check the tag, not the folder.

What a major will look like ​

None has happened yet in the 1.x line, so this describes the commitment rather than an experience:

  • It gets its own migration notes, not a changelog bullet.
  • Your composer.json constraint stops it reaching you. A ^1 absorbs every minor and patch and excludes the next major, which is the point — a major is a deliberate, coordinated upgrade in every consumer, never something composer update does to you on a Tuesday.

The same applies across the stack. laravelui5/core and laravelui5/odata are on strict SemVer too, and OData has already taken a major past 2.0.0; each one is its own decision.

Version compatibility across the stack ​

The SDK declares what it needs and Composer enforces it. What that means in practice:

  • You do not pin Core yourself. The SDK's own constraint on laravelui5/core decides which Core versions can be installed alongside it. Adding your own narrower pin is how you end up with an unsolvable dependency set.
  • Upgrade the SDK, and Core follows within the range the SDK allows.
  • A Core major is an SDK release, because the SDK's constraint has to move first. If you want a new Core major, the question is which SDK version allows it.

Never take a version number from documentation — including this page. The authoritative sources are each package's CHANGELOG.md head and, for the public trio, the roadmap pills on laravelui5.com.

After the upgrade ​

Run the five-step smoke test. It takes two minutes and it exercises the registry, the shell bundle, the help output, the OData stack and the write path — which is exactly the set an upgrade touches.

If something is off, troubleshooting starts from the symptom.

Downgrading ​

Composer will let you. The database will not follow: ui5:sync has already reconciled it to the newer declarations, and reconciling deletes what the code no longer declares.

Treat a downgrade as a rollback — check out the older release, run the full chain against it, and remember that migrations are the part that does not reverse cleanly.