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
|
||||
- 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:
|
||||
|
||||
@@ -22,52 +36,56 @@ Il server PHP sarà disponibile su:
|
||||
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
|
||||
Debug PHP in Docker
|
||||
```
|
||||
## 4. Imposta un breakpoint e testa
|
||||
|
||||
Poi premi F5.
|
||||
|
||||
## 3. Imposta un breakpoint
|
||||
|
||||
Aggiungi un breakpoint in un controller, ad esempio in:
|
||||
1. Aggiungi un breakpoint in un controller, ad esempio:
|
||||
|
||||
```text
|
||||
src/Api/Controllers/V1/UsersController.php
|
||||
```
|
||||
|
||||
Quindi richiama un endpoint come:
|
||||
2. Richiama un endpoint tramite browser:
|
||||
|
||||
```text
|
||||
http://localhost:8000/api/users
|
||||
```
|
||||
|
||||
## 4. Se il debugger non parte
|
||||
|
||||
Prova a inviare la richiesta con il trigger Xdebug:
|
||||
3. Oppure usa curl con il trigger Xdebug:
|
||||
|
||||
```bash
|
||||
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
|
||||
- un file docker-compose.yml
|
||||
- una configurazione di avvio VS Code in .vscode/launch.json
|
||||
### VS Code non si ferma sul breakpoint
|
||||
|
||||
## 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
|
||||
php -S 0.0.0.0:8000 -t public public/index.php
|
||||
```
|
||||
- Assicurati che Docker Desktop sia in esecuzione
|
||||
- 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