在 Laravel 中自定义 Stub

这篇文章将向您展示如何自定义用于在您的应用程序中生成各种类的 Stub。虽然手动调整每个生成的类可能很繁琐，但 Laravel 为开发者提供了一种方法来发布和版本控制 Stub，如果您想让生成的类符合您的特定口味，可以使用这种方法。

如果您想跟着一起做，可以使用 Laravel 安装程序、使用 Sail 或者您喜欢的任何其他方法创建一个新的 Laravel 项目。

laravel new stub-demo --git

您可能已经注意到，Laravel 安装程序现在支持 Git 和 GitHub 集成，假设您拥有所需的最低 Git 版本，您应该有一个新的代码库和第一个提交。

版本控制我们的演示项目是可视化我们沿途进行的 Stub 更改以及查看 Laravel 将哪些文件发布到应用程序中的一个很好的方法。

发布 Stub

自定义 Stub 的第一步可能是将您想要单独自定义的 Stub 添加到 Laravel 项目根目录下的 /stubs 文件夹中，或者您可以使用 Artisan 发布所有 Stub。

$ php artisan stub:publish
$ git add stubs
$ git status
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)
 
    new file:   stubs/cast.stub
    new file:   stubs/console.stub
    new file:   stubs/controller.api.stub
    new file:   stubs/controller.invokable.stub
    new file:   stubs/controller.model.api.stub
    new file:   stubs/controller.model.stub
    new file:   stubs/controller.nested.api.stub
    new file:   stubs/controller.nested.stub
    new file:   stubs/controller.plain.stub
    new file:   stubs/controller.stub
    new file:   stubs/factory.stub
    new file:   stubs/job.queued.stub
    new file:   stubs/job.stub
    new file:   stubs/middleware.stub
    new file:   stubs/migration.create.stub
    new file:   stubs/migration.stub
    new file:   stubs/migration.update.stub
    new file:   stubs/model.pivot.stub
    new file:   stubs/model.stub
    new file:   stubs/observer.plain.stub
    new file:   stubs/observer.stub
    new file:   stubs/policy.plain.stub
    new file:   stubs/policy.stub
    new file:   stubs/request.stub
    new file:   stubs/resource-collection.stub
    new file:   stubs/resource.stub
    new file:   stubs/rule.stub
    new file:   stubs/seeder.stub
    new file:   stubs/test.stub
    new file:   stubs/test.unit.stub

如您所见，我们在 app 文件夹中发布了相当多的 Stub！如果您想对它们进行版本控制，我建议您自行决定，您可以保留它们的副本，或者只保留您想要自定义的特定 Stub。

自定义控制器 Stub

Laravel 8.36 引入了在创建控制器时使用 --type 标志的想法，允许您编写自定义 Stub 文件以生成控制器。

<?php
// stubs/controller.custom.stub
namespace {{ namespace }};
 
use {{ rootNamespace }}Http\Controllers\Controller;
use Illuminate\Http\Request;
 
/**
 * Hello from the custom controller stub
 */
class {{ class }}
{
    //
}

添加了自定义 Stub 类之后，可以使用此模板生成控制器。

php artisan make:controller --type=custom MyController

这将生成以下控制器文件

<?php
 
namespace App\Http\Controllers;
 
use Illuminate\Http\Request;
 
/**
 * Hello from the custom controller stub
 */
class MyController
{
    //
}

虽然这种灵活性水平很不错，但我相信大多数开发者都可以满足框架提供的 Stub 的要求。使用新的 --type 标志是手动选择要生成哪个控制器模板的一种方式。

php artisan make:controller --type=plain PlainController

这将根据 Laravel 发布的 stubs/controller.plain.stub 文件生成一个文件。

<?php
 
namespace App\Http\Controllers;
 
use Illuminate\Http\Request;
 
class PlainController extends Controller
{
    //
}

一个合理的方案

假设您想在 Laravel 应用程序中生成的每个文件开头添加一个版权注释。在这种情况下，您可以考虑对所有可用的 Stub 进行版本控制，并在您升级时运行 stub:publish 命令以获取新添加的 Stub。

但是，对于典型用例，您可能只对需要自定义的 Stub 进行版本控制。例如，假设您不希望任何控制器扩展基本 Controller 类；您可以对所有 controller.* Stub 进行版本控制，并在其中添加您的自定义内容，但删除所有其他 Stub。

如果上游 Stub 发生更改怎么办？

假设您对 stub:publish 中的所有 Stub 都进行了版本控制，但您担心 Laravel 框架对核心 Stub 文件进行更新时，您的应用程序将落后。如果您对所有 Stub 都进行了版本控制，您可以始终强制更新以获取最新版本。

以这个例子为例，我们修改一个 Stub 并将其提交到 Git

echo "/* test */" >> stubs/test.stub
git commit -am"Testing stub update"

您已更新测试 Stub 并将更新提交到 Git。假设稍后 Laravel 发布了一些 Stub 更新，您想验证是否有任何更新。

$ php artisan stub:publish --force
$ git diff
diff --git a/stubs/test.stub b/stubs/test.stub
index 834a53d..84c75cb 100644
--- a/stubs/test.stub
+++ b/stubs/test.stub
@@ -20,4 +20,3 @@ class {{ class }} extends TestCase
         $response->assertStatus(200);
     }
 }
-/* test */