add skill for markdown
also move some files around
This commit is contained in:
@@ -1,46 +0,0 @@
|
|||||||
# Debug API PHP con VS Code e Docker
|
|
||||||
|
|
||||||
Questa sezione descrive la procedura per fare debug delle API PHP servite da Docker in questa repository.
|
|
||||||
|
|
||||||
## Passaggi
|
|
||||||
|
|
||||||
1. Avvia il container Docker dalla root del progetto:
|
|
||||||
```bash
|
|
||||||
docker compose up --build
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Apri Visual Studio Code e vai su "Run and Debug".
|
|
||||||
|
|
||||||
3. Seleziona la configurazione:
|
|
||||||
```text
|
|
||||||
Debug PHP in Docker
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Premi F5 per avviare il debugger.
|
|
||||||
|
|
||||||
5. Imposta un breakpoint in un controller, ad esempio in:
|
|
||||||
```text
|
|
||||||
src/Api/Controllers/V1/UsersController.php
|
|
||||||
```
|
|
||||||
|
|
||||||
6. Richiama l’endpoint tramite browser o curl:
|
|
||||||
```bash
|
|
||||||
curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
|
|
||||||
```
|
|
||||||
|
|
||||||
## Nota
|
|
||||||
|
|
||||||
Il container deve esporre:
|
|
||||||
- porta `8000` per HTTP
|
|
||||||
- porta `9003` per Xdebug
|
|
||||||
|
|
||||||
Il progetto contiene già i file necessari per il debug:
|
|
||||||
- `.docker/php/Dockerfile`
|
|
||||||
- `docker-compose.yml`
|
|
||||||
- `.vscode/launch.json`
|
|
||||||
- `.vscode/settings.json`
|
|
||||||
|
|
||||||
## Problemi comuni
|
|
||||||
|
|
||||||
- Se VS Code non si ferma sul breakpoint, verifica che Xdebug sia abilitato nel container e che la configurazione `client_host` punti a `host.docker.internal`.
|
|
||||||
- Se il container non si avvia, controlla che Docker Desktop sia in esecuzione.
|
|
||||||
@@ -0,0 +1,203 @@
|
|||||||
|
---
|
||||||
|
name: markdown-linting
|
||||||
|
description: Markdown formatting standards following markdownlint practices
|
||||||
|
applyTo: [markdown]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Markdown Linting Skill
|
||||||
|
|
||||||
|
This skill documents markdown formatting standards for this project, following markdownlint practices.
|
||||||
|
|
||||||
|
## Core Rules
|
||||||
|
|
||||||
|
### Headings
|
||||||
|
- Use `#` for headings (not underlines with `===` or `---`)
|
||||||
|
- Headings must have space after `#`: `# Heading` ✓, `#Heading` ✗
|
||||||
|
- Heading levels must increment by 1: `# > ## > ###` (don't skip levels)
|
||||||
|
- File must start with a level 1 heading (H1)
|
||||||
|
- Use sentence case for headings (capitalize only first word unless proper noun)
|
||||||
|
|
||||||
|
### Line Endings & Spacing
|
||||||
|
- Trim trailing whitespace at end of lines
|
||||||
|
- No more than one blank line between elements
|
||||||
|
- Use consistent list marker spacing: 1 space after marker
|
||||||
|
- Between major sections: exactly 1 blank line
|
||||||
|
|
||||||
|
### Lists
|
||||||
|
- Use `-` for unordered lists (not `*` or `+`)
|
||||||
|
- Lists must be indented consistently (2 spaces or 4 spaces)
|
||||||
|
- Ordered lists use `1. 2. 3.` (always `1.` for first item)
|
||||||
|
- List items with multiple paragraphs: indent continuation 4 spaces
|
||||||
|
- Blank line before and after lists (if between other content)
|
||||||
|
|
||||||
|
### Code
|
||||||
|
- Inline code with backticks: `` `code` ``
|
||||||
|
- Code blocks use triple backticks with language: ` ```php `, ` ```bash `, ` ```json `
|
||||||
|
- Blank line before code block
|
||||||
|
- Blank line after code block
|
||||||
|
- Use fenced code blocks (` ``` `), not indentation
|
||||||
|
|
||||||
|
### Links & Images
|
||||||
|
- Use reference-style or inline links: `[text](url)`
|
||||||
|
- Image syntax: ``
|
||||||
|
- URLs must be valid and properly formatted
|
||||||
|
- Don't use bare URLs (wrap in `<>` or use markdown link syntax)
|
||||||
|
|
||||||
|
### Emphasis
|
||||||
|
- Use `**bold**` for bold (not `__bold__`)
|
||||||
|
- Use `*italic*` for italic (not `_italic_`)
|
||||||
|
- Underscores on word boundaries only
|
||||||
|
|
||||||
|
### Line Length
|
||||||
|
- Keep lines under 120 characters where practical
|
||||||
|
- Long URLs and code blocks are exceptions
|
||||||
|
- Wrap long text at sentence boundaries
|
||||||
|
|
||||||
|
### Blockquotes
|
||||||
|
- Use `>` for blockquotes with space after: `> quote` ✓
|
||||||
|
- Blank line after blockquote if followed by text
|
||||||
|
|
||||||
|
## Template Structure
|
||||||
|
|
||||||
|
### Documentation Files
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Main Title
|
||||||
|
|
||||||
|
Brief introduction (1-2 sentences).
|
||||||
|
|
||||||
|
## Section One
|
||||||
|
|
||||||
|
Content here.
|
||||||
|
|
||||||
|
### Subsection
|
||||||
|
|
||||||
|
Details.
|
||||||
|
|
||||||
|
## Section Two
|
||||||
|
|
||||||
|
More content.
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- [Link text](url)
|
||||||
|
```
|
||||||
|
|
||||||
|
### API Documentation
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# API Endpoint Name
|
||||||
|
|
||||||
|
Brief description.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
What this does.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Prerequisite 1
|
||||||
|
- Prerequisite 2
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Request
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl command
|
||||||
|
```
|
||||||
|
|
||||||
|
### Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
json example
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
- Option 1: description
|
||||||
|
- Option 2: description
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Problem
|
||||||
|
|
||||||
|
Solution.
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- [Related](link)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Guides & Tutorials
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Tutorial Title
|
||||||
|
|
||||||
|
Brief intro.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Item 1
|
||||||
|
|
||||||
|
## Step 1: Title
|
||||||
|
|
||||||
|
Description and code.
|
||||||
|
|
||||||
|
## Step 2: Title
|
||||||
|
|
||||||
|
Description and code.
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
How to test.
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
Issues and fixes.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Checklist
|
||||||
|
|
||||||
|
- [ ] File starts with `# Title` (H1)
|
||||||
|
- [ ] Headings have space after `#`
|
||||||
|
- [ ] No heading level jumps
|
||||||
|
- [ ] No trailing whitespace
|
||||||
|
- [ ] Max 1 blank line between sections
|
||||||
|
- [ ] Lists use `-` consistently
|
||||||
|
- [ ] Code blocks have language specified
|
||||||
|
- [ ] Inline code uses backticks
|
||||||
|
- [ ] Links are properly formatted
|
||||||
|
- [ ] No bare URLs
|
||||||
|
- [ ] Lines under 120 chars where practical
|
||||||
|
- [ ] Bold uses `**text**`, italic uses `*text*`
|
||||||
|
- [ ] All section transitions are clear
|
||||||
|
|
||||||
|
## Common Violations to Avoid
|
||||||
|
|
||||||
|
❌ `#No space after hash`
|
||||||
|
✓ `# Space after hash`
|
||||||
|
|
||||||
|
❌ `# Heading\n\n\n## Next` (two blank lines)
|
||||||
|
✓ `# Heading\n\n## Next` (one blank line)
|
||||||
|
|
||||||
|
❌ `* or + for lists`
|
||||||
|
✓ `- for all lists`
|
||||||
|
|
||||||
|
❌ Bare URL `http://example.com`
|
||||||
|
✓ Wrapped URL `<http://example.com>`
|
||||||
|
✓ Link `[text](http://example.com)`
|
||||||
|
|
||||||
|
❌ Indented code blocks
|
||||||
|
✓ Fenced code blocks ` ``` `
|
||||||
|
|
||||||
|
❌ `# Skip to ### level`
|
||||||
|
✓ `# Then ## Then ###`
|
||||||
|
|
||||||
|
❌ __emphasis with underscores__
|
||||||
|
✓ **emphasis with asterisks**
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [Markdownlint Rules](https://github.com/markdownlint/markdownlint/blob/main/README.md)
|
||||||
|
- [CommonMark Spec](https://spec.commonmark.org/)
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
# Istruzioni per lo sviluppo di questa repository
|
|
||||||
|
|
||||||
## Debug delle API PHP con Docker
|
|
||||||
|
|
||||||
Quando si lavora su questa repository e si deve fare debug delle API PHP servite via Docker, usare il setup seguente:
|
|
||||||
|
|
||||||
- avviare il container con `docker compose up --build`
|
|
||||||
- usare la configurazione VS Code `Debug PHP in Docker`
|
|
||||||
- mettere breakpoint nei controller sotto `src/Api/Controllers`
|
|
||||||
- testare le richieste su `http://localhost:8000`
|
|
||||||
- se il debugger non parte, usare `curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users`
|
|
||||||
|
|
||||||
Queste istruzioni valgono anche per eventuali problemi di routing o di esecuzione delle API.
|
|
||||||
@@ -8,7 +8,21 @@ Queste istruzioni permettono di fare debug delle API PHP servite con Docker dire
|
|||||||
- Visual Studio Code
|
- Visual Studio Code
|
||||||
- Estensione PHP per VS Code
|
- Estensione PHP per VS Code
|
||||||
|
|
||||||
## 1. Avvia il container
|
## 1. Configurazione del progetto
|
||||||
|
|
||||||
|
Il progetto contiene già i file necessari per il debug:
|
||||||
|
|
||||||
|
- `.docker/php/Dockerfile` - container PHP con Xdebug
|
||||||
|
- `docker-compose.yml` - configurazione Docker
|
||||||
|
- `.vscode/launch.json` - configurazione di avvio VS Code
|
||||||
|
- `.vscode/settings.json` - impostazioni VS Code
|
||||||
|
|
||||||
|
Il container espone:
|
||||||
|
|
||||||
|
- **porta `8000`** per HTTP
|
||||||
|
- **porta `9003`** per Xdebug
|
||||||
|
|
||||||
|
## 2. Avvia il container
|
||||||
|
|
||||||
Dalla root del progetto esegui:
|
Dalla root del progetto esegui:
|
||||||
|
|
||||||
@@ -22,52 +36,56 @@ Il server PHP sarà disponibile su:
|
|||||||
http://localhost:8000
|
http://localhost:8000
|
||||||
```
|
```
|
||||||
|
|
||||||
## 2. Avvia il debug in VS Code
|
## 3. Avvia il debug in VS Code
|
||||||
|
|
||||||
Apri la sezione Run and Debug e seleziona la configurazione:
|
1. Apri la sezione **Run and Debug** in VS Code (Ctrl+Shift+D)
|
||||||
|
2. Seleziona la configurazione: **Debug PHP in Docker**
|
||||||
|
3. Premi **F5** per avviare il debugger
|
||||||
|
|
||||||
```text
|
## 4. Imposta un breakpoint e testa
|
||||||
Debug PHP in Docker
|
|
||||||
```
|
|
||||||
|
|
||||||
Poi premi F5.
|
1. Aggiungi un breakpoint in un controller, ad esempio:
|
||||||
|
|
||||||
## 3. Imposta un breakpoint
|
|
||||||
|
|
||||||
Aggiungi un breakpoint in un controller, ad esempio in:
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
src/Api/Controllers/V1/UsersController.php
|
src/Api/Controllers/V1/UsersController.php
|
||||||
```
|
```
|
||||||
|
|
||||||
Quindi richiama un endpoint come:
|
2. Richiama un endpoint tramite browser:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
http://localhost:8000/api/users
|
http://localhost:8000/api/users
|
||||||
```
|
```
|
||||||
|
|
||||||
## 4. Se il debugger non parte
|
3. Oppure usa curl con il trigger Xdebug:
|
||||||
|
|
||||||
Prova a inviare la richiesta con il trigger Xdebug:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
|
curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
|
||||||
```
|
```
|
||||||
|
|
||||||
## 5. Configurazione attesa
|
Il debugger dovrebbe fermarsi sul breakpoint e permetterti di ispezionare le variabili.
|
||||||
|
|
||||||
Il progetto contiene già:
|
## 5. Risoluzione dei problemi
|
||||||
|
|
||||||
- un Dockerfile PHP con Xdebug
|
### VS Code non si ferma sul breakpoint
|
||||||
- un file docker-compose.yml
|
|
||||||
- una configurazione di avvio VS Code in .vscode/launch.json
|
|
||||||
|
|
||||||
## 6. Nota importante
|
- Verifica che Xdebug sia abilitato nel container
|
||||||
|
- Controlla che la configurazione `client_host` nel Dockerfile punti a `host.docker.internal`
|
||||||
|
- Verifica che la porta 9003 sia disponibile e non bloccata dal firewall
|
||||||
|
|
||||||
Il server PHP viene eseguito con:
|
### Il container non si avvia
|
||||||
|
|
||||||
```bash
|
- Assicurati che Docker Desktop sia in esecuzione
|
||||||
php -S 0.0.0.0:8000 -t public public/index.php
|
- Verifica che le porte 8000 e 9003 non siano già in uso
|
||||||
```
|
- Controlla i log di Docker per errori specifici
|
||||||
|
|
||||||
Questa modalità è adatta per il debug delle API HTTP del progetto.
|
### "Failed to fetch" dalle richieste del frontend
|
||||||
|
|
||||||
|
- Verifica che il frontend abbia il CORS correttamente configurato
|
||||||
|
- Controlla che `allowed_origins` in `config/config.php` includa l'origine del frontend
|
||||||
|
- Testa con l'endpoint di diagnostica `/cors-check`
|
||||||
|
|
||||||
|
## Note
|
||||||
|
|
||||||
|
- La procedura di debug influisce solo sulla sessione VS Code, il server continua a funzionare normalmente
|
||||||
|
- È possibile debug con i breakpoint condizionali per limitare i fermi
|
||||||
|
- Usa la console di debug di VS Code per eseguire comandi PHP durante il debug
|
||||||
|
|||||||
Reference in New Issue
Block a user