README

Stuble 是一个使用 PHP 编建的命令行工具，用于简化处理存根。Stuble 将收集存根文件中的参数并询问您这些参数。因此，您无需为每个存根文件编写脚本。

需求

PHP >= 8.0.3
Composer

安装

composer global require emsifa/stuble

确保您已将 composer 的 bin 目录注册到您的 PATH 变量中。您可以在此处了解更多信息。

用法示例

在开始之前，您需要知道 stuble 从两个位置扫描存根文件。

本地源：您想使用 stuble 命令的任何地方的 stubs 目录。
全局源：STUBLE_HOME 路径内的 stubs 目录。

如果在两个源中找到相同的存根文件，stuble 将使用本地存根文件。

创建存根文件

在您的 cmd/终端中，转到您想尝试 stuble 的目录。

例如，我们位于 /home/me/coding/try-stuble。

然后在那个目录中创建 stubs/model.stub 文件。

<?php

namespace {? model_namespace["App\Models"] ?};

use Illuminate\Database\Eloquent\Model;

/**
 * Model {? entity ?}
 */
class {? entity.pascal ?} extends Model
{

    protected $table = "{? entity.snake.plural ?}";

}

从存根生成文件

回到 cmd/终端，运行以下命令

stuble make model

然后 stuble 将扫描 stubs/model.stub（在本例中为 model_namespace 和 entity）中所需的参数，然后询问这些参数的值，最后 stuble 将询问您要保存文件的位置。

例如，如果您填写

model_namespace = App\Models
entity = product category
path = app/Models/ProductCategory.php

Stuble 将生成 app/Models/ProductCategory.php，内容如下

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

/**
 * Model product category
 */
class ProductCategory extends Model
{

    protected $table = "product_categories";

}

如果您再次查看您的 model.stub，您可能会注意到以下内容

被 {?...?} 包围的第一个单词是 stuble 将会询问的参数。
被 ["..."] 包围的单词，如 App\Models，是参数的默认值。
pascal、snake、plural 是修改您的参数值的过滤器。
您可以使用 . 来分隔每个过滤器（如 snake.plural）。

您需要了解的事项

使用全局源

如果您想使用全局源，您应该在环境变量中定义 STUBLE_HOME。

对于 Linux，您可以将以下行添加到您的 ~/.bashrc 或 ~/.zshrc 文件中。

export STUBLE_HOME=/home/{your_username}/stuble

然后在该路径下创建 stubs 目录。

在目录中生成存根

只需在 stuble make 命令中将 path/to/directory 替换为 path/to/filename。Stuble 将收集该目录中存根文件中的参数，然后生成结果文件。

例如，如果您的 stubs 目录结构如下

└── laravel-scaffolds
    ├── controller.stub
    ├── factory.stub
    ├── migration.stub
    ├── model.stub
    ├── resource.stub
    ├── store-request.stub
    └── update-request.stub

您可以使用 stuble make laravel-scaffolds 生成 controller、factory、migration、model、resource、store-request 和 update-request。

在存根文件中定义输出文件路径

如果您有自己的标准文件路径并且不想在每次执行 stuble make 时都让 stuble 询问输出文件路径，您可以在存根文件的最顶部添加以下行

===
path = "define/your/relative/path/here.ext"
===

示例

===
path = "app/Models/{? entity.pascal ?}.php"
===
<?php

namespace App\Models;

class {? entity.pascal ?} extends Model
{

    protected $table = "{? entity.snake.plural ?}";

}

现在，如果您从该存根创建文件，stuble 不会询问您输出文件路径。相反，stuble 将自动使用该格式放置文件。

附加到现有文件

您也可以将现有文件附加到新文件，而不是每次创建存根文件时都创建新文件。

例如，您想将一些代码附加到 Laravel 路由文件中

===
[append]
file = "routes/web.php"
===
Route::resource('{? entity.kebab ?}', '{? entity.pascal ?}Controller');

然后每次您创建该存根文件时，Route::resource(...) 将附加到 routes/web.php 文件的底部。

你现在可能已经意识到，位于 === 和 === 之间的代码是 TOML 格式。实际上，它也可以是 YAML 格式 :)

您还可以将代码追加到特定的行，或者在某些代码之后/之前。

追加到特定行

===
[append]
file = "routes/web.php"
line = 15
===
Route::resource('{? entity.kebab ?}', '{? entity.pascal ?}Controller');

现在，无论您创建哪个 stub 文件，Route::resource(...) 都会始终追加到 routes/web.php 文件的第 15 行。

追加到特定代码之后

===
[append]
file = "routes/web.php"
after = "// Generated by Stuble"
===
Route::resource('{? entity.kebab ?}', '{? entity.pascal ?}Controller');

现在，无论您创建哪个 stub 文件，Route::resource(...) 都会始终追加到包含 "// Generated by Stuble" 的行之后。

追加到特定代码之前

===
[append]
file = "routes/web.php"
before = "// Code aboves was generated by Stuble"
===
Route::resource('{? entity.kebab ?}', '{? entity.pascal ?}Controller');

现在，无论您创建哪个 stub 文件，Route::resource(...) 都会始终追加到包含 "// Code aboves was generated by Stuble" 的行之前。

内置过滤器

创建自己的过滤器

在这个例子中，我们将添加 substr 过滤器。

在你的 stubs 目录下，创建文件 stuble-init.php。写入以下代码

<?php

$stuble->filter('substr', function (string $value, int $start, int $length = null) {
    return substr($value, $start, $length);
});

然后你可以这样使用它。

// sample.stub

Your param: {? your_param ?}
Your param after substr: {? your_param.substr(0, 6) ?}

您可以使用该过滤器在该目录下的所有 stubs 文件中，包括子目录。如果您在子目录中也有相同的过滤器，Stuble 会覆盖它。

显示可用 stubs 列表

您可以使用 stuble ls 命令来显示可用 stubs 列表。

例如

# Show list stubs in both global and local sources
stuble ls

# Show list stubs in global source only
stuble ls --global
# or
stuble ls -G

# Show list stubs in local source only
stuble ls --local
# or
stuble ls -L

# Show list stubs contains 'laravel'
stuble ls laravel

# Show list stubs contains 'laravel' in global source only
stuble ls laravel -G

输出结果

如果您想输出结果而不是保存它，可以在 stuble make 命令中使用 --dump。

例如

stuble make laravel-scaffolds --dump

将现有文件转换为 stubs 文件（实验性）

如果您想将一些文件转换为 stubs 文件，可以使用 stublify 命令。

例如，您有一个包含用户 CRUD 的 modules/users 目录，您可以通过运行以下命令将其转换为 stubs

stuble stublify modules/users my-module

这将把 modules/users 目录中的文件转换为 stubs/my-modules 目录下的 .stub 文件。

运行此命令后，Stuble 将询问您是否要使用参数替换某些文本。Stuble 也能检测到您的文本的其他格式。例如，您想将 "User" 替换为 entity。Stuble 将询问您是否要将 "Users" 替换为 entity.plural，将 "users" 替换为 entity.plural.lower 等。

emsifa / stuble

维护者

详细信息