Skip to content

Commit 200ece1

Browse files
author
Vojtech Smejkal
committed
[Notifier][Firebase] Update README and CHANGELOG
Reflects changes made by transferring to new v1 API.
1 parent f15fedf commit 200ece1

File tree

2 files changed

+159
-15
lines changed

2 files changed

+159
-15
lines changed

‎src/Symfony/Component/Notifier/Bridge/Firebase/CHANGELOG.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
CHANGELOG
22
=========
33

4+
7.3
5+
---
6+
7+
* Changed to using the new v1 Firebase API
8+
* [DEPRECATION] `AndroidNotification`, `IOSNotification` and `WebNotification` were deprecated and will be removed in 8.0, use `FirebaseOptions` instead. New Firebase API allows for all platform specific options to be specified for the message. Having options separated by platforms now limits usability.
9+
* [DEPRECATION] Using DSN for firebase in the old format `firebase://username:password@default` was deprecated, use the new DSN format and specify the required options instead. Not specifying the options will throw error in 8.0.
10+
* [DEPRECATION] `$token` param in `FirebaseTransport::__construct()` was marked as deprecated because the new Firebase API does not use standard token auth. The param will be removed in 8.0.
11+
412
5.3
513
---
614

‎src/Symfony/Component/Notifier/Bridge/Firebase/README.md

Lines changed: 151 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,32 +7,107 @@ DSN example
77
-----------
88

99
```
10-
FIREBASE_DSN=firebase://USERNAME:PASSWORD@default
10+
FIREBASE_DSN=firebase://<CLIENT_EMAIL>@default?project_id=<PROJECT_ID>&private_key_id=<PRIVATE_KEY_ID>&private_key=<PRIVATE_KEY>
11+
```
12+
13+
All 4 parameters are required. All 4 parameters are located inside your firebase json private key.
14+
15+
IMPORTANT: Make sure that `PRIVATE_KEY` is safely url encoded. Get more information in [Notifier documentation](https://symfony.com/doc/current/notifier.html#chat-channel) or use the script below.
16+
17+
18+
Getting credentials for your DSN
19+
--------------------------------
20+
21+
Steps for getting your private key:
22+
1. Log into the [firebase console](https://console.firebase.google.com/).
23+
2. Click on your project
24+
3. Click on the gear icon next to "Project Overview" and click on "Project settings"
25+
4. Click on "Service accounts" tab
26+
5. Click on "Generate new private key" button at the bottom
27+
6. A JSON file with your private key will be downloaded
28+
29+
The downloaded private key is a JSON file which should contain the following keys:
30+
* `type`
31+
* `project_id`
32+
* `private_key_id`
33+
* `private_key`
34+
* `client_email`
35+
* `client_id`
36+
* `auth_uri`
37+
* `token_uri`
38+
* `auth_provider_x509_cert_url`
39+
* `client_x509_cert_url`
40+
* `universe_domain`
41+
42+
You can then use the following script to convert your JSON private key to DSN format:
43+
44+
```php
45+
<?php
46+
47+
if (!isset($argv[1])) {
48+
echo 'Usage: php ' . $argv[0] . ' path_to_your_key.json'.PHP_EOL;
49+
exit(1);
50+
}
51+
52+
$file = file_get_contents($argv[1]);
53+
54+
if (false === $file) {
55+
echo 'Could not open file at path: '.$argv[1].PHP_EOL.PHP_EOL;
56+
exit(1);
57+
}
58+
59+
$key = json_decode($file, true);
60+
61+
if (false === $key) {
62+
echo 'Unable to load JSON content of the file at path: '.$argv[1].PHP_EOL;
63+
exit(1);
64+
}
65+
66+
foreach (['client_email', 'project_id', 'private_key_id', 'private_key'] as $param) {
67+
if (!isset($key[$param])) {
68+
echo 'Missing param '.$param.' inside the JSON key.'.PHP_EOL;
69+
exit(1);
70+
}
71+
}
72+
73+
echo sprintf(
74+
'FIREBASE_DSN=firebase://%s@default?project_id=%s&private_key_id=%s&private_key=%s',
75+
$key['client_email'],
76+
$key['project_id'],
77+
$key['private_key_id'],
78+
urlencode($key['private_key']),
79+
).PHP_EOL;
80+
```
81+
82+
The script then can be used as follows:
83+
```bash
84+
php script_name.php path/to/your/firebase/key.json
1185
```
1286

13-
where:
14-
- `USERNAME` is your Firebase username
15-
- `PASSWORD` is your Firebase password
1687

1788
Adding Interactions to a Message
1889
--------------------------------
1990

20-
With a Firebase message, you can use the `AndroidNotification`, `IOSNotification` or `WebNotification` classes to add
21-
[message options](https://firebase.google.com/docs/cloud-messaging/xmpp-server-ref.html).
91+
With a Firebase message, you can use the `FirebaseOptions` class to to add
92+
[platform specific message options](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#resource:-message).
93+
94+
Specifying Firebase options for a message:
2295

2396
```php
2497
use Symfony\Component\Notifier\Message\ChatMessage;
25-
use Symfony\Component\Notifier\Bridge\Firebase\Notification\AndroidNotification;
98+
use Symfony\Component\Notifier\Bridge\Firebase\FirebaseOptions;
2699

27-
$chatMessage = new ChatMessage('');
100+
$chatMessage = new ChatMessage('Hello, you should contribute to Symfony.');
28101

29-
// Create AndroidNotification options
30-
$androidOptions = (new AndroidNotification('/topics/news', []))
31-
->icon('myicon')
32-
->sound('default')
33-
->tag('myNotificationId')
34-
->color('#cccccc')
35-
->clickAction('OPEN_ACTIVITY_1')
102+
// Specify options for Firebase
103+
$firebaseOptions = (new FirebaseOptions('/topics/news', []))
104+
->title('New message!')
105+
->body('This will overwrite the subject from ChatMessage object.')
106+
->image('https://path-to-your-image.png')
107+
->data([
108+
'key1' => 'value1',
109+
'key2' => 'value2',
110+
])
36111
// ...
37112
;
38113

@@ -42,6 +117,67 @@ $chatMessage->options($androidOptions);
42117
$chatter->send($chatMessage);
43118
```
44119

120+
Firebase offers 3 different types of targets to send the message to:
121+
* token
122+
* topic
123+
* condition
124+
125+
How to specify different targets for firebase messages:
126+
127+
```php
128+
use Symfony\Component\Notifier\Bridge\Firebase\FirebaseOptions;
129+
use Symfony\Component\Notifier\Bridge\Firebase\TargetType;
130+
131+
// Use a topic as a target
132+
$topicOptions = new FirebaseOptions('/topics/news', [], [], TargetType::Topic);
133+
134+
// Use a token as a target
135+
$tokenOptions = new FirebaseOptions('dU5e3nFJf9bE:APA91bH3Kd/exampleToken', [], [], TargetType::Token);
136+
137+
// Use a condition as a target
138+
$conditionOptions = new FirebaseOptions('\'news\' in topics', [], [], TargetType::Condition);
139+
```
140+
141+
Firebase also allows specifying platform specific options. They can be specified as follows:
142+
143+
```php
144+
use Symfony\Component\Notifier\Bridge\Firebase\FirebaseOptions;
145+
use Symfony\Component\Notifier\Bridge\Firebase\TargetType;
146+
147+
$detailedOptions = (new FirebaseOptions('dU5e3nFJf9bE:APA91bH3Kd/exampleToken', [], [], TargetType::Token))
148+
// Basic options
149+
->title('New message!')
150+
->data([
151+
'key1' => 'value1',
152+
'key2' => 'value2',
153+
])
154+
// Android specific options
155+
->android([
156+
'notification' => [
157+
'color' => '#4538D5',
158+
],
159+
])
160+
// WebPush specific options
161+
->webpush([
162+
'notification' => [
163+
'icon' => 'https://path-to-an-icon.png',
164+
],
165+
])
166+
// APNS specific options
167+
->apns([
168+
'payload' => [
169+
'aps' => [
170+
'sound' => 'default',
171+
],
172+
],
173+
])
174+
// ...
175+
;
176+
```
177+
178+
For all available options please refer to the [firebase documentation](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages).
179+
180+
45181
Resources
46182
---------
47183

0 commit comments

Comments
 (0)