Comprendre PHPAML.
Construire efficacement.

Quatre 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 Classique pour MVC, View pour une interface réactive, API pour JSON ou Console pour apprendre et exécuter du PHP pur.

aml create mon-projet
cd mon-projet
aml serve

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

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

aml create-console mon-programme
cd mon-programme
aml run

Pour les trois parcours Web, ouvrez ensuite http://127.0.0.1:8910. Utilisez aml doctor pour vérifier l’environnement.

Quatre parcours lisibles, une même plateforme

PHPAML sépare les responsabilités sans imposer de dossiers inutiles. Les applications classique et View utilisent src. Une API retire les vues et adopte une classe de route par ressource. Un programme Console conserve uniquement le PHP nécessaire à son exécution.

src/
├── controllers/
├── models/
├── middleware/
├── routes/WebApp.php
└── views/
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.

Apprendre et exécuter du PHP sans application Web

Le parcours Console génère un programme PHP pur, strict et orienté objet. Il ne contient ni serveur HTTP, ni route, ni contrôleur, ni HTML. echo écrit dans le terminal, fgets() lit une saisie et la valeur retournée par main() devient le code de sortie.

aml create-console bonjour
cd bonjour
aml run
aml run -- Andre
aml make:class Domain/User
aml test

final class Program
{
    /** @param list<string> $arguments */
    public static function main(array $arguments): int
    {
        $name = $arguments[0] ?? 'PHP';
        echo "Hello, {$name}!\n";
        return 0;
    }
}

La réactivité locale utilisée par AML View

Engine n’est pas un interpréteur PHP complet dans le navigateur. Il reçoit l’état initial et les instructions frontend produites par View, puis met à jour uniquement les nœuds concernés. Les affectations, calculs, conditions, collections, requêtes API et effets pris en charge peuvent ainsi rester exprimés en PHP côté auteur.

Button('Calculate')->onClick(function (): void {
    $subtotal = $this->price * $this->quantity;
    $this->total = $subtotal - $this->discount;
});

Créer un service JSON sans couche de vues

create-api prépare une structure dédiée aux contrôleurs, requêtes validées, ressources, dépôts, middlewares et routes par classe. Elle n’installe pas AML View : l’application répond en JSON et peut rester indépendante d’un frontend.

aml create-api films-api
cd films-api
aml serve
aml routes
aml test

Persistance typée pour MVC, View, API ou PHP autonome

PHPAML Data est optionnel. make:model crée toujours une classe PHP simple ; make:entity crée une entité persistante après installation de Data. SQLite, MySQL, MariaDB et PostgreSQL sont couverts par la matrice de tests réelle. MongoDB reste fourni par un adaptateur alpha séparé.

aml install data --driver sqlite
aml make:entity User
aml make:migration create_users_table
aml make:seeder UserSeeder
aml data:migrate
aml data:doctor

#[Table('users')]
final class User extends Entity
{
    #[Key]
    public int $id;
    public string $name;
    public string $email;
}

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 --dry-run
aml deploy:status production
aml deploy production
aml deploy:history production
aml deploy:rollback production
aml deploy:prune production --keep 5

Après le premier envoi, AML compare les empreintes SHA-256 et ne transfère que les fichiers ajoutés ou modifiés. Il retire les fichiers supprimés, affiche le volume transféré, l’économie obtenue et la progression jusqu’à l’activation. --dry-run et deploy:status restent strictement en lecture seule.

[ 25%] Comparison completed
+ public/version.txt
~ src/controllers/HomeController.php
- public/obsolete.txt
Transfer: 42.3 KB of 8.40 MB — 99.5% saved
[100%] Deployment completed

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 et l’historique dans ~/.phpaml/deploy-history.json, tous deux avec des permissions 600. L’historique conserve au plus 100 résultats sans hôte, chemin, utilisateur ni secret.

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 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/.

use AML\View\{Page, State, View};
use function AML\View\{Button, Text, VStack, import};

import('pages/home.css');

final class HomePage extends Page
{
    #[State]
    private int $count = 0;

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

Les propriétés #[State] se lisent et se modifient comme du PHP ordinaire. View compile les fermetures frontend prises en charge ; Engine exécute ensuite l’interaction dans le navigateur, sans requête serveur pour chaque clic. Les effets offrent dépendances, debounce, throttle, annulation latest et états loading/success/error.

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.