Skip to content

Commit 3c784ba

Browse files
jeromegamezjeromegamez
committed
Add details to upgrade guide
1 parent 77637fa commit 3c784ba

1 file changed

Lines changed: 97 additions & 28 deletions

File tree

‎UPGRADE-8.0.md‎

Lines changed: 97 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
## Introduction
44

5-
This is a major release, but its aim is to provide as much backward compatibility as possible to ease upgrades
6-
from 7.x to 8.0.
5+
This is a major release, but its aim is to provide as much backward compatibility as possible to ease upgrades from 7.x to 8.0.
76

87
## Notable changes
98

10-
* The SDK supports only actively supported PHP versions. As a result, support for PHP < 8.3 has been dropped;
9+
* The SDK supports only actively supported PHP versions.
10+
As a result, support for PHP < 8.3 has been dropped;
1111
supported versions are 8.3, 8.4, and 8.5.
1212
* [Firebase Dynamic Links was shut down on August 25th, 2025](https://firebase.google.com/support/dynamic-links-faq)
1313
and has been removed from the SDK.
@@ -20,13 +20,31 @@ from 7.x to 8.0.
2020
Several argument types have been simplified to their most common forms to eliminate runtime type conversion overhead.
2121
For example, methods that previously accepted `Stringable|string` now only accept `string`.
2222

23-
The union types were originally added for convenience, but introduced overhead when processing arguments, requiring
24-
runtime type conversion and validation that could be replaced with static analysis.
23+
The union types were originally added for convenience,
24+
but introduced overhead when processing arguments,
25+
requiring runtime type conversion and validation that could be replaced with static analysis.
26+
27+
**Migration:**
28+
29+
If you were passing `Stringable` objects, extract/convert to the string value first:
30+
31+
```diff
32+
+use Kreait\Firebase\Auth\CreateUser;
33+
+
34+
$userRecord = $auth->createUser(
35+
- CreateUser::new()->withEmail($emailObject)
36+
+ CreateUser::new()->withEmail((string) $emailObject)
37+
);
38+
39+
-$user = $auth->getUser($userRecord);
40+
+$user = $auth->getUser($userRecord->uid);
41+
```
2542

2643
### Sensitive Parameter Protection
2744

28-
The SDK now leverages PHP 8.2+ `#[SensitiveParameter]` attributes to enhance security by preventing sensitive data
29-
from appearing in stack traces and error logs. This affects methods that handle:
45+
The SDK now leverages PHP 8.2+ `#[SensitiveParameter]` attributes to enhance security
46+
by preventing sensitive data from appearing in stack traces and error logs.
47+
This affects methods that handle:
3048

3149
- Passwords and authentication credentials
3250
- JWT tokens (ID tokens, refresh tokens, custom tokens)
@@ -36,44 +54,95 @@ from appearing in stack traces and error logs. This affects methods that handle:
3654
## Dependency Changes
3755

3856
### PSR Log Dependency
39-
`psr/log` is now a development dependency instead of a runtime dependency. This change reduces the production dependency footprint. If you were using PSR Log interfaces directly in your application code, you should add `psr/log` to your project's composer.json.
57+
58+
`psr/log` is now a development dependency instead of a runtime dependency.
59+
This change reduces the production dependency footprint.
60+
If you were using PSR Log interfaces directly in your application code,
61+
you should add `psr/log` to your project's composer.json.
4062

4163
### Removed Constants
42-
The `Kreait\Firebase\Contract\Messaging::BATCH_MESSAGE_LIMIT` constant has been removed. If you were using this constant in your code, you should define the limit (500) in your application or use the Firebase messaging service limits documentation as reference.
64+
65+
The `Kreait\Firebase\Contract\Messaging::BATCH_MESSAGE_LIMIT` constant has been removed.
66+
If you were using this constant in your code,
67+
you should define the limit (500) in your application or use the Firebase messaging service limits documentation as reference.
4368

4469
### Exception Handling Changes
45-
Exception codes are no longer preserved when wrapping exceptions. If your code relies on specific exception codes for error handling, you should update it to use exception types or messages instead.
4670

47-
### Cloud Message Builder Method Renames
71+
Exception codes are no longer preserved when wrapping exceptions.
72+
If your code relies on specific exception codes for error handling,
73+
you should update it to use exception types or messages instead.
4874

49-
The `CloudMessage` builder methods for setting message targets have been renamed to follow the `with*` naming pattern for consistency with other builder methods in the SDK:
75+
### Cloud Message Builder Method Renames
5076

51-
- `toToken()` -> `withToken()`
52-
- `toTopic()` -> `withTopic()`
53-
- `toCondition()` -> `withCondition()`
77+
The `CloudMessage` builder methods for setting message targets have been renamed
78+
to follow the `with*` naming pattern for consistency with other builder methods in the SDK.
5479

5580
**Migration:**
5681

57-
Replace the old method names with the new ones:
82+
```diff
83+
-$message = CloudMessage::new()
84+
- ->toToken('device-token')
85+
- ->withNotification(['title' => 'Hello']);
86+
+$message = CloudMessage::new()
87+
+ ->withToken('device-token')
88+
+ ->withNotification(['title' => 'Hello']);
89+
90+
-$message->toTopic('news');
91+
+$message->withTopic('news');
92+
93+
-$message->toCondition("'dogs' in topics");
94+
+$message->withCondition("'dogs' in topics");
95+
```
96+
97+
The old methods are still available as deprecated aliases,
98+
so your code will continue to work during the transition period.
99+
100+
### Removed Factory Methods
58101

59-
```php
60-
// Before (7.x)
61-
$message = CloudMessage::new()
62-
->toToken('device-token')
63-
->withNotification(['title' => 'Hello']);
102+
Several debugging and logging methods have been removed from the `Factory` class.
103+
104+
**Migration:**
64105

65-
// After (8.0)
66-
$message = CloudMessage::new()
67-
->withToken('device-token')
68-
->withNotification(['title' => 'Hello']);
106+
```diff
107+
-$factory = $factory->withHttpLogger($logger);
108+
-$factory = $factory->withHttpDebugLogger($logger);
109+
+// Use Guzzle middleware or your HTTP client's logging instead
110+
+// See: https://docs.guzzlephp.org/en/stable/handlers-and-middleware.html
111+
112+
-$debugInfo = $factory->getDebugInfo();
113+
+// No direct replacement - inspect services directly if needed
69114
```
70115

71-
The old methods are still available as deprecated aliases, so your code will continue to work during the transition period.
116+
The `withFirestoreDatabase()` method has also been removed as it was never fully implemented.
117+
118+
### Remote Config Value Objects
119+
120+
The `DefaultValue` and `ExplicitValue` classes have been removed and replaced with the unified `ParameterValue` class.
121+
122+
**Migration:**
123+
124+
```diff
125+
use Kreait\Firebase\RemoteConfig\Parameter;
126+
+use Kreait\Firebase\RemoteConfig\ParameterValue;
127+
128+
-$parameter = Parameter::named('feature_flag', DefaultValue::with('false'));
129+
+$parameter = Parameter::named('feature_flag', 'false');
130+
131+
-$value = $parameter->defaultValue();
132+
-if ($value instanceof DefaultValue) {
133+
- // Handle default
134+
-}
135+
+$value = $parameter->defaultValue();
136+
+if ($value instanceof ParameterValue) {
137+
+ $stringValue = $value->value();
138+
+}
139+
```
72140

73141
---
74142

75-
**See the complete list of breaking changes below** to identify any adjustments needed. Most changes should (hopefully)
76-
be trivial (e.g., passing `$user->uid` instead of `$user`). Run your test suite to catch any breaking changes.
143+
**See the complete list of breaking changes below** to identify any adjustments needed.
144+
Most changes should (hopefully) be trivial (e.g., passing `$user->uid` instead of `$user`).
145+
Run your test suite to catch any breaking changes.
77146

78147
## Complete list of breaking changes
79148

0 commit comments

Comments
 (0)