Construire avec PHPAML.
Du premier projet à la production.

Trois parcours, un premier résultat en moins de cinq minutes

AML inclut PHP et Composer, crée la structure choisie et installe automatiquement ses dépendances. Choisissez l’application classique pour MVC, AML View pour une interface déclarative réactive, ou API pour un service JSON ciblé.

aml create mon-projet
cd mon-projet
aml serve

aml create-view-app mon-interface
cd mon-interface
aml serve

aml create-api mon-api
cd mon-api
aml serve

Ouvrez ensuite http://127.0.0.1:8910. Utilisez aml doctor si vous souhaitez vérifier l’environnement. Pour le dossier actuel, utilisez aml create ..

Trois structures lisibles, une même configuration

PHPAML sépare les responsabilités sans imposer de dossiers inutiles. Le projet classique conserve app et sa carte de routes WebApp. AML View organise le backend et l’interface sous src. Une API retire les vues et adopte une classe de route par ressource.

app/
├── Controllers/
├── Models/
└── views/
routes/WebApp.php
public/index.php

src/
├── controllers/
├── models/
├── middleware/
├── locales/
└── views/
    ├── pages/
    ├── components/
    ├── layouts/
    ├── states/
    └── stylesheets/
routes/WebApp.php

src/
├── controllers/
├── models/
├── repositories/
├── requests/
├── resources/
├── middleware/
└── routes/
    └── MovieRoute.php
public/index.php

Configuration sans dossier configs

Dans les nouveaux projets, phpaml.json contient les choix partageables et .env les secrets ou valeurs propres à la machine. PHPAML construit runtime/config/app.php automatiquement. Ce dernier appartient au moteur et ne doit jamais être édité.

Cycle d’une requête

1. public/index.php charge phpaml.json et .env.
2. Les middlewares traitent la requête.
3. Le routeur découvre routes/ ou src/routes/.
4. Le conteneur injecte les dépendances du contrôleur.
5. L’action retourne HTML, JSON ou une redirection.

Passer de aml_env à runtime

Les projets plus anciens utilisent aml_env, info.json ou app/View. La migration renomme aussi app/View en app/UI. Prévisualisez toujours la conversion avant de l’appliquer. AML crée une sauvegarde dans runtime/storage/migrations avant de renommer les éléments et d’actualiser les références connues.

aml migrate:structure
aml migrate:structure --apply --yes
aml doctor --offline
aml test

Référence des commandes AML

Au premier lancement, AML demande English ou Français. Les sorties, diagnostics et erreurs suivent ce choix. AML_LANG=en ou AML_LANG=fr remplace temporairement la langue.

Options utiles

aml create projet --version 0.1.0
aml create projet --offline
aml install --production
aml install --refresh
aml doctor --offline
aml doctor --port 8080
aml doctor --production --json
aml update --version 1.3.0

Routes, requêtes et contrôleurs

'GET /users/{id}' => [
    'handler' => [UserController::class, 'show'],
    'middleware' => [AuthMiddleware::class],
    'name' => 'users.show',
],

public function show(Request $request): Response
{
    return $this->json(['id' => $request->attribute('id')]);
}

Request fournit method(), path(), query(), input(), cookie(), header(), server() et attribute(). Le JSON est décodé automatiquement. Une route inconnue retourne 404 ; une mauvaise méthode retourne 405.

return Response::html('<h1>Hello</h1>');
return Response::json(['ok' => true], 201);
return Response::redirect('/login');
return $this->view('users/show.php', ['user' => $user]);

Vues déclaratives et ressources

Les applications classiques peuvent conserver leurs templates PHP et partials. Une application AML View place ses pages, composants, layouts et états dans src/views. Les feuilles de style sont découvertes automatiquement dans src/views/stylesheets, tandis que le moteur JavaScript est servi automatiquement par AML.

src/views/pages/home/page.php
src/views/components/Navigation.php
src/views/layouts/DashboardLayout.php
src/views/stylesheets/pages/home.css
assets/images/hero.webp
public/favicon.svg

Configurer .env en ligne de commande

aml env:init
aml env:set APP_DEBUG false
aml env:get APP_DEBUG
aml env:list

env:init copie .env.example ; --force remplace un fichier existant. env:list masque mots de passe, secrets, clés et jetons. Ne publiez jamais .env dans Git.

SQLite, MySQL et migrations

SQLite est la base locale par défaut. AML crée runtime/storage/database.sqlite et enregistre root/root par convention ; SQLite n’utilise pas réellement ces identifiants.

aml db:configure sqlite
aml db:configure sqlite --path storage/app.sqlite
aml db:show

aml db:configure mysql --host 127.0.0.1 --port 3306 \
  --database phpaml --user root --password root

Migrations transactionnelles

aml make:migration create_users_table
aml migrate
aml migrate:rollback --steps 1

Les migrations sont enregistrées dans aml_migrations. Les migrations sont ordonnées et verrouillées. migrate:rollback exécute down() en ordre inverse. Le QueryBuilder fournit all() et insert() ; utilisez PDO préparé pour le reste.

Validation, CSRF et middleware

$valid = $validator->validate($request->input(), [
  'email' => ['required', 'email'],
  'name' => ['required', 'string', 'min:2', 'max:100'],
]);

Règles : required, email, string, min:n et max:n. Protégez les routes d’écriture avec CsrfMiddleware et ajoutez <?= $this->csrfField() ?> aux formulaires. Pour une API, utilisez X-CSRF-Token.

SecurityHeadersMiddleware ajoute les en-têtes de sécurité ; les détails d’erreur sont masqués avec APP_DEBUG=false.

Tester et préparer la production

aml test
aml install --production
aml doctor --production --json
aml routes

aml test utilise le PHP privé d’AML et exécute tests/run.php. --production exclut les dépendances de développement et optimise l’autoloader.

Résoudre les problèmes fréquents

Piloter le SEO depuis AML

AML centralise les métadonnées, génère les fichiers destinés aux moteurs de recherche et audite le HTML publié.

aml seo:init
aml seo:set base_url "https://example.com"
aml seo:set title "My website"
aml seo:set description "A clear description between 50 and 160 characters."
aml seo:disallow /admin
aml seo:allow /admin/public
aml seo:generate
aml seo:audit https://example.com --json

seo:generate crée public/sitemap.xml et public/robots.txt depuis les routes GET statiques. Les routes interdites sont retirées du sitemap. seo:audit vérifie le titre, la description, l’URL canonique, Open Graph, Twitter Cards, JSON-LD, la langue, le viewport, le H1, les images et HTTPS.

Construire et déployer partout

aml build exécute les tests, vérifie public/.htaccess et crée une archive ZIP, un manifeste et un checksum SHA-256 dans output/. Les secrets et éléments non exécutables sont exclus : .env, journaux, bases SQLite, tests, fichiers temporaires, output/ et deliverables/.

aml build
aml build --skip-tests

aml deploy:configure production --host example.com --user deploy \
  --path /home/deploy/site --port 22 --key ~/.ssh/id_ed25519
aml deploy:check production
aml deploy production
aml deploy:rollback production

Choisir une stratégie

aml deploy:configure hostinger --host example.com --user deploy \
  --path /home/user/domains/example.com \
  --strategy public-html \
  --public-path /home/user/domains/example.com/public_html \
  --key ~/.ssh/id_ed25519

Le profil privé est conservé dans ~/.phpaml/deploy.json avec des permissions 600. AML n’enregistre aucun mot de passe : utilisez une clé SSH. Le domaine doit pointer vers public/ ou, avec public-html, vers le chemin public configuré. Les visiteurs obtiennent /about, jamais /index.php/about.

Installer les composants indépendamment

Les commandes de création AML configurent automatiquement les bons composants. Dans un projet Composer existant, déclarez ensemble les paquets en préversion qui collaborent afin que le projet racine autorise explicitement leur niveau de stabilité.

composer require \
  phpaml/view:^0.1@beta \
  phpaml/engine:^0.1@beta

composer require \
  phpaml/data:^0.2@alpha \
  phpaml/data-mongodb:^0.1@alpha

Engine, Data et i18n peuvent aussi être installés seuls. L’adaptateur MongoDB nécessite l’extension PHP mongodb, tandis que Data SQL nécessite PDO.

Construire une interface déclarative et réactive

AML View est la couche frontend optionnelle de PHPAML. PHP rend le premier document, puis Engine gère localement l’état, les effets, les collections, les thèmes et la navigation.

aml create-view-app mon-interface
cd mon-interface
aml serve
# http://127.0.0.1:8910

src/
├── controllers/
├── models/
├── middleware/
└── views/
    ├── pages/{route}/page.php
    ├── components/
    ├── layouts/
    ├── states/{Loading,Error,NotFound}.php
    ├── stylesheets/
    ├── themes/
    └── assets/

src/views, src/controllers et src/models sont obligatoires. Les CSS sont collectés depuis src/views/stylesheets. Les ressources importées restent dans assets ; favicon, robots.txt et sitemap.xml restent dans public/.

#[State]
public int $count = 0;

public function body(): View
{
    return VStack(
        Heading('AML View')->class('page-title'),
        Text("Count: {$this->count}"),
        Button('Add one')->onClick(fn () => $this->count++),
    );
}

Les interactions compilées s’exécutent dans le navigateur sans rappeler PHP. Les effets offrent dépendances, nettoyage, debounce, throttle, annulation latest, états loading/success/error et protection contre les cycles.

Internationalisation JSON

aml install i18n
aml i18n:add es
aml i18n:list
aml i18n:check
aml i18n:missing fr
aml i18n:set-default en

Organisez librement les fichiers sous src/locales/{langue}. Le chemin devient une clé pointée, les paramètres utilisent :nom, les pluriels one/other utilisent le nombre et LocaleResolver choisit une langue supportée depuis la route, le cookie ou Accept-Language.