How do I update a FirebaseUser's phone number in firebase_auth?

In my Flutter app I use Firebase's phone number authentication as my main form of authentication. After authenticating, I create a user in my users collection with these details:

{
    phoneNumber: FirebaseAuth.instance.currentUser().phoneNumber,
    displayName: 'Comes from user textbox',
    ...
}

But say one day a user want's to change their phone number. How do I do this? Because I cannot simply change the user's phone number in the document, because the phone number needs to be authenticated. And after authentication, the user gets a new authUID. Which should then be a new user?

Could someone explain the logic behind a user that wants to keep their profile details but change their number.

In order to achieve this, you can use User.updatePhoneNumber. This allows you to update the phone number of a user.

You would use it in the same manner that you also authenticated with phone number in the first place (using signInWithCredential), i.e. you retrieve a credential using FirebaseAuth.verifyPhoneNumber and pass the credential that you get from either verificationCompleted or your user when they enter the SMS code they received. I will only sketch out what this would look like as I assume that you know how to perform this task:

FirebaseAuth.instance.verifyPhoneNumber(
        phoneNumber: phoneNumber,
        timeout: const Duration(minutes: 2),
        verificationCompleted: (credential) async {
          await (await FirebaseAuth.instance.currentUser()).updatePhoneNumber(credential);
          // either this occurs or the user needs to manually enter the SMS code
        },
        verificationFailed: null,
        codeSent: (verificationId, [forceResendingToken]) async {
          String smsCode;
          // get the SMS code from the user somehow (probably using a text field)
          final AuthCredential credential =
            PhoneAuthProvider.getCredential(verificationId: verificationId, smsCode: smsCode);
          await (await FirebaseAuth.instance.currentUser()).updatePhoneNumber(credential);
        },
        codeAutoRetrievalTimeout: null);

When updatePhoneNumber is called, you probably also want to update your database document. Alternatively, you could listen to onAuthStateChanged and update your document this way.