New Tutorials: File Upload & Google OAuth Authentication

[koriym]

Summary

This issue tracks the proposal for two new tutorials to enhance BEAR.Sunday documentation. These tutorials address common web development needs that are currently not covered.

Branch with planning documents: claude/collect-tutorial-ideas-sL4nN
Ideas document: docs/tutorial-ideas.md

---

Proposed Tutorials

1. File Upload Tutorial (tutorial-upload.md)

Library: Koriym.FileUpload

A three-part tutorial covering file upload implementation:

Part	Topic	Content
Part 1	Basics	Single file upload (profile image), validation, error handling
Part 2	Advanced	Multiple file upload, image gallery, delete functionality
Part 3	Extended	Various file types, download response, access control, testing

Key features:

• Type-safe file upload handling
• Built-in validation (size, MIME type, extensions)
• Union type pattern (FileUpload|ErrorFileUpload) with match expressions
• Integration with BEAR.Streamer for downloads

---

2. Google OAuth Authentication Tutorial (tutorial-auth.md)

Library: league/oauth2-google

A tutorial covering OAuth 2.0 authentication with Google:

Chapter	Topic
1-3	Project setup, Google Cloud Console configuration
4-6	Library installation, environment variables, DI configuration
7-9	Login/Callback/Logout resources, session management
10-12	Protected pages, testing, next steps

Design decisions:

• No password management (OAuth-only approach keeps it simple)
• PHP native sessions (simple wrapper, no additional dependencies)
• Simple session check for protected pages (AOP mentioned as advanced topic)

---

Other Tutorial Ideas (Future)

From docs/tutorial-ideas.md:

Priority	Tutorial	Target Audience
High	Full-stack Web App (forms, sessions, CSRF)	Beginners
Medium	Caching	Intermediate
Medium	Testing Practices	Intermediate
Low-Medium	Content Negotiation	Intermediate
Low-Medium	Swoole/Real-time	Advanced
Low	Microservices	Advanced
Low	GraphQL	Advanced

---

Quick Reference / Recipe Collection

A proposed addition to improve documentation discoverability:

Task	Reference
Pagination	database.md (Ray.MediaQuery)
Caching	cache.md
HTML output	html.md
Validation	validation.md
Testing	test.md
External API calls	database.md (Ray.MediaQuery)
Production deployment	production.md

---

Prerequisites

Both tutorials assume completion of Tutorial 1 only. They are independent of each other and can be completed in any order.

Next Steps

1. Implement tutorial-upload.md (Japanese)
2. Implement tutorial-auth.md (Japanese)
3. Update navigation (contents.html)
4. Translate to English (separate task)