README

注意

此工具已完全重构为可插拔架构，以允许未来的扩展。请注意以下内容

1. 命令行参数名称已更改
2. @routeJS 标签不再支持，已被 [js] 修饰符替换。
3. 文档仍在完善中。

PHP >= 7.0（使用工具），PHP >= 5.4（生成代码）

此开发工具允许用户在控制器类中，使用 DocBlock 格式指定 Fat Free Framework 的路由。此外，它还构建了一个可插拔接口，允许在未来扩展路由生成之外的功能。

示例

class MyFatFreeController {

   /**
    * @route GET @alias: /path/here
    *
    * @param \Base $f3
    * @param array $args
    */
   public function someHandler(\Base $f3, $args) {
      //...
   }

}
 

添加上面的 @route 标签等同于调用

$f3->route('GET @alias: /path/here', 'MyFatFreeController->someHandler');

或指定配置文件中的路由。

工具 f3routes 生成一个适合在 index.php 中 required 的 PHP 文件，并提供了一个安装路由的方法。

function installRoutes($includeDev = true) {
   // ...
}

在 index.php 中引入生成的文件，并在调用 $f3->run(); 之前调用 installRoutes($includeDev);

还可以生成一个 JavaScript 文件，以便在前端使用时轻松构建路由。

标签

以下 DocBlock 标签可以使用

@route 适用于类方法，并遵循与 Fat Free Framework 路由相同的语法，使用以下语法

   @route <METHOD> @alias: path [ajax|cli|sync]

可以在路径中使用可替换令牌。别名是可选的，方括号中的路由修饰符也是如此 [ ]。

f3routes 支持方括号 [ ] 中路由修饰符部分的附加值。这可以是一个逗号分隔的现有 F3 修饰符列表（ajax、cli 或 sync），以及以下附加修饰符

• ttl=<number> 将 $ttl 参数设置为 Base->route()
• kbps=<number> 将 $kbps 参数设置为 Base->route()
• js 在 JavaScript 代码中暴露别名。

修饰符部分的项的顺序不重要，除了 ajax、sync 或 cli 中的最后一个被保留。

以下是一些使用修饰符的 @route 标签示例

   @route GET|POST @alias: /some/path/@id [sync]
   @route GET @alias2: /some/other/path [ajax,js,ttl=3600]

@devroute 与 @route 相同，但仅在调用 installRoutes(true) 时安装。

@routeBase 在类的 DocBlock 中指定，为 @route 或 @devroute 方法中指定的所有路由路径添加路径片段。

@routeMap 和 @devrouteMap 等同于 F3 map 函数，这些为 RESTful 控制器创建路由。这些还允许指定在 JavaScript 输出中暴露的别名，这通过在标签末尾添加 [js] 来启用

/**
 *
 * @routeMap @mapAlias: /company/@id [js]
 *
 */
class Company {
    // ...
}

这等同于

$f3->map('/company/@id', 'Company');

如果设置了 @routeBase，则映射路径也将被添加。

请注意，f3routes 支持提议的 PSR-5 PHPDoc 标准：所有标签都可以使用 f3routes 前缀或命名空间。以下等效

   /**
    *
    * @route GET /mypath
    * @f3routes-route GET /mypath
    * @f3routes\route GET /mypath
    * @\f3routes\route GET /mypath
    */
    public function myHandler(....) {
        // ...

命令行参数

• -f, --force

  强制重新生成整个路由映射。如果没有指定缓存文件，则此选项无效，因为在这种情况下路由表将从头开始生成。

• -v, --verbose

  详细输出。

• --cache-file=<file>

  如果指定，缓存文件将保存生成的路由映射，这样只有发生变化的文件才需要重新解析。对于同一项目的后续调用，应使用相同的缓存文件。

• --source-dir=<目录>

  这是必需的。指定包含PHP文件的目录。此参数可以指定多次。将递归地扫描目录。

• --output-php=<文件>

  这是必需的。指定要写入生成的PHP代码的文件。

• --output-js=<文件>

  这是一个可选参数。如果指定，将生成包含JS代码和路由映射的文件。只有明确标记为JS输出的路由将被输出。

一个用例是将f3routes集成到文件监视器中，并在控制器类修改时实时更新路由。

示例

   f3routes --source-dir=/myprojects/src/controllers \
         --output-php=/myproject/src/generated/routes.php \
         --cache-file=/myproject/src/generated/cache.f3r

安装

f3routes可以通过composer安装

   composer require --dev richardgoldstein/fat-free-routes

可能需要指定最低稳定性，因为这仍然处于开发中。

一旦通过composer安装，f3routes可以在vendor/bin中找到

   ./vendor/bin/f3routes --controller-dir=...

或

   composer exec f3routes ...

我在gulp任务中包含它

var run=require('gulp-run');

// ...

gulp.task('php-routes', ['clean-dist-app'], function(cb) {
    var cmd = new run.Command([
        './vendor/bin/f3routes',
        '--cache-file=./conf/route-cache.f3r',
        '--source-dir=./src/controllers',
        '--output-php=./conf/routes.php',
        '--output-js=./assets/js/generated/routes.js'
    ].join(' '));
   cmd.exec('', cb);
});

TODO

1. 详细说明JavaScript输出
2. 插件文档
3. 由于重构，需要新的单元测试。
4. 更多示例
5. 如何使用渲染的PHP和JavaScript