file.changeName() leaves UUID stub at old path; Panel creates _changes draft under wrong filename for orphaned sidecars

[DustinStupp]

Environment

• Kirby: 5.3.2
• PHP: 8.2
• Multilingual: yes (EN default, DE, ZH)
• OS: macOS 15

What happened

Using a file.create:after hook that calls $file->changeName($newBase) to auto-rename uploaded files.
Two related bugs appear:

---

Bug 1 — changeName() leaves a UUID-only stub at the old filename

After calling changeName(), the renamed file and its sidecar are created correctly at the new path. However, a UUID-only stub (22 bytes, Uuid: <originalUUID>) is left behind at the original sidecar path, with no corresponding media file.

Steps to reproduce:

1. Upload photo.jpg to a page in a multilingual site
2. In a file.create:after hook, call $file->changeName('newname')
3. Inspect the page's content folder

Expected:

• newname.jpg ✓
• newname.jpg.en.txt ✓ (with full content)
• photo.jpg.en.txt — deleted

Actual:

• newname.jpg ✓
• newname.jpg.en.txt ✓ (with full content, new UUID)
• photo.jpg.en.txt still exists — contains only Uuid: <originalUUID> (22 bytes)

Since photo.jpg no longer exists, Kirby's file collection for the page encounters a sidecar with no corresponding media file, causing errors when rendering the page.

---

Bug 2 — Orphaned sidecar misidentified as page content; Panel creates wrong _changes draft

When photo.jpg.en.txt (the stub from Bug 1) survives after the rename, and the user later opens the page in the Panel, Kirby's content scanner cannot find a corresponding photo.jpg media file. It therefore misidentifies the orphaned sidecar as the page content file.

The Panel then:

1. Creates _changes/photo.jpg.en.txt as a draft — containing the actual page content (Title, UUID matching the page, Page-layout blocks, etc.) rather than file metadata
2. This draft persists across uploads and can be published, recreating the orphan in the main content folder with the page's UUID embedded

This means any subsequent cleanup of photo.jpg.en.txt from the main folder may be undone when the Panel publishes the stale _changes draft.

---

Notes

• Calling update() on $file before changeName() returns a new File object (immutable model) — the changeName() call must use this updated object or Kirby throws "Storage for the file is immutable and cannot be moved."
• The UUID stub left by changeName() has the original UUID (pjsl3eeauhp4j5it), while the new sidecar gets a new UUID (1mdypinsdsbkv5iy). Content saved before the rename that references the old UUID via file://pjsl3eeauhp4j5it will therefore be broken regardless of the stub cleanup.
• rename() (deprecated) may have had the same behaviour; confirmed on changeName() in 5.3.2.

[afbora]

file.create:after hook, $file->changeName() returns a new File object, so that object should be returned from the hook:

'file.create:after' => function (Kirby\Cms\File $file) {
    return $file->changeName('newname');
}

This prevents the create flow from continuing with the old/original file object and keeps the post-rename state consistent.

However, there still needs to be a solution for orphaned sidecar files that were already created. If photo.jpg.en.txt remains but photo.jpg no longer exists, Kirby can no longer match it as file metadata and may interpret it as a page content/template file instead. The Panel can then create a wrong draft at _changes/photo.jpg.en.txt, containing actual page content rather than file metadata.

So the remaining question is: even if changeName() is fixed/used correctly, how should Kirby handle orphaned file sidecars? Should files like *.jpg.en.txt/*.jpg.de.txt without a matching media file be excluded from page content detection, or should the Panel/cleanup flow safely ignore or remove them?

[distantnative]

For Kirby, these aren't orphaned meta files of former files, but just another .txt that doesn't belong to any file present in the folder. There is no real way for Kirby to determine between that orphaned .txt and the actual content file which one should be ignored and which one is the actual content file (as also the content file's name could include multiple dots - template names with dots included are quite common).

[lukasbestle]

I agree with Nico, it's pretty much impossible to deal with this broken content state once it has already been created.

The question is: Can we improve Event::updateArgument() so it can handle this case of a missed return value from the hook automatically?

[DustinStupp]

Thank you all, correctly returning the File object as described by @afbora resolved the issue I was facing. Your discussion points still stand, would be great to see this handled automatically, but please feel free to close this issue if the hook works as intended.

[afbora]

Once orphan sidecar files already exist, it really doesn’t seem possible to distinguish them reliably after the fact. So instead of trying to solve that broken content state later, it may be better to focus on preventing it from being created in the first place.

I think the idea around Event::updateArgument() points in a good direction: actions like changeName() that return a new model could leave a “next model / successor” reference on the old model after they complete successfully. If a hook accidentally does not return that result, updateArgument() could see the hook result is null, inspect the current argument, find that successor reference and automatically replace the event argument with the new model.

For example:

'file.create:after' => function (File $file) {
    $file->changeName('newname');
}

Today, this can continue with the old $file state. If changeName() links the old file to the new file, Event::updateArgument() could pick that up and let the create flow continue with the newname.jpg model instead. This would not clean up existing orphan files, but it could prevent new broken states caused by a missing return.

@lukasbestle @distantnative This approach makes sense to me. What do you think: should we try something in this direction, or should we close the issue as a usage error where the hook result must be returned?

[lukasbestle]

We had a similar issue recently and I think it makes sense to do what we can to cover accidentally missed return values from hooks.