README

This repository contains the application skeleton for Velt framework used for local development and testing.

Usage

Install dependencies:

composer install

Run tests:

composer test

Start local server:

php bin/velt serve 127.0.0.1:8000

Configuration

Copy .env.example to .env and edit variables as needed.
Configuration files are under config/ and accessible via config('app.name') and helpers env('KEY', 'default').

Presets (guide rapide)

Le skeleton peut être initialisé avec plusieurs presets d'architecture pour accélérer la création d'un projet Velt. Chaque preset décrit une arborescence minimale et des fichiers recommandés. Les presets disponibles (MVP) :

monolith-feature — structure par feature (par défaut pour applications web simples).
api-only — structure légère pour API (pas de pages HTML, uniquement JSON endpoints).
mvc-simple — structure classique MVC avec dossiers Controllers, Models, Views.

Exemples d'arborescences minimales

monolith-feature

my-project/
  features/
    Home/
      HomePage.php
      HomeController.php
  routes/
    web.php
  public/
    config/

api-only

my-project/
  src/
    Controllers/
  routes/
    api.php
  public/
  config/

mvc-simple

my-project/
  app/
    Controllers/
    Models/
    Views/
  public/
  routes/
  config/

Notes

Les presets ne modifient pas les composants internes du framework (kernel, http, ui, etc.). Ils génèrent uniquement des fichiers et arborescences côté application.
Le CLI et les generateurs sont conçus pour supporter --preset, --dry-run et --force. Le générateur doit vérifier les collisions et proposer un rollback si nécessaire.

CLI (guide rapide)

Le skeleton inclut un shim CLI minimal bin/velt qui offre une commande serve. À terme la CLI fournira des commandes de génération et d'assistance.

Commandes disponibles aujourd'hui :

php bin/velt help
php bin/velt serve [host:port]    # exemple: php bin/velt serve 127.0.0.1:8000

Commandes prévues pour la génération (exemples d'usage)

# Générer un nouveau projet avec preset monolith-feature
php bin/velt make:project my-project --preset=monolith-feature

# Générer une feature (controller + page + test)
php bin/velt make:feature auth

# Dry run pour vérifier les fichiers qui seraient créés
php bin/velt make:project my-project --preset=api-only --dry-run

Bonnes pratiques

Toujours exécuter --dry-run ou vérifier le repository avant d'exécuter un générateur sur un projet existant.
Les presets doivent être simples et explicites ; éviter de modifier des fichiers fournis par kernel.
Documenter tout preset nouveau dans ce README et ajouter un test d'acceptation qui vérifie l'arborescence générée.

Velt Skeleton

Projet applicatif minimal installe par velt new.

Ce repo est le point d'entree du Module 2 - Skeleton et Developer Experience. Il ne contient pas le framework entier : il assemble les packages du Module 1 (kernel, http, ui, database, cli) dans une application concrete, executable et testable.

Etat actuel

Issue 01 - Creer le skeleton installable : implementee.

Le skeleton fournit maintenant :

un composer.json de projet avec dependances Velt locales ;
un front controller public/index.php ;
un bootstrap applicatif bootstrap/app.php ;
les routes routes/web.php et routes/api.php ;
une feature features/Home qui rend une page Velt en HTML ;
un binaire projet bin/velt ;
un .env.example ;
une base PHPUnit de fumee pour valider / et /api/preview/demo.

Installation locale

Depuis ce repo :

composer install
cp .env.example .env
php bin/velt kernel:check
php bin/velt serve --dry-run
composer test

Sur Windows PowerShell :

composer install
Copy-Item .env.example .env
php bin/velt kernel:check
php bin/velt serve --dry-run
composer test

Pour lancer le serveur :

php bin/velt serve

Puis ouvrir http://127.0.0.1:8000.

Routes disponibles

Methode	Route	Description
GET	`/`	Rend la page d'accueil Velt en HTML via `Velt\Ui\Renderers\WebRenderer`.
GET	`/api/preview/demo`	Retourne une erreur JSON propre quand aucune session preview n'existe.

Exemple de payload preview sans session :

{
  "success": false,
  "error": {
    "code": "preview_session_missing",
    "message": "No preview session is available for the demo route."
  }
}

Structure

bootstrap/
  app.php
bin/
  velt
config/
  app.php
  database.php
  preview.php
features/
  Home/
    HomePage.php
public/
  index.php
routes/
  api.php
  web.php
tests/
  Feature/
    SkeletonSmokeTest.php

Comment ca marche

bootstrap/app.php charge la configuration, instancie Velt\Kernel\Application, enregistre les providers HTTP/UI, charge les routes, puis expose le dispatcher HTTP.

public/index.php capture la requete HTTP avec Velt\Http\Request, la passe au dispatcher, puis envoie la response.

features/Home/HomePage.php construit une page declarative avec Page, Card, Text et Button, puis la rend en HTML.

bin/velt delegue a Velt\Cli\ApplicationFactory, ce qui permet d'utiliser les commandes CLI officielles depuis le projet skeleton.

Objectif Module 2

Le Module 2 transforme les composants bas niveau du Module 1 en experience developpeur concrete :

creer un projet Velt minimal installable ;
exposer .env.example et config/*.php sans reinventer le loader du kernel ;
proposer des presets d'architecture simples ;
fournir une base PHPUnit pour applications Velt ;
aligner les generateurs CLI sur la structure du skeleton ;
poser les standards de documentation et de contribution.

Perimetre du repo

Inclus dans ce repo :

composer.json du projet skeleton ;
public/index.php comme front controller ;
bin/velt pour les commandes projet ;
config/app.php, config/database.php, config/preview.php ;
routes/web.php et routes/api.php ;
structure features/ par defaut ;
.env.example ;
presets MVP documentes ;
tests de fumee du projet genere.

Exclus de ce repo :

implementation interne du kernel ;
routeur HTTP complet ;
moteur UI ;
ORM avance ;
systeme de preview mobile avance ;
generateurs CLI eux-memes, sauf exemples et integration.

Sous-modules et repos

Sous-module	Repo cible	Decision
01 - Project Skeleton	`Velt-PHP/veltphp-skeleton`	Implementation principale
02 - Architecture Presets	`Velt-PHP/veltphp-skeleton` + `Velt-PHP/veltphp-cli`	Presets dans le skeleton, selection via CLI
03 - Config Environment	`Velt-PHP/veltphp-skeleton` au MVP	Extraire vers `veltphp/config` seulement si l'API devient stable
04 - Testing Foundation	`veltphp/testing` recommande	Peut demarrer comme dossier `tests/` du skeleton avant extraction
05 - Code Generators	`Velt-PHP/veltphp-cli`	Adapter les commandes `make:*` au skeleton
06 - Documentation Standards	`veltphp/docs` recommande	Peut demarrer comme conventions partagees dans ce repo

Definition of Done

velt new blog cree un projet minimal depuis ce skeleton.
composer install fonctionne avec les packages Velt locaux via path repositories.
php bin/velt serve demarre le projet.
La route / retourne une page Velt rendue en HTML.
Une route preview JSON expose un contrat d'erreur propre si aucune session n'existe.
Les presets monolith-feature, api-only et mvc-simple sont documentes.
Les tests de base peuvent etre lances sans configuration cachee.

Workflow local attendu

Tant que les packages ne sont pas publies sur Packagist, utiliser des repositories Composer de type path :

{
  "repositories": [
    { "type": "path", "url": "../veltphp-kernel/packages/kernel", "options": { "symlink": true } },
    { "type": "path", "url": "../veltphp-http", "options": { "symlink": true } },
    { "type": "path", "url": "../velt-ui", "options": { "symlink": true } },
    { "type": "path", "url": "../velt-database", "options": { "symlink": true } },
    { "type": "path", "url": "../veltphp-cli", "options": { "symlink": true } }
  ]
}

Verification minimale :

composer install
composer dump-autoload
php bin/velt kernel:check
php bin/velt serve --dry-run
composer test

Les chemins sont relatifs au dossier github-repos/, ce qui permet de travailler en symlink sur les packages locaux sans copier le code.

Labels GitHub

Les issues Module 2 doivent utiliser les labels suivants :

module:2-skeleton-dx
area:skeleton, area:cli, area:config, area:testing, area:docs
type:feature, type:architecture, type:tests, type:documentation
priority:p0, priority:p1, priority:p2
status:ready

Ordre de livraison

Skeleton installable.
Presets MVP.
Configuration projet.
Base de tests.
Generateurs CLI alignes.
Standards de documentation.

Criteres Issue 01

Le skeleton peut etre clone et installe avec Composer.
php bin/velt serve lance le projet via le serveur PHP local.
La route / retourne une page Velt rendue en HTML.
La route /api/preview/demo retourne une erreur JSON propre si aucune session n'existe.

velt/skeleton

包简介

README 文档