README

AttoPHP 是一个基于构建者模式的工具，可以轻松地配置、路由和渲染一个网站。

1. 简介
2. 要求
3. 安装
4. 特点
5. 使用
6. 控制流程
7. 错误处理

1. 简介

市面上有大量其他解决方案，例如 Slim 框架、bramus/router、Twig 以及许多其他框架。每个都有其独特的功能、依赖，并且都建议使用 Composer 安装。

AttoPHP 不如其他框架全面，但它快速且易于使用。一旦你理解了一些核心原则，你就可以开始了。一些基本的 PHP 知识是首选，但如果你可以阅读和修改一些简单的 PHP 代码，你就能达到目的。

2. 要求

PHP ^8.1
URL 重写

3. 安装

使用 Composer 安装 AttoPHP 非常简单

$ composer require extendssoftware/atto-php

4. 特点

不多，但足以让您的网站开始运行

匹配和组装路由
重定向到 URL
开始、路由、结束和错误时的回调
渲染 PHP 模板（布局、视图和部分）和脚本
数据容器
配置加载
文本翻译

在每一个回调、模板和脚本中，AttoPHP 都是当前对象 $this，因此无论你做什么，你都可以使用这些功能。

熟悉 jQuery 的人都知道如何使用组合的 get/set 方法。让我们考虑一下 view 方法。当这个方法不带参数调用时，将返回当前设置的视图，如果没有设置视图，则返回 null。当这个方法带有一个视图文件名时，将设置视图。通常，当使用适当的面向对象编程时，这将是两个方法，getView 和 setView。AttoPHP 使用组合方法以保持其紧凑和快速。

5 使用

设置完成后，需要调用 run 方法来运行 AttoPHP 并获取渲染的内容。

5.1 路由

一切从将 URL 匹配到视图和/或回调开始。一个路由可以有以下属性

名称
模式
视图
回调

5.1.1 名称

路由名称可以是任何你喜欢的名称。路由名称是必需的，在组装过程中使用，例如在模板中。有了组装路由的选项，您不需要更改网站每个地方的 URL。只需更改 URL，只要您保持名称相同，它就会在所有地方更改。这也可以在脚本中完成，例如在渲染网站地图时。

可以通过为方法assemble不提供路由名称来组装当前路由。这只能在AttoPHP运行后、路由匹配并接收到HTTP请求时进行。提供的参数将覆盖匹配路由中的参数。路由模式中的星号不会进行组装。

当组装命名路由时，匹配的路由参数将与提供的参数合并。

5.1.2 模式（匹配和组装）

模式将用于检查路由是否与URL匹配。路由匹配是对URL路径进行的，包括顶级域名（TLD）之后的所有内容（如/foo/bar/baz）。当模式包含查询字符串时（如/foo/bar/baz?foo=），也会匹配查询字符串。如果不包含查询字符串，则跳过查询字符串匹配，允许每个参数和值。

模式路径可以由静态文本、参数和可选部分组成。必需参数以冒号开头，后跟字母字符，可以由字母数字字符和下划线组成（如/blog/:blogId）。可选部分之外的参数是必需的，并且必须在URL中存在，以便路由匹配。

可选路径部分由方括号[和]包围，可以嵌套（如/blog/:blogId[/comments[/:page]]）。可选部分内的参数不是必需的。只有当部分内的所有参数都匹配时，可选部分才会匹配。可选部分的处理是从外到内。对于模式/blog/:blogId[/comments[/:page]]，只有当URL中指定了page时，带有page的部分才会匹配。comments部分会与或没有page部分匹配。

这同样适用于路由组装。只有当所有参数都已指定且每个嵌套的可选部分也已组装时，可选部分才会组装。来自路由/foo[/:bar[/:baz]]的参数baz部分只有在参数bar也指定时才会组装。

匹配的路径参数在以atto.route为前缀的数据容器中可用。对于模式/blog/:blogId的路径参数blogId，可以通过路径atto.route.blogId访问。未匹配的路径参数作为null值提供。

匹配的查询字符串参数也在以atto.route为前缀的数据容器中可用。对于模式/blog?page=的查询字符串参数page，可以通过路径atto.route.query访问。未匹配的查询字符串参数作为null值提供。只有指定的查询字符串参数是可访问的。

大括号{和}内的部分在匹配之前会被翻译。在匹配URL/blog/{page}之前，部分{page}会被翻译为全局或提供的语言环境。这也适用于查询字符串参数。查询字符串参数?{page}=<\d+>在路由匹配之前会被翻译。

5.1.3 约束和 HTTP 方法

可以为路径参数指定约束。约束是一个不带界定符[a-z0-9-]+的正则表达式。约束必须添加在参数名之后，并在<和>字符之间包含正则表达式（如/blog/:page<\d+>）。当参数值不匹配约束时，路由将不会匹配。当未指定约束时，默认约束是[^/]+，匹配直到下一个正斜杠或URL的末尾（如果没有的话）。

在路由模式中可以使用星号*来匹配URL中的所有字符。路由/foo/*将匹配/foo/bar，也会匹配/foo/baz。类似/*的路由将匹配任何URL。星号匹配零个到无限个字符。建议将一个通配符路由/*作为最后一个路由添加。此路由可以用于重定向到适当的404页面或显示当前URL的404页面。

约束也可以像路径参数一样指定查询字符串参数 /blog?page=<\d+>。当未指定约束或省略等号时，默认约束为 .*。在路由模式 /blog 中未指定查询字符串时，允许所有查询字符串参数和值。当指定了问号和感叹号组合 /blog?! 时，不允许查询字符串。

当组装路由时，如果约束与参数值不匹配，将发生错误。当约束仅允许数字 \d+ 时，不允许字母 a。

可以将 HTTP 方法添加到路由模式的开头，必须以竖线分隔，并以空格字符结尾 POST|DELETE /blog/:blogId。当未指定 HTTP 方法时，所有方法都将匹配路由。路由组装期间不包含路由的 HTTP 方法。也可以使用星号用于带有 HTTP 方法的路由。

5.1.4 视图和回调

路由视图是可选的。当路由匹配并且设置了视图时，此视图将被设置为 AttoPHP 以供以后使用。

当您想在回调中使用任何 URL 参数时，需要添加与路由参数完全相同名称的回调参数。值将是字符串类型。当路由参数是可选的，参数必须具有默认值或允许 null。对于参数 :blogId，您必须添加参数 $blogId。参数的顺序无关紧要。

要在回调或模板中获取匹配的路由，必须不带任何参数调用 route 方法。匹配的路由还包含所有匹配的 URL 参数。

5.1.5 示例

/blog[/:page<\d+>]

允许 /blog 和 /blog/1 的 URL。URL /blog/a 不会匹配，因为约束仅允许数字。页面参数是可选的。将匹配任何 HTTP 方法。

POST|DELETE /blog/:blogId

此路由允许 POST 和 DELETE HTTP 方法。 blogId 将匹配除斜杠之外的所有内容。始终添加约束以避免奇怪的行为和 URL 以优化 SEO 被认为是良好的做法。

/*

通配符路由，将匹配任何 HTTP 方法下的任何 URL。

/blog/*.html

将匹配以 /blog/ 开头并以 .html 结尾的任何路由。

5.2 任务

后台任务是网站或 Web 应用程序的重要组成部分。任务可以有以下属性

名称
命令
脚本和回调
示例

5.2.1 名称

任务名称可以是任何您喜欢的名称。任务名称仅用于获取和设置任务。与路由不同，名称不用于其他目的。

5.2.2 命令

命令用于检查任务是否与传递的命令行参数匹配，第一个参数是文件名。

任务命令可以包含静态单词、必需参数和可选参数。所有都必须以字母开头，可以由字母数字字符和下划线组成。

必需参数由尖括号 <limit> 包围。可选参数由方括号和尖括号 [<limit>] 包围。参数不能有约束。带有空格的值需要用引号包围。

5.2.3 脚本和回调

任务脚本是非必需的。当任务匹配并且设置了脚本时，此脚本将被直接调用，并且脚本输出不会被缓冲，输出将立即显示。

当您需要在回调中获取任何命令参数时，您需要添加与命令参数同名且精确匹配的回调参数。参数值将为字符串类型。当路由参数为可选时，参数必须具有默认值或允许为null。对于参数:importId，您必须添加参数$importId。参数的顺序无关紧要。

5.2.4 示例

import feed <id>

带有必需参数id的命令。命令将匹配import feed 15，但如果省略必需参数则不会匹配import feed。

process queue [<limit>]

带有可选参数limit的命令。命令将匹配process queue和process queue 10。

generate word cloud <id> latest [<limit>]

带有混合静态单词、必需参数和可选参数的命令。命令将匹配generate word cloud 8 latest 10和generate word cloud 8 latest，但不匹配generate word cloud 8。

5.3 模板和脚本

PHP包含用于使用render方法渲染模板或脚本。对于要渲染的文件，AttoPHP设置为当前对象$this。当设置时，AttoPHP会调用此方法进行布局和视图。当您手动调用render方法时，您必须指定文件当前对象。当您从模板、脚本或回调渲染文件时，您可以将$this作为第二个参数或您自己的对象传递。

5.3.1 根目录

始终设置文件名的完整路径可能会很麻烦，为了解决这个问题，可以调用root方法并传入根目录的路径。

当渲染模板或脚本时，AttoPHP将检查指定的文件名是否是文件。如果是，则渲染该文件并返回。如果不是文件且设置了根目录，则检查目录中是否存在文件。如果存在，则渲染该文件。

5.3.2 内联模板

当在绝对或相对路径中找不到文件时，模板被视为内联模板。这对于将模板存储在数据库中很有用。使用此方法时，PHP渲染不可用，模板将直接通过render方法返回。如果您想解析此模板，可以使用与render方法结合使用的模板解析器。

此方法对脚本不起作用，当找不到脚本时将抛出异常。

5.3.3 布局和视图

AttoPHP有设置布局和视图的方法，分别是layout和view。如果设置了视图，则将先渲染视图，然后渲染布局。渲染的视图将在布局中作为数据容器路径atto.view可用。

5.4 数据容器

AttoPHP有一个数据容器，可以使用data方法调用。您可以将任何喜欢的数据设置到数据容器中，并在每个回调、模板或脚本中使用。设置数据路径必须使用点表示法，以冒号、点或正斜杠作为分隔符。它们可以互换使用，但不推荐这样做。分隔符之间的字符只能由a-z和0-9组成，不区分大小写。

请注意，每个分隔符都会使下一个键成为前一个键的嵌套值。当为路径foo.bar设置值时，将覆盖路径foo.bar.baz的值。当为foo.bar.qux设置值时，它将添加到baz旁边。

点表示法的优点是数据分组。例如，您可以分组所有布局数据，例如layout.title用于标题和layout.description用于描述。

5.5 回调

如果回调返回字符串值，则AttoPHP的run方法将短路该值，并且之后停止执行。

回调的当前对象$this是AttoPHP类。AttoPHP提供的所有功能都在回调中可用。

5.5.1 开始

此回调在配置加载后调用，并有一个名为 $config 的参数。当配置路径模式设置且配置文件加载时，它将包含加载的配置；如果没有设置配置路径模式，则返回空数组。

5.5.2 开始之前

当匹配到路由且在调用路由的可选回调之前，将调用此回调。此回调获取与路由回调相同的参数。

5.5.3 路由

当匹配到路由且指定了回调时，将调用此回调。路由参数可以作为参数指定。例如，参数 :blogId 将作为参数 $blogId 提供。

5.5.4 结束之后

当匹配到路由且在调用路由的可选回调之后，将调用此回调。此回调获取与路由回调相同的参数。

5.5.5 完成

布局和/或视图渲染后，将调用此回调。渲染的内容将作为名为 $render 的参数提供。

5.5.6 错误

发生错误时，将调用此回调。发生的错误将作为名为 $throwable 的参数提供。

5.6 配置

使用 config 方法设置配置路径模式时，在调用启动回调之前将加载文件。使用 PHP 方法 glob() 加载配置文件，并提供了标志 GLOB_BRACE。配置文件必须是 PHP 文件，返回数组，并使用 require 加载。目录将被忽略，文件将非递归合并。

5.7 翻译

使用 translation 方法设置翻译路径模式时，在调用启动回调之前将加载文件。使用 PHP 方法 glob() 加载配置文件，并提供了标志 GLOB_BRACE。翻译文件必须是 PHP 文件，返回数组，并使用 require 加载。目录将被忽略。文件名（不带扩展名）将用作加载文件的区域设置，例如，nl-nl.php 将获得区域设置 nl-nl。

使用 translate 方法进行文本翻译时，可以使用 locale 方法设置区域设置。此外，可以将区域设置作为参数传递给 translate 方法，以覆盖使用 locale 方法设置的全球区域设置。全局区域设置或区域设置参数不必与文件名完全相同。AttoPHP 使用 PHP 方法 locale_lookup 来查找匹配的区域设置。加载的区域设置 nl 可以用于全局或提供的区域设置 nl-be 或 nl-nl。

如果没有设置或提供区域设置、未找到匹配的翻译或文本未作为数组键找到，则返回未更改的文本。

6 控制流程

为了基本了解 AttoPHP 的工作方式，这里解释了快乐路径。

如果设置，则从配置路径模式加载配置文件
如果设置，则从翻译路径模式加载翻译文件
如果设置，则调用启动回调
- 如果返回值为真，则返回值并停止执行
检查请求类型
- 如果是 HTTP
  - 查找匹配的路由
    - 如果找到
      - 将匹配的路由设置为 Atto
      - 如果设置，则将视图设置为 Atto
      - 如果设置，则调用路由回调
        
        如果返回值为真，则返回值并停止执行
  - 如果设置，则渲染视图
    - 将渲染的内容设置为具有路径 atto.view 的数据容器
  - 如果设置，则渲染布局
- 如果是控制台
  - 检查控制台参数
    - 如果指定
      - 解析参数以找到任务
        
        如果找到
        
        如果设置，则调用任务回调
        
        如果返回值为真，则返回值并停止执行
        
        如果设置，则渲染脚本
        
        如果没有找到
        
        将错误和所有可用的任务设置为渲染的内容
    - 如果没有指定
      - 将可用的任务设置为渲染的内容
如果设置，则调用完成回调
- 如果返回值为真，则返回值并停止执行
返回渲染的内容

发生错误时

如果设置，则调用错误回调
- 如果返回值为真，则返回值并停止执行
- 如果回调错误，则返回错误消息并停止执行
返回错误消息

7 错误处理

AttoPHP在运行过程中捕获所有发生的错误。如果没有回调错误，或者回调没有返回一个真值，则会返回原始错误的错误消息。如果在渲染模板或脚本时发生错误，则在返回错误之前会清理输出。因此，错误信息永远不会在HTML元素的深层嵌套中显示，例如。

extendssoftware /

维护者

详细信息