Skip to content

Commit 1d47421

Browse files
mcollinamcollina
committed
Added README
Signed-off-by: Matteo Collina <[email protected]>
1 parent ae084da commit 1d47421

File tree

3 files changed

+224
-4
lines changed

3 files changed

+224
-4
lines changed

‎CLAUDE.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is `@platformatic/php` - a PHP stackable for Watt that integrates PHP applications with the Platformatic framework. It enables serving PHP files through a Fastify server with proper request/response handling.
8+
9+
## Development Commands
10+
11+
- `npm test` - Run tests using Node.js built-in test runner
12+
- `npm run build` - Generate schema.json and config.d.ts from schema definitions
13+
- `npm run ci` - Run linting and tests (assumes lint script exists)
14+
- `npm run dl-wordpress` - Download WordPress for testing/development
15+
16+
## Architecture
17+
18+
The project follows Platformatic's stackable pattern:
19+
20+
### Core Components
21+
22+
- **lib/index.js** - Main stackable export with configuration and plugin registration
23+
- **lib/plugin.js** - Fastify plugin that handles PHP request routing and execution
24+
- **lib/generator.js** - Code generator for creating new PHP stackable projects
25+
- **lib/schema.js** - JSON schema definitions for configuration validation
26+
27+
### Key Architecture Patterns
28+
29+
1. **Stackable Integration**: Extends `@platformatic/service` with PHP-specific functionality
30+
2. **Request Handling**: All HTTP methods are captured by wildcard routes and forwarded to PHP via `@platformatic/php-node`
31+
3. **Static File Serving**: Non-PHP files in docroot are served statically with `@fastify/static`
32+
4. **Header Processing**: HTTP headers are capitalized for PHP compatibility
33+
5. **Configuration Schema**: Uses JSON schema with automatic TypeScript generation
34+
35+
### Generated Project Structure
36+
37+
When using the generator, projects include:
38+
- `public/` directory as PHP docroot with `index.php`
39+
- `platformatic.json` configuration file
40+
- `.env` and `.env.sample` for environment variables
41+
- Node.js v22.14.0+ requirement
42+
43+
### Testing Approach
44+
45+
- Uses Node.js built-in test runner (`node --test`)
46+
- Tests cover generator functionality, configuration validation, and file generation
47+
- Test fixtures in `test/fixtures/` for integration testing

‎README.md‎

Lines changed: 175 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,175 @@
1-
# php
2-
PHP stackable for Watt
1+
# @platformatic/php
2+
3+
A PHP stackable for [Platformatic](https://platformatic.dev/) that enables running PHP applications within the Platformatic ecosystem. This package integrates PHP execution with Fastify servers, allowing you to serve PHP files alongside Node.js applications.
4+
5+
## Features
6+
7+
- 🚀 Run PHP applications within Platformatic services
8+
- 🔄 Automatic request/response handling between Node.js and PHP
9+
- 📁 Static file serving for non-PHP assets
10+
- ⚡ Hot reloading during development
11+
- 🛠️ Code generation for new PHP projects
12+
- 🔧 Environment-based configuration
13+
14+
## Requirements
15+
16+
- Node.js >= 22.14.0
17+
- The PHP runtime is built thanks to [`@platformatic/php-node`](https://github.com/platformatic/php-node).
18+
19+
## Installation
20+
21+
```bash
22+
npm install @platformatic/php
23+
```
24+
25+
## Quick Start
26+
27+
### Create a New PHP Project
28+
29+
```bash
30+
npx --package=@platformatic/php create-platformatic-php --dir my-php-app --port 3042
31+
cd my-php-app
32+
npm install
33+
npm start
34+
```
35+
36+
### CLI Options
37+
38+
- `--dir` - Target directory (default: `plt-php`)
39+
- `--port` - Server port (default: `3042`)
40+
- `--hostname` - Server hostname (default: `0.0.0.0`)
41+
- `--main` - Main PHP file (default: `index.php`)
42+
43+
## Configuration
44+
45+
The stackable uses a `platformatic.json` configuration file:
46+
47+
```json
48+
{
49+
"$schema": "https://schemas.platformatic.dev/@platformatic/php/0.4.3.json",
50+
"module": "@platformatic/php",
51+
"php": {
52+
"docroot": "public"
53+
},
54+
"server": {
55+
"hostname": "{PLT_SERVER_HOSTNAME}",
56+
"port": "{PORT}",
57+
"logger": { "level": "{PLT_SERVER_LOGGER_LEVEL}" }
58+
},
59+
"watch": true
60+
}
61+
```
62+
63+
### Configuration Options
64+
65+
#### php
66+
- `docroot` (string, required) - Path to the root directory containing PHP files
67+
68+
#### server
69+
Standard Platformatic server configuration options are supported.
70+
71+
## Project Structure
72+
73+
A generated PHP project includes:
74+
75+
```
76+
my-php-app/
77+
├── public/
78+
│ └── index.php # Main PHP file
79+
├── .env # Environment variables
80+
├── .env.sample # Environment template
81+
├── .gitignore
82+
├── package.json
83+
└── platformatic.json # Platformatic configuration
84+
```
85+
86+
## Development
87+
88+
### Available Scripts
89+
90+
- `npm start` - Start the development server
91+
- `npm test` - Run tests
92+
- `npm run build` - Build schema and types
93+
94+
### Environment Variables
95+
96+
- `PLT_SERVER_HOSTNAME` - Server hostname (default: `0.0.0.0`)
97+
- `PORT` - Server port (default: `3042`)
98+
- `PLT_SERVER_LOGGER_LEVEL` - Log level (default: `info`)
99+
100+
## How It Works
101+
102+
1. **Request Routing**: All HTTP requests are captured by wildcard routes
103+
2. **PHP Execution**: Requests are forwarded to PHP via `@platformatic/php-node`
104+
3. **Static Files**: Non-PHP files in the docroot are served statically
105+
4. **Response Handling**: PHP responses are processed and returned through Fastify
106+
107+
## API
108+
109+
### Stackable Export
110+
111+
```javascript
112+
import { stackable } from '@platformatic/php'
113+
// or
114+
import php from '@platformatic/php'
115+
```
116+
117+
### Generator
118+
119+
```javascript
120+
import { Generator } from '@platformatic/php'
121+
122+
const generator = new Generator()
123+
generator.setConfig({
124+
targetDirectory: './my-app',
125+
port: 3042,
126+
hostname: '0.0.0.0'
127+
})
128+
await generator.run()
129+
```
130+
131+
## Examples
132+
133+
### Basic PHP Application
134+
135+
```php
136+
<?php
137+
// public/index.php
138+
header("Content-Type: application/json");
139+
echo json_encode([
140+
"message" => "Hello from PHP!",
141+
"timestamp" => date('c')
142+
]);
143+
?>
144+
```
145+
146+
### Handling POST Requests
147+
148+
```php
149+
<?php
150+
// public/api.php
151+
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
152+
$input = json_decode(file_get_contents('php://input'), true);
153+
154+
header("Content-Type: application/json");
155+
echo json_encode([
156+
"received" => $input,
157+
"method" => $_SERVER['REQUEST_METHOD']
158+
]);
159+
}
160+
?>
161+
```
162+
163+
## Contributing
164+
165+
This project is part of the [Platformatic](https://github.com/platformatic) ecosystem. Please refer to the main repository for contribution guidelines.
166+
167+
## License
168+
169+
Apache-2.0
170+
171+
## Support
172+
173+
- [GitHub Issues](https://github.com/platformatic/php/issues)
174+
- [Platformatic Documentation](https://docs.platformatic.dev/)
175+
- [Community Discord](https://discord.gg/platformatic)

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@
2020
"type": "module",
2121
"main": "./lib/index.js",
2222
"bin": {
23-
"create-platformatic-kafka-hooks": "./cli/create.js",
24-
"start-platformtic-kafka-hooks": "./cli/start.js"
23+
"create-platformatic-php": "./cli/create.js",
24+
"start-platformatic-php": "./cli/start.js"
2525
},
2626
"author": "Platformatic Inc. <[email protected]> (https://platformatic.dev)",
2727
"license": "Apache-2.0",

0 commit comments

Comments
 (0)