Skip to content

Commit cf319fc

Browse files
EhespEhesp
authored
docs: add migration guide (#3138)
1 parent 974d634 commit cf319fc

File tree

2 files changed

+257
-0
lines changed

2 files changed

+257
-0
lines changed

‎docs/migration-guide.mdx

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
---
2+
id: migration
3+
title: Migration Guide
4+
sidebar_label: Migration Guide
5+
---
6+
7+
With the recent [FlutterFire Roadmap](https://github.com/FirebaseExtended/flutterfire/issues/2582) announcement, we've
8+
changed the way developers integrate Flutter applications with Firebase. If you're currently using FlutterFire and wish
9+
to upgrade to the latest recommended versions, follow this guide to help ease that process.
10+
11+
> If you're starting a fresh project, you can ignore this page and follow the [Getting Started](overview.mdx) documentation.
12+
13+
The table below shows the recommended minimum versions for each plugin which the migration guide covers.
14+
15+
## Breaking Changes & Deprecations
16+
17+
Although breaking changes have been kept to a minimum, the substantial changes and improvements which have been made
18+
required us to break a few things (for the greater good). Where possible, we've deprecated any of the "old ways" of
19+
integrating FlutterFire. You should aim to replace these deprecations as soon as possible.
20+
21+
## Migration Steps
22+
23+
### 1. Adding `firebase_core`
24+
25+
The FlutterFire plugins now depend on the `firebase_core` plugin. The plugin is responsible for connecting your
26+
Flutter application to your Firebase project(s), and without it all other plugins will not work.
27+
28+
Add the plugin to your `pubspec.yaml` file within your project:
29+
30+
```yaml title="pubspec.yaml"
31+
dependencies:
32+
flutter:
33+
sdk: flutter
34+
firebase_core: "{{ plugins.firebase_core }}"
35+
```
36+
37+
Install the plugin by running the following command from the project root:
38+
39+
```bash
40+
$ flutter pub get
41+
```
42+
43+
### 2. Platform Setup
44+
45+
Even though you may have already setup your platform to connect with Firebase, we recommend following the new documentation
46+
steps for each platform to ensure everything is up-to-date.
47+
48+
Previously, it was possible to use FlutterFire without a "default" Firebase application. This has now changed, and all
49+
platforms now require an underlying default Firebase app has been registered. The platform specific guides below
50+
show you how to set up a default Firebase application:
51+
52+
#### A. [Android Installation](installation/android.mdx)
53+
54+
Ensure that the `com.google.gms:google-services` plugin is up-to-date.
55+
56+
#### B. [iOS Installation](installation/ios.mdx)
57+
58+
- If you manually configured the `[FIRApp configure];` or `FirebaseApp.configure()` within your projects `ios/{projectName}/AppDelegate{.m/.swift}` file,
59+
you can now safely remove it - FlutterFire automatically handles this for you.
60+
61+
#### C. [Web Installation](installation/web.mdx)
62+
63+
### 3. Initialize FlutterFire
64+
65+
To ensure each plugin has a consistent API and to enable the possibility of some new features, you are now required to
66+
initialize FlutterFire before performing any other Firebase related functionality.
67+
68+
The `firebase_core` package exposes a [`Firebase`](!firebase_core.Firebase) class, provides an
69+
[`initializeApp`](!firebase_core.Firebase.initializeApp) method. This method should be called as soon as possible in your
70+
application. It is responsible for ensuring the default app is ready, and bootstraps all additional FlutterFire plugins
71+
which are installed.
72+
73+
To learn more, view the [Initializing FlutterFire](overview.mdx#initializing-flutterfire) documentation.
74+
75+
## Plugin usage
76+
77+
Each plugin how provides a consistent API for integrating with Firebase. The example below shows how the `cloud_firestore`
78+
package previously created a new instance vs the new way:
79+
80+
```dart
81+
// Before
82+
Firestore firestore = Firestore();
83+
// After
84+
FirebaseFirestore firestore = FirebaseFirestore.instance;
85+
```
86+
87+
If you'd like to a plugin with a secondary Firebase application, use the `instanceFor` method instead:
88+
89+
```dart
90+
FirebaseApp secondaryApp = Firebase.app('SecondaryApp');
91+
92+
// Before
93+
Firestore firestore = Firestore(app: secondaryApp);
94+
// After
95+
FirebaseFirestore firestore = FirebaseFirestore.instanceFor(app: secondaryApp);
96+
```
97+
98+
To learn more about seconday Firebase app instances, view the [Initializing secondary apps](core/usage) documentation.
99+
100+
## Plugin Changes
101+
102+
### Core
103+
104+
- **DEPRECATED**: `FirebaseApp.configure` method is now deprecated in favor of the `Firebase.initializeApp` method.
105+
- **DEPRECATED**: `FirebaseApp.allApps` method is now deprecated in favor of the `Firebase.apps` property.
106+
- Previously, `allApps` was asynchronous & is now synchronous.
107+
- **DEPRECATED**: `FirebaseApp.appNamed` method is now deprecated in favor of the `Firebase.app` method.
108+
- **BREAKING**: `FirebaseApp.options` getter is now synchronous.
109+
110+
- `FirebaseOptions` has been reworked to better match web property names:
111+
- **DEPRECATED**: `googleAppID` is now deprecated in favor of `appId`.
112+
- **DEPRECATED**: `projectID` is now deprecated in favor of `projectId`.
113+
- **DEPRECATED**: `bundleID` is now deprecated in favor of `bundleId`.
114+
- **DEPRECATED**: `clientID` is now deprecated in favor of `androidClientId`.
115+
- **DEPRECATED**: `trackingID` is now deprecated in favor of `trackingId`.
116+
- **DEPRECATED**: `gcmSenderID` is now deprecated in favor of `messagingSenderId`.
117+
- Added support for `authDomain`.
118+
- Added support for `trackingId`.
119+
- Required properties are now `apiKey`, `appId`, `messagingSenderId` & `projectId`.
120+
121+
- Added support for deleting Firebase app instances via the `delete` method on `FirebaseApp`.
122+
- iOS: The default Firebase app is now automatically configured without needing to manually add Objective-C code to your iOS application.
123+
- Added support for returning consistent error messages from `firebase-dart` plugin.
124+
- Any FlutterFire related errors now throw a `FirebaseException`.
125+
- Added a `FirebaseException` class to handle all FlutterFire related errors.
126+
- Matching the web sdk, the exception returns a formatted "[plugin/code] message" message when thrown.
127+
- Added support for `setAutomaticDataCollectionEnabled` & `isAutomaticDataCollectionEnabled` on a `FirebaseApp` instance.
128+
- Added support for `setAutomaticResourceManagementEnabled` on a `FirebaseApp` instance.
129+
130+
- Android: Gradle build tools updated to 3.5.0 from 3.3.0.
131+
- Android: Removed Gradle ‘hacks’ and upgrade Flutter SDK requirement from `>=1.12.13+hotfix.4` to `>=1.12.13+hotfix.5` - based on PR https://github.com/flutter/plugins/pull/2651
132+
- Android: Switched to using Firebase BoM to manage SDK versions
133+
134+
### Firestore
135+
136+
Along with the below changes, the plugin has undergone a quality of life update to better support exceptions thrown.
137+
Any Firestore specific errors now return a `FirebaseException` (see Core changes), allowing you to directly access the code
138+
(e.g. permission-denied) and message.
139+
140+
- **`FirebaseFirestore`**:
141+
- **BREAKING**: Calling `settings()` now accepts a `Settings` instance.
142+
- **DEPRECATED**: Calling `document()` is deprecated in favor of `doc()`.
143+
- **DEPRECATED**: Calling `Firestore(app: app)` is now deprecated. Use `FirebaseFirestore.instance` or `FirebaseFirestore.instanceFor` instead.
144+
- **BREAKING**: `enablePersistence` has now been removed, see `settings()` instead.
145+
- **NEW**: Add `clearPersistence()` support.
146+
- **NEW**: Add `disableNetwork()` support.
147+
- **NEW**: Add `enableNetwork()` support.
148+
- **NEW**: Add `snapshotInSync()` support.
149+
- **NEW**: Add `terminate()` support.
150+
- **NEW**: Add `waitForPendingWrites()` support.
151+
152+
- **`CollectionReference`**:
153+
- **BREAKING**: Getting a collection parent document via `parent()` has been changed to a getter `parent`.
154+
- **DEPRECATED**: Calling `document()` is deprecated in favor of `doc()`.
155+
156+
- **`Query`**:
157+
- **BREAKING**: The internal query logic has been overhauled to better assert invalid queries locally.
158+
- **BREAKING**: `getDocuments`/`get` has been updated to accept an instance of `GetOptions` (see below).
159+
- **DEPRECATED**: Calling `getDocuments()` is deprecated in favor of `get()`.
160+
- **NEW**: Query methods are now chainable.
161+
- **NEW**: It is now possible to call same-point cursor based queries without throwing (e.g. calling `endAt()` and then `endBefore()` will replace the "end" cursor query with the `endBefore`).
162+
- **NEW**: Added support for `limitToLast`.
163+
164+
- **`QuerySnapshot`**:
165+
- **DEPRECATED**: `documents` has been deprecated in favor of `docs`.
166+
- **DEPRECATED**: `documentChanges` has been deprecated in favor of `docChanges`.
167+
- **NEW**: `docs` now returns a `List<QueryDocumentSnapshot>` vs `List<DocumentSnapshot>`. This doesn't break existing functionality.
168+
169+
- **`DocumentReference`**:
170+
- **BREAKING**: `setData`/`set` has been updated to accept an instance of `SetOptions` (see below, supports `mergeFields`).
171+
- **BREAKING**: `get()` has been updated to accept an instance of `GetOptions` (see below).
172+
- **BREAKING**: Getting a document parent collection via `parent()` has been changed to a getter `parent`.
173+
- **DEPRECATED**: `documentID` has been deprecated in favor of `id`.
174+
- **DEPRECATED**: `setData()` has been deprecated in favor of `set()`.
175+
- **DEPRECATED**: `updateData()` has been deprecated in favor of `update()`.
176+
177+
- **`DocumentSnapshot`**:
178+
- **BREAKING**: Getting a snapshots data via the `data` getter is now done via the `data()` method.
179+
- **DEPRECATED**: `documentID` has been deprecated in favor of `id`.
180+
- **NEW**: Added support for fetching nested snapshot data via the `get()` method. If no data exists at the given path, a `StateError` will be thrown.
181+
182+
- **`DocumentChange`**:
183+
- **DEPRECATED**: Calling `document()` is deprecated in favor of `doc()`.
184+
185+
- **`WriteBatch`**:
186+
- **BREAKING**: `setData`/`set` now supports `SetOptions` to merge data/fields (previously this accepted a `Map`).
187+
- **DEPRECATED**: `setData()` has been deprecated in favor of `set()`.
188+
- **DEPRECATED**: `updateData()` has been deprecated in favor of `update()`.
189+
190+
- **`Transaction`**:
191+
- **BREAKING**: Transactions have been overhauled to address a number of issues:
192+
- Values returned from the transaction will now be returned from the Future. Previously, only primitive values (e.g. `String`) were supported. It is now possible to return values such as a `DataSnapshot`.
193+
- When manually throwing an exception, the context was lost and a generic `PlatformException` was thrown. You can now throw & catch on any exceptions.
194+
- The modify methods on a transaction (`set`, `delete`, `update`) were previously Futures. This has been updated to better reflect how transactions should behave - they are now synchronous and are executed atomically once the transaction handler block has finished executing.
195+
196+
- **`FieldPath`**:
197+
- **NEW**: The constructor has now been made public to accept a `List` of `String` values. Previously field paths were accessible only via a dot-notated string path. This meant attempting to access a field in a document with a `.` in the name (e.g. `[email protected]`) was impossible.
198+
199+
- **`GetOptions`**: New class created to support how data is fetched from Firestore (server, cache, serverAndCache).
200+
201+
- **`SetOptions`**: New class created to both `merge` and `mergeFields` when setting data on documents.
202+
203+
- **`GeoPoint`**:
204+
- **BREAKING**: Added latitude and longitude validation when constructing a new `GeoPoint` instance.
205+
206+
### Authentication
207+
208+
Overall, Firebase Auth has been heavily reworked to bring it inline with the federated plugin setup along with adding new features, documentation and many more unit and end-to-end tests.
209+
The API has mainly been kept the same, however there are some breaking changes.
210+
211+
- **General**:
212+
- **BREAKING**: The `FirebaseUser` class has been renamed to `User`.
213+
- **BREAKING**: The `AuthResult` class has been renamed to `UserCredential`.
214+
- **NEW**: The `ActionCodeSettings` class is now consumable on all supporting methods.
215+
- **NEW**: Added support for the `dynamicLinkDomain` property.
216+
- **NEW**: Added a new `FirebaseAuthException` class (extends `FirebaseException`).
217+
- All errors are now returned as a `FirebaseAuthException`, allowing you to access the code & message associated with the error.
218+
- In addition, it is now possible to access the `email` and `credential` properties on exceptions if they exist.
219+
220+
- **`FirebaseAuth`**
221+
- **BREAKING**: Accessing the current user via `currentUser()` is now synchronous via the `currentUser` getter.
222+
- **BREAKING**: `isSignInWithEmailLink()` is now synchronous.
223+
- **DEPRECATED**: `FirebaseAuth.fromApp()` is now deprecated in favor of `FirebaseAuth.instanceFor()`.
224+
- **DEPRECATED**: `onAuthStateChanged` has been deprecated in favor of `authStateChanges()`.
225+
- **NEW**: Added support for `idTokenChanges()` stream listener.
226+
- **NEW**: Added support for `userChanges()` stream listener.
227+
- The purpose of this API is to allow users to subscribe to all user events without having to manually hydrate app state in cases where a manual reload was required (e.g. `updateProfile()`).
228+
- **NEW**: Added support for `applyActionCode()`.
229+
- **NEW**: Added support for `checkActionCode()`.
230+
- **NEW**: Added support for `verifyPasswordResetCode()`.
231+
- **NEW**: Added support for accessing the current language code via the `languageCode` getter.
232+
- **NEW**: `setLanguageCode()` now supports providing a `null` value.
233+
- On web platforms, if `null` is provided the Firebase projects default language will be set.
234+
- On native platforms, if `null` is provided the device language will be used.
235+
- **NEW**: `verifyPhoneNumber()` exposes a `autoRetrievedSmsCodeForTesting` property.
236+
- This allows developers to test automatic SMS code resolution on Android devices during development.
237+
- **NEW** (iOS): `appVerificationDisabledForTesting` setting can now be set for iOS.
238+
- This allows developers to skip ReCaptcha verification when testing phone authentication.
239+
- **NEW** (iOS): `userAccessGroup` setting can now be set for iOS & MacOS.
240+
- This allows developers to share authentication states across multiple apps or extensions on iOS & MacOS. For more information see the [Firebase iOS SDK documentation](https://firebase.google.com/docs/auth/ios/single-sign-on).
241+
242+
- **`User`**
243+
- **BREAKING**: Removed the `UpdateUserInfo` class when using `updateProfile` in favor of named arguments.
244+
- **NEW**: Added support for `getIdTokenResult()`.
245+
- **NEW**: Added support for `verifyBeforeUpdateEmail()`.
246+
- **FIX**: Fixed several iOS crashes when the Firebase SDK returned `nil` property values.
247+
- **FIX**: Fixed an issue on Web & iOS where a users email address would still show after unlinking the email/password provider.
248+
249+
- **`UserCredential`**
250+
- **NEW**: Added support for accessing the users `AuthCredential` via the `credential` property.
251+
252+
- **`AuthProvider`** & **`AuthCredential`**
253+
- **DEPRECATED**: All sub-class (e.g. `GoogleAuthProvider`) `getCredential()` methods have been deprecated in favor of `credential()`.
254+
- **DEPRECATED**: `EmailAuthProvider.getCredentialWithLink()` has been deprecated in favor of `EmailAuthProvider.credentialWithLink()`.
255+
- **NEW**: Supporting providers can now assign scope and custom request parameters.
256+
- The scope and parameters will be used on web platforms when triggering a redirect or popup via `signInWithPopup()` or `signInWithRedirect()`.

‎docs/sidebars.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ module.exports = {
1313
"installation/android",
1414
"installation/ios",
1515
"installation/web",
16+
"migration",
1617
],
1718
// AdMob: ["admob/usage", toReferenceAPI("firebase_admob")],
1819
Analytics: ["analytics/overview", toReferenceAPI("firebase_analytics")],

0 commit comments

Comments
 (0)