1. 介绍 - Phlo

1: 介绍

Phlo 是一个集成平台，拥有自己的全栈语言。您编写 .phlo 源文件；Phlo 将它们转译为您可以打开和阅读的 PHP、CSS 和 JavaScript，每个运行时错误都指向您编写的 .phlo 行。相同的语言包含四个层次：语言本身、应用平台（后端资源加上 phlo.js SPA 引擎）、服务器平台（FrankenPHP、Phlo Daemon、Phlo Realtime、Phlo WhatsApp）和操作平台（Phlo Dashboard）。本指南涵盖了所有这些内容。生产版本运行在共享运行时上，通常位于 /opt/phlo/，而每个应用程序则保留自己的源代码、数据、生成的 PHP 和 webroot。

1.1: 哲学

源代码优先：您在 .phlo 中工作，而不是在生成的 PHP、CSS 或 JavaScript 中。
小型运行时：Web 入口点加载 /opt/phlo/phlo.php 并使用 phlo_app(...) 启动应用程序。
显式运行时资源：data/app.json 选择应用程序从运行时目录加载哪些 Phlo 资源；应用程序代码保留在应用程序中。
开发和发布分开：开发构建、调试并可以使用身份验证；发布使用生成的输出。
HTML、路由和行为紧密结合：当将路由、视图、样式或脚本放在同一主题文件中可以使应用程序更清晰时，它们可以共存。
服务器驱动的前端：标记一个表单 <form.async> 或一个链接 <a.async>，Phlo 会拦截提交或点击，向您的路由发送请求，并用响应更新 DOM。您编写路由和视图，而不是 fetch 调用或客户端状态。

1.2: 安装

Phlo 需要 PHP 8.3 或更高版本；CLI 构建在相同的 PHP 上运行。对于生产环境，推荐使用 FrankenPHP 作为运行时（内置 web 服务器，工作模式）；经典的 PHP-FPM 在 Nginx 后面也可以使用。

获取运行时并使用捆绑的安装程序搭建您的第一个应用：

git clone https://github.com/q-ainl/phlo.git /opt/phlo
php /opt/phlo/install.php /var/www/example.nl/

安装程序会询问名称、主机和目标，显示运行时目录，并让您选择资源（它们的 @ requires 会自动包含），写入入口点、data/app.json、data/app.md、第一个路由和 .gitignore，并在完成干净构建和具体后续步骤后才结束。

希望一个能自我清理的副本？将 install.php 复制到新的应用程序目录并在那里运行；成功安装后，它会自我删除：

cp /opt/phlo/install.php /var/www/example.nl/ && cd /var/www/example.nl && php install.php

接下来的部分将描述安装程序为您设置的内容，以及如何手动构建相同的内容。

1.3: 项目结构

一个典型的应用程序：

/var/www/example.nl/
  app.phlo
  page.home.phlo
  data/
    app.json
    auth.ini
    creds.ini
  php/
    app.php
    classmap.php
  release/
    www/
      app.php
  www/
    app.php

php/、www/app.js、www/app.css 和 release/ 是构建输出。仅通过源代码更改它们并重新构建。

1.4: 入口点

在 www/app.php 中的开发入口点：

<?php
require('/opt/phlo/phlo.php');
phlo_app (
	id: 'Example',
	host: 'dev.example.nl',
	auth: true,
	build: true,
	debug: true,
	app: '/var/www/example.nl/',
	data: '/var/www/example.nl/data/',
);

在 release/www/app.php 中发布入口点：

<?php
require('/opt/phlo/phlo.php');
phlo_app (
	id: 'Example',
	host: 'stage.example.nl',
	app: '/var/www/example.nl/release/',
	php: '/var/www/example.nl/release/',
	data: '/var/www/example.nl/data/',
);

1.5: Build

在开发过程中，每个请求都会自动重建已更改的源文件，因此浏览器重新加载就是所需的所有更改。CLI 明确提供相同的构建，用于脚本、CI 和代理：

php www/app.php build::run
php www/app.php build::lint
php www/app.php build::release

build::run 转换开发输出，build::lint 检查生成的 PHP，build::release 写入发布输出。

1.6: 网络服务器

Web 服务器在开发环境中指向 www/，在阶段/生产环境中指向 release/www/。未知路径会被重写为 app.php。

对于 FrankenPHP（推荐），一个 Caddyfile 块就足够了：

example.nl {
	root * /var/www/example.nl/release/www
	php_server
}

对于 Nginx：

root /var/www/example.nl/release/www;

location / {
	try_files $uri $uri/ /app.php?$query_string;
}