Skip to content

Commit 28accc4

Browse files
luispabonluispabon
committed
Update documentation and add AGENTS file
1 parent 60f9221 commit 28accc4

File tree

2 files changed

+128
-15
lines changed

2 files changed

+128
-15
lines changed

‎AGENTS.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# AI Agent Guide - PHPDocker.io
2+
3+
Welcome! This document provides essential context and instructions for AI agents working on the PHPDocker.io project.
4+
5+
## Project Overview
6+
7+
PHPDocker.io is a web-based generator for Docker environments tailored for PHP applications. This repository contains both the website and the generator core.
8+
9+
- **Primary Goal**: Provide an easy-to-use interface for generating `docker-compose.yaml` and related Dockerfiles for PHP projects.
10+
- **Architecture**: Symfony-based web application.
11+
12+
## Tech Stack
13+
14+
- **PHP**: 8.4
15+
- **Framework**: Symfony 7.0
16+
- **Template Engine**: Twig
17+
- **Frontend**: Managed via Yarn/NPM, assets served through Symfony Asset component.
18+
- **Database/Storage**: Redis (for caching/sessions).
19+
- **Environment**: Docker & Docker Compose.
20+
- **Orchestration**: Kubernetes (deployment).
21+
22+
## Critical Workflows
23+
24+
### 1. Local Development Setup
25+
The project uses a `Makefile` to automate environment setup.
26+
```bash
27+
make init
28+
```
29+
This command performs:
30+
- Cache cleanup
31+
- SSL certificate generation (using `mkcert`)
32+
- Hosts file entry creation (`phpdocker.local`)
33+
- Dependency installation (Composer & Yarn)
34+
- Starting Docker containers
35+
36+
### 2. Common Commands
37+
Always prefer using `make` commands to ensure consistent environment execution:
38+
- `make start`: Start the environment.
39+
- `make stop`: Stop the environment.
40+
- `make shell`: Open a bash shell inside the PHP container.
41+
- `make clear-cache`: Clear Symfony cache.
42+
43+
### 3. Testing & Quality
44+
- **Static Analysis**: `make static-analysis` (runs PHPStan at level 9).
45+
- **Unit Tests**: `make unit-tests` (runs PHPUnit).
46+
- **Behavioral Tests**: `make behaviour` (runs Behat).
47+
- **Coverage**: `make coverage-tests`.
48+
49+
## Coding Standards
50+
51+
- **PHP Standards**: Follow PSR-12 and Symfony best practices.
52+
- **Strict Typing**: Use strict types in all new PHP files.
53+
- **Static Analysis**: Ensure all changes pass PHPStan level 9.
54+
- **Formatting**: Use existing project patterns for indentation and naming.
55+
56+
## Project Structure Highlights
57+
58+
- `src/PHPDocker/Generator`: Core logic for Docker environment generation.
59+
- `src/Controller`: Symfony controllers for the web interface.
60+
- `templates/`: Twig templates.
61+
- `infrastructure/`: Docker and Kubernetes configuration files.
62+
- `tests/`:
63+
- `Unit`: Small unit tests.
64+
- `Functional`: Symfony functional tests.
65+
- `Behat`: Feature-based behavioral tests.
66+
67+
## Deployment Information
68+
69+
Deployment is container-based:
70+
- PHP-FPM image: `phpdockerio/site-php`
71+
- Nginx image: `phpdockerio/site-ngx`
72+
- Deployment target: Kubernetes (see `infrastructure/kubernetes`).
73+
74+
## Guidance for AI Agents
75+
76+
1. **Environment Awareness**: Always remember that the application runs inside Docker. Use `$(PHP_RUN)` (defined in Makefile as `docker compose run ...`) for executing PHP commands if you are running them from the host.
77+
2. **Configuration**: Symfony configuration is located in `config/`. Environment variables are managed via `.env` and Symfony Dotenv.
78+
3. **Tests**: When adding features to the generator, ensure you update or add tests in `tests/Functional/GeneratorTest.php` and relevant Behat features.
79+
4. **Permissions**: If you encounter file permission issues in `var/`, use `make fix-cache-permissions-dev`.

‎README.md‎

Lines changed: 49 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,67 @@
11
PHPDocker.io
22
============
33

4-
This is the repository for both the website and the generator over at [PHPDocker.io](http://phpdocker.io), opensourced on an Apache 2.0 license and open for anyone to contribute as they please
4+
PHPDocker.io is a web-based generator for Docker environments tailored for PHP applications. This repository contains both the website and the generator core, open-sourced under the Apache 2.0 license.
5+
6+
Visit us at [phpdocker.io](https://phpdocker.io).
7+
8+
Tech Stack
9+
----------
10+
11+
- **PHP**: 8.4
12+
- **Framework**: Symfony 7.0
13+
- **Frontend**: Yarn / Symfony Asset
14+
- **Storage**: Redis
15+
- **Environment**: Docker & Docker Compose
516

617
Contributing
718
------------
819

920
Fork, tweak & pull request.
1021

11-
Please follow PSR code formatting standards, and Symfony best practices and, in general, do what you see already done in the current code.
22+
Please follow PSR-12 code formatting standards, Symfony best practices, and maintain strict typing. Ensure all changes pass static analysis at level 9.
23+
24+
See [AGENTS.md](./AGENTS.md) for a more detailed guide for developers and AI agents.
1225

1326
Running the project
1427
-------------------
1528

16-
Project is given with a [PHPDocker.io](http://phpdocker.io) generated environment.
29+
The project comes with its own PHPDocker.io generated environment.
30+
31+
### Prerequisites
32+
33+
- Docker and Docker Compose
34+
- `mkcert` (for local SSL)
35+
- `make`
36+
37+
### Installation
38+
39+
The recommended installation is running the `make init` script. This will automate the setup through Docker:
40+
41+
```bash
42+
make init
43+
```
44+
45+
This command performs the following:
46+
- Cleans up caches
47+
- Provisions a local SSL certificate using `mkcert`
48+
- Creates a hosts entry (`phpdocker.local`)
49+
- Installs PHP dependencies via Composer
50+
- Installs JS dependencies via Yarn
51+
- Installs web assets
52+
- Starts up the Docker environment
1753

18-
Recommended installation is running a `make init` script: this will set up the app (bower install, composer install, etc) through docker and docker-compose commands.
54+
Once finished, the application will be available at [https://phpdocker.local:10000](https://phpdocker.local:10000). You can head directly to the [/generator](https://phpdocker.local:10000/generator) route.
1955

20-
* Clone
21-
* Run `make init` - this will:
22-
* clean up caches
23-
* provision a cert using `mkcert`
24-
* create a hosts entry (`phpdocker.local`)
25-
* composer and bower install
26-
* ensure web assets are available
27-
* start up the environment
56+
### Common Commands
2857

29-
* You can then head off to the [/generator](https://phpdocker.local:10000/generator) route.
58+
- `make start`: Start the environment.
59+
- `make stop`: Stop the environment.
60+
- `make shell`: Open a bash shell inside the PHP container.
61+
- `make static-analysis`: Run PHPStan (level 9).
62+
- `make unit-tests`: Run PHPUnit.
63+
- `make behaviour`: Run Behat tests.
3064

31-
This is an initial fail-safe set up and not always you need to run it, after it's done once you'll just need to do a good old `docker-compose up -d`.
65+
### Windows Support
3266

33-
Running the app on **Windows** is possible using Wsl2 and Docker. More info here: [Docker Desktop WSL 2 backend](https://docs.docker.com/docker-for-windows/wsl/). App will be available at [https://localhost:10000/generator](https://phpdocker.local:10000/generator) route.
67+
Running the app on **Windows** is possible using WSL2 and Docker. More info here: [Docker Desktop WSL 2 backend](https://docs.docker.com/docker-for-windows/wsl/). The app will be available at [https://localhost:10000](https://localhost:10000).

0 commit comments

Comments
 (0)