Skip to content

Commit 2ab8177

Browse files
SpomkySpomky
committed
Add workshop documentation for building Progressive Web Apps with Symfony
1 parent e5f6dc2 commit 2ab8177

File tree

1 file changed

+338
-0
lines changed

1 file changed

+338
-0
lines changed

‎WORKSHOP.md‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
# PWA Workshop: Building Progressive Web Apps with Symfony
2+
3+
## Workshop Overview
4+
5+
This full-day workshop focuses on transforming the FieldLog application into a fully-featured Progressive Web App (PWA) using the Spomky-Labs/PWA-Bundle for Symfony.
6+
7+
**Duration**: 6-8 hours (1 full day)
8+
**Level**: Intermediate
9+
**Prerequisites**: Basic knowledge of Symfony, JavaScript, and web development
10+
11+
## Learning Objectives
12+
13+
By the end of this workshop, participants will:
14+
- Understand PWA core concepts and architecture
15+
- Install and configure the Spomky-Labs/PWA-Bundle
16+
- Create a complete Web App Manifest
17+
- Implement Service Workers with multiple caching strategies
18+
- Enable offline functionality
19+
- Implement Background Sync for offline content creation
20+
- Configure Push Notifications
21+
- Integrate system-level features (Share Target, Web Share, Badging)
22+
- Optimize PWA performance and achieve high Lighthouse scores
23+
24+
---
25+
26+
## Morning Session: PWA Foundations (3-4 hours)
27+
28+
### 1. Introduction & Setup (30 minutes)
29+
30+
**Topics Covered:**
31+
- What is a Progressive Web App?
32+
- Benefits of PWAs vs Native Apps
33+
- PWA Requirements (HTTPS, Service Worker, Manifest)
34+
- Introduction to Spomky-Labs/PWA-Bundle
35+
36+
**Hands-on:**
37+
- Install the bundle: `composer require spomky-labs/pwa-bundle`
38+
- Initial configuration in `config/packages/pwa.yaml`
39+
- Explore bundle structure and documentation
40+
41+
### 2. Web App Manifest (1 hour)
42+
43+
**Topics Covered:**
44+
- Manifest.json structure and purpose
45+
- App metadata configuration
46+
- Display modes (standalone, fullscreen, minimal-ui, browser)
47+
- Color theming (theme_color, background_color)
48+
- Icons and maskable icons
49+
- Installability criteria
50+
51+
**Hands-on:**
52+
- Configure app metadata (name, short_name, description)
53+
- Create app icons in multiple sizes (192x192, 512x512)
54+
- Generate maskable icons for Android
55+
- Set theme and background colors
56+
- Configure start_url and scope
57+
- Test installability on mobile and desktop devices
58+
59+
**Deliverables:**
60+
- Complete manifest.json file
61+
- Icon set in appropriate sizes
62+
- Installable app on at least one device
63+
64+
### 3. Service Worker Basics (1.5 hours)
65+
66+
**Topics Covered:**
67+
- Service Worker lifecycle (install, activate, fetch)
68+
- Service Worker scope and registration
69+
- Cache API fundamentals
70+
- Caching strategies:
71+
- Cache-First (for static assets)
72+
- Network-First (for dynamic content)
73+
- Stale-While-Revalidate (for frequently updated content)
74+
- Network-Only, Cache-Only
75+
- Precaching critical resources
76+
77+
**Hands-on:**
78+
- Configure Service Worker via the bundle
79+
- Implement Cache-First strategy for static assets
80+
- Implement Network-First strategy for API calls
81+
- Precache essential assets (CSS, JS, fonts)
82+
- Debug Service Worker using DevTools
83+
- Test cache behavior and updates
84+
85+
**Deliverables:**
86+
- Working Service Worker with multiple strategies
87+
- Precached essential assets
88+
- Understanding of SW lifecycle
89+
90+
### 4. Basic Offline Mode (1 hour)
91+
92+
**Topics Covered:**
93+
- Offline detection strategies
94+
- Fallback pages and resources
95+
- Offline UX best practices
96+
- Informing users about connectivity status
97+
98+
**Hands-on:**
99+
- Create an offline fallback page
100+
- Implement network status detection
101+
- Cache previously viewed entries for offline access
102+
- Display offline indicator in the UI
103+
- Test complete offline experience
104+
105+
**Deliverables:**
106+
- Offline fallback page
107+
- Network status indicator
108+
- Cached content accessible offline
109+
110+
---
111+
112+
## Afternoon Session: Advanced PWA Features (3-4 hours)
113+
114+
### 5. Background Synchronization (1.5 hours)
115+
116+
**Topics Covered:**
117+
- Background Sync API overview
118+
- Use cases for Background Sync
119+
- Implementing sync queues
120+
- Handling sync failures
121+
- User feedback during sync
122+
123+
**Hands-on (Perfect for FieldLog):**
124+
- Implement offline entry creation
125+
- Queue entries when offline
126+
- Sync entries automatically when online
127+
- Display sync status to users
128+
- Handle sync errors gracefully
129+
- Notify users after successful sync
130+
131+
**Deliverables:**
132+
- Working Background Sync for entry creation
133+
- Sync queue management
134+
- User notifications after sync
135+
136+
### 6. Push Notifications (1 hour)
137+
138+
**Topics Covered:**
139+
- Push Notifications architecture
140+
- VAPID keys and subscription
141+
- Permission management
142+
- Notification best practices
143+
- Integration with Symfony Notifier
144+
145+
**Hands-on:**
146+
- Generate VAPID keys
147+
- Request notification permissions
148+
- Subscribe users to push notifications
149+
- Send notifications from server (Symfony Notifier)
150+
- Handle notification clicks and actions
151+
- Implement daily reminder notification
152+
153+
**Deliverables:**
154+
- Working push notification system
155+
- User subscription management
156+
- Server-side notification sending
157+
158+
### 7. System Integration Features (1 hour)
159+
160+
**Topics Covered:**
161+
- Share Target API (receive shared content)
162+
- Web Share API (share from your app)
163+
- File Handling API
164+
- Badging API
165+
- App shortcuts
166+
167+
**Hands-on (FieldLog-specific):**
168+
- Configure Share Target to receive text and files
169+
- Create controller to handle shared content
170+
- Implement Web Share to share entries
171+
- Add app shortcuts for different entry types
172+
- Implement badge counter for new items
173+
174+
**Configuration Examples:**
175+
```json
176+
"share_target": {
177+
"action": "/entry/new",
178+
"method": "POST",
179+
"enctype": "multipart/form-data",
180+
"params": {
181+
"title": "title",
182+
"text": "content",
183+
"files": [{
184+
"name": "file",
185+
"accept": ["image/*", "application/pdf"]
186+
}]
187+
}
188+
}
189+
190+
"shortcuts": [
191+
{
192+
"name": "New Text Entry",
193+
"url": "/entry/new?type=text",
194+
"icons": [{"src": "/icons/text.png", "sizes": "192x192"}]
195+
}
196+
]
197+
```
198+
199+
**Deliverables:**
200+
- Share Target receiving content from other apps
201+
- Web Share functionality
202+
- App shortcuts configured
203+
- Badge API integration
204+
205+
### 8. Optimization & Best Practices (30 minutes)
206+
207+
**Topics Covered:**
208+
- App Shell pattern
209+
- Lazy loading strategies
210+
- Resource preloading
211+
- Lighthouse PWA audit
212+
- Performance optimization
213+
- Accessibility considerations
214+
- Progressive enhancement approach
215+
216+
**Hands-on:**
217+
- Run Lighthouse audit
218+
- Optimize asset loading
219+
- Implement lazy loading for images
220+
- Preload critical resources
221+
- Fix Lighthouse warnings
222+
- Aim for 90+ PWA score
223+
224+
**Deliverables:**
225+
- Lighthouse PWA score > 90
226+
- Optimized loading performance
227+
- Accessible PWA
228+
229+
---
230+
231+
## Practical Challenges
232+
233+
Throughout the workshop, participants will complete these challenges:
234+
235+
1. **Challenge 1**: Make the app fully functional offline (reading and creating entries)
236+
2. **Challenge 2**: Implement Share Target to receive shared content
237+
3. **Challenge 3**: Create a daily reminder push notification
238+
4. **Challenge 4**: Achieve 100/100 on Lighthouse PWA audit
239+
5. **Challenge 5**: Successfully install and test on Android, iOS, and Desktop
240+
241+
---
242+
243+
## Technical Requirements
244+
245+
### For Participants:
246+
- Laptop with Docker and Docker Compose
247+
- Modern browser (Chrome/Edge recommended for DevTools)
248+
- Text editor/IDE
249+
- Mobile device for testing (optional but recommended)
250+
- Basic terminal/command line knowledge
251+
252+
### For the Application:
253+
- Symfony 7.3+
254+
- PHP 8.2+
255+
- HTTPS (required for PWA features)
256+
- Modern browser with PWA support
257+
258+
---
259+
260+
## Expected Outcomes
261+
262+
By the end of the workshop, FieldLog will:
263+
- Be installable as a standalone app on mobile and desktop
264+
- Function completely offline (viewing and creating entries)
265+
- Receive shared content from other applications
266+
- Send push notifications to users
267+
- Have a Lighthouse PWA score > 90
268+
- Use Service Worker with multiple caching strategies
269+
- Handle background synchronization
270+
- Integrate with system-level APIs
271+
272+
---
273+
274+
## File Structure (Post-Workshop)
275+
276+
```
277+
config/
278+
└── packages/
279+
└── pwa.yaml # PWA Bundle configuration
280+
281+
public/
282+
├── manifest.json # Generated Web App Manifest
283+
├── serviceworker.js # Generated Service Worker
284+
└── icons/ # App icons
285+
├── icon-192.png
286+
├── icon-512.png
287+
└── icon-maskable.png
288+
289+
assets/
290+
└── pwa/ # Custom PWA scripts
291+
├── install-prompt.js # Installation flow
292+
├── update-checker.js # SW update detection
293+
├── offline-handler.js # Offline state management
294+
└── sync-manager.js # Background sync logic
295+
296+
templates/
297+
└── pwa/
298+
└── offline.html.twig # Offline fallback page
299+
300+
src/
301+
└── Controller/
302+
└── ShareTargetController.php # Handle shared content
303+
```
304+
305+
---
306+
307+
## Key Concepts Summary
308+
309+
- **Progressive Enhancement**: App works for everyone, enhanced for capable browsers
310+
- **Service Worker**: JavaScript proxy between app and network
311+
- **Manifest**: JSON file describing app metadata and appearance
312+
- **Offline-First**: Design pattern prioritizing offline functionality
313+
- **Background Sync**: Defer actions until connectivity is restored
314+
- **Push Notifications**: Re-engage users with timely updates
315+
- **Share Target**: Make your app a destination for shared content
316+
317+
---
318+
319+
## Resources & References
320+
321+
- [Spomky-Labs/PWA-Bundle Documentation](https://github.com/Spomky-Labs/pwa-bundle)
322+
- [MDN PWA Guide](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)
323+
- [Web.dev PWA](https://web.dev/progressive-web-apps/)
324+
- [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
325+
- [Workbox (Google's SW Library)](https://developers.google.com/web/tools/workbox)
326+
- [PWA Builder](https://www.pwabuilder.com/)
327+
328+
---
329+
330+
## Post-Workshop
331+
332+
After completing this workshop, consider exploring:
333+
- **IndexedDB** for complex offline data storage
334+
- **Web Workers** for background computations
335+
- **WebRTC** for peer-to-peer communication
336+
- **WebAssembly** for performance-critical features
337+
- **Advanced caching strategies** with Workbox
338+
- **App Store deployment** (Microsoft Store, Google Play)

0 commit comments

Comments
 (0)