Skip to content

Commit 110f1ce

Browse files
h7mlh7ml
committed
docs: add PHP Laravel API documentation
- Add guide/api-php.md: Laravel 11 backend API with JWT, RBAC - Add en/guide/api-php.md: English version - Update sidebar.ts with PHP Laravel link in Backend Services
1 parent 2019b02 commit 110f1ce

3 files changed

Lines changed: 528 additions & 0 deletions

File tree

‎.vitepress/sidebar.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ const zhGuideSidebar: DefaultTheme.SidebarItem[] = [
4040
{ text: '🐍 Python FastAPI', link: '/guide/api-python' },
4141
{ text: '☕ Java Spring Boot', link: '/guide/api-java' },
4242
{ text: '🍞 Bun + Hono', link: '/guide/api-bun' },
43+
{ text: '🐘 PHP Laravel', link: '/guide/api-php' },
4344
{ text: '🔗 tRPC BFF', link: '/guide/bff' },
4445
{ text: '🛠️ 超级管理面板', link: '/guide/admin' },
4546
],
@@ -130,6 +131,7 @@ const enGuideSidebar: DefaultTheme.SidebarItem[] = [
130131
{ text: '🐍 Python FastAPI', link: '/en/guide/api-python' },
131132
{ text: '☕ Java Spring Boot', link: '/en/guide/api-java' },
132133
{ text: '🍞 Bun + Hono', link: '/en/guide/api-bun' },
134+
{ text: '🐘 PHP Laravel', link: '/en/guide/api-php' },
133135
{ text: '🔗 tRPC BFF', link: '/en/guide/bff' },
134136
{ text: '🛠️ Admin Panel', link: '/en/guide/admin' },
135137
],

‎en/guide/api-php.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# PHP Laravel API
2+
3+
HaloLight PHP enterprise-grade backend API service, built with Laravel 11 + PostgreSQL + Redis, providing a complete RESTful API.
4+
5+
**GitHub**: [https://github.com/halolight/halolight-api-php](https://github.com/halolight/halolight-api-php)
6+
7+
## Tech Stack
8+
9+
| Technology | Version | Description |
10+
|------------|---------|-------------|
11+
| Laravel | 11.x | PHP full-stack framework |
12+
| PHP | 8.2+ | Runtime |
13+
| PostgreSQL | 16 | Relational database |
14+
| Redis | 7 | Cache/Queue |
15+
| JWT | tymon/jwt-auth | Dual token authentication |
16+
| RBAC | spatie/laravel-permission | Permission management |
17+
| Swagger | L5-Swagger | OpenAPI 3.0 documentation |
18+
| Docker | latest | Containerized deployment |
19+
20+
## Core Features
21+
22+
- **JWT Dual Token Auth**: Based on tymon/jwt-auth, supports auto-refresh and blacklist
23+
- **RBAC Permission System**: Using spatie/laravel-permission, supports role inheritance
24+
- **High-Performance Cache**: Redis-driven Session, Cache, Queue
25+
- **Swagger Documentation**: Complete OpenAPI 3.0 interactive documentation
26+
- **Docker Deployment**: Nginx + PHP-FPM + Supervisor multi-process architecture
27+
- **Complete Testing**: PHPUnit unit and feature tests
28+
- **Code Quality**: PHPStan + Laravel Pint ensures code quality
29+
30+
## Directory Structure
31+
32+
```
33+
halolight-api-php/
34+
├── app/
35+
│ ├── Http/
36+
│ │ ├── Controllers/
37+
│ │ │ ├── Controller.php # Base controller
38+
│ │ │ ├── HomeController.php # Homepage and health check
39+
│ │ │ └── Api/V1/ # API controllers (12 modules)
40+
│ │ │ ├── AuthController.php
41+
│ │ │ ├── UserController.php
42+
│ │ │ ├── RoleController.php
43+
│ │ │ └── ...
44+
│ │ ├── Middleware/
45+
│ │ │ ├── ForceJsonResponse.php # Force JSON response
46+
│ │ │ ├── JwtAuthenticate.php # JWT authentication
47+
│ │ │ └── CheckPermission.php # Permission check
48+
│ │ └── Requests/ # Form validation requests
49+
│ ├── Services/ # Business logic layer
50+
│ ├── Models/ # Data models (17+ models)
51+
│ ├── Enums/ # Enum types
52+
│ └── Providers/
53+
├── config/ # Configuration files
54+
├── routes/
55+
│ ├── web.php # Web routes
56+
│ └── api.php # API routes
57+
├── tests/
58+
│ ├── Unit/ # Unit tests
59+
│ └── Feature/ # Feature tests
60+
├── docker-compose.yml
61+
├── Dockerfile
62+
└── composer.json
63+
```
64+
65+
## Quick Start
66+
67+
### Prerequisites
68+
69+
- PHP 8.2+
70+
- Composer
71+
- PostgreSQL 16
72+
- Redis 7
73+
- Docker (optional)
74+
75+
### Local Development
76+
77+
```bash
78+
# Clone project
79+
git clone https://github.com/halolight/halolight-api-php.git
80+
cd halolight-api-php
81+
82+
# Install dependencies
83+
composer install
84+
85+
# Configure environment variables
86+
cp .env.example .env
87+
php artisan key:generate
88+
89+
# Run migrations
90+
php artisan migrate
91+
92+
# Seed data (optional)
93+
php artisan db:seed
94+
95+
# Start server
96+
php artisan serve --port=8080
97+
```
98+
99+
Access:
100+
- **Homepage**: http://localhost:8080
101+
- **Health Check**: http://localhost:8080/health
102+
- **Swagger Docs**: http://localhost:8080/docs
103+
104+
### Docker Deployment
105+
106+
```bash
107+
# Configure environment variables
108+
cp .env.example .env
109+
110+
# Start all services
111+
docker-compose up -d
112+
113+
# View logs
114+
docker-compose logs -f app
115+
```
116+
117+
Access: http://localhost:8000
118+
119+
## API Modules
120+
121+
| Module | Endpoints | Description |
122+
|--------|-----------|-------------|
123+
| Auth | 7 | Login, register, refresh, logout, password management |
124+
| Users | 7 | User CRUD, status management |
125+
| Roles | 6 | Role management, permission assignment |
126+
| Permissions | 4 | Permission management |
127+
| Teams | 7 | Team management, member management |
128+
| Documents | 9 | Document CRUD, sharing |
129+
| Files | 9 | File upload, download, management |
130+
| Folders | 5 | Folder tree management |
131+
| Calendar | 8 | Calendar events, attendees |
132+
| Notifications | 5 | Notification management |
133+
| Messages | 5 | Conversations, messages |
134+
| Dashboard | 9 | Statistics data |
135+
136+
## Authentication
137+
138+
### JWT Dual Token Auth
139+
140+
```bash
141+
# Login
142+
curl -X POST http://localhost:8080/api/auth/login \
143+
-H "Content-Type: application/json" \
144+
-d '{"email":"demo@halolight.com","password":"password123"}'
145+
146+
# Response
147+
{
148+
"accessToken": "eyJ...", // 7 days valid
149+
"refreshToken": "eyJ...", // 30 days valid
150+
"user": { ... }
151+
}
152+
153+
# Use Token to access protected endpoints
154+
curl -X GET http://localhost:8080/api/users \
155+
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
156+
```
157+
158+
### Refresh Token
159+
160+
```bash
161+
POST /api/auth/refresh
162+
{ "refreshToken": "eyJ..." }
163+
```
164+
165+
## Environment Variables
166+
167+
```env
168+
# Application config
169+
APP_ENV=production
170+
APP_KEY=base64:...
171+
APP_DEBUG=false
172+
APP_URL=http://localhost:8080
173+
174+
# Database
175+
DB_CONNECTION=pgsql
176+
DB_HOST=localhost
177+
DB_PORT=5432
178+
DB_DATABASE=halolight
179+
DB_USERNAME=postgres
180+
DB_PASSWORD=your_password
181+
182+
# Redis
183+
REDIS_HOST=localhost
184+
REDIS_PORT=6379
185+
REDIS_PASSWORD=your_redis_password
186+
CACHE_DRIVER=redis
187+
SESSION_DRIVER=redis
188+
189+
# JWT config
190+
JWT_SECRET=your-super-secret-key-min-32-chars
191+
JWT_TTL=10080 # minutes, 7 days
192+
193+
# CORS
194+
CORS_ALLOWED_ORIGINS=*
195+
```
196+
197+
## Common Commands
198+
199+
```bash
200+
# Development
201+
php artisan serve --port=8080 # Start development server
202+
203+
# Database
204+
php artisan migrate # Run migrations
205+
php artisan migrate:fresh --seed # Reset and seed data
206+
php artisan db:seed # Seed data
207+
208+
# Code quality
209+
composer lint # Code style check
210+
composer test # Run tests
211+
composer analyse # Static analysis
212+
213+
# Swagger docs
214+
php artisan l5-swagger:generate # Generate Swagger docs
215+
216+
# Docker
217+
docker-compose up -d # Start services
218+
docker-compose down # Stop services
219+
```
220+
221+
## Security Features
222+
223+
- JWT token authentication and auto-refresh
224+
- RBAC role-based permission control
225+
- CORS configuration
226+
- SQL injection protection (Eloquent ORM)
227+
- XSS protection (Laravel auto-escaping)
228+
- CSRF protection (API token mode)
229+
- Rate limiting (Laravel Throttle)
230+
- Password hashing (bcrypt)
231+
232+
## Deployment
233+
234+
### Fly.io
235+
236+
```bash
237+
# Install flyctl
238+
curl -L https://fly.io/install.sh | sh
239+
240+
# Login
241+
fly auth login
242+
243+
# Deploy
244+
fly launch
245+
246+
# Set environment variables
247+
fly secrets set \
248+
APP_KEY="base64:your-app-key" \
249+
JWT_SECRET="your-jwt-secret" \
250+
DB_HOST="your-db-host" \
251+
DB_PASSWORD="your-db-password"
252+
253+
# Deploy
254+
fly deploy
255+
```
256+
257+
## Related Projects
258+
259+
- [halolight-api-go](https://github.com/halolight/halolight-api-go) - Go API
260+
- [halolight-api-node](https://github.com/halolight/halolight-api-node) - Node.js API
261+
- [halolight-api-python](https://github.com/halolight/halolight-api-python) - Python API
262+
- [halolight](https://github.com/halolight/halolight) - Next.js frontend
263+
- [halolight-vue](https://github.com/halolight/halolight-vue) - Vue 3 frontend

0 commit comments

Comments
 (0)