在 Laravel 项目中创建自己的 PHP 助手

Laravel 提供了许多优秀的 助手函数，这些函数对于执行诸如处理数组、文件路径、字符串和路由等操作非常方便，除此之外还有像备受喜爱的 dd() 函数这样的函数。

您还可以通过使用 Composer 自动导入它们，为您的 Laravel 应用程序和 PHP 包定义自己的助手函数集。

如果您是 Laravel 或 PHP 的新手，让我们一起了解一下如何创建自己的助手函数，这些函数会由 Laravel 自动加载。

#在 Laravel 应用程序中创建助手文件

您可能希望包含助手函数的第一个场景是在 Laravel 应用程序的上下文中。根据您的偏好，您可以随意组织助手文件的位置，但是这里有一些建议的位置

• app/helpers.php
• app/Http/helpers.php

我更喜欢将我的助手文件放在应用程序命名空间根目录下的 app/helpers.php 文件中。

#自动加载

要使用您的 PHP 助手函数，您需要在运行时将它们加载到您的程序中。在我职业生涯的早期，在文件的顶部看到这种代码并不罕见

require_once ROOT . '/helpers.php';

PHP 函数无法自动加载。但是，我们有一个比使用 require 或 require_once 更好的解决方案，那就是使用 Composer。

如果您创建一个新的 Laravel 项目，您将在 composer.json 文件中看到 autoload 和 autoload-dev 键

"autoload": {
    "classmap": [
        "database/seeds",
        "database/factories"
    ],
    "psr-4": {
        "App\\": "app/"
    }
},
"autoload-dev": {
    "psr-4": {
        "Tests\\": "tests/"
    }
},

如果您想添加一个助手文件，Composer 有一个 files 键（它是一个文件路径数组），您可以在 autoload 中定义它

"autoload": {
    "files": [
        "app/helpers.php"
    ],
    "classmap": [
        "database/seeds",
        "database/factories"
    ],
    "psr-4": {
        "App\\": "app/"
    }
},

将新路径添加到 files 数组后，您需要转储自动加载器

composer dump-autoload

现在，在每次请求时，helpers.php 文件都会自动加载，因为 Laravel 在 public/index.php 中需要 Composer 的自动加载器

require __DIR__.'/../vendor/autoload.php';

#定义函数

在您的助手类中定义函数是最简单的部分，不过有一些注意事项。所有 Laravel 助手文件都包含一个检查，以避免函数定义冲突

if (! function_exists('env')) {
    function env($key, $default = null) {
        // ...
    }
}

这可能会很棘手，因为您可能会遇到这种情况，您使用了一个您没有预期的函数定义，这取决于哪个函数先被定义。

我更喜欢在我的应用程序助手函数中使用 function_exists 检查，但是如果您在应用程序上下文中定义助手函数，您可以省略 function_exists 检查。

通过跳过检查，您将在任何时候遇到冲突，只要您的助手函数重新定义了函数，这可能会有用。

在实践中，冲突并不像您想象的那么频繁，您应该确保您定义的函数名称不要过于通用。您还可以为函数名称添加前缀，以降低它们与其他依赖项发生冲突的可能性。

#助手示例

我喜欢 Rails 路径和 URL 助手，这些助手在定义资源路由时可以免费获得。例如，一个 photos 资源路由将公开路由助手，如 new_photo_path、edit_photo_path` 等。

当我使用 Laravel 中的资源路由时，我喜欢添加一些助手函数，这些函数使在模板中定义路由更容易。在我的实现中，我喜欢使用一个 URL 助手函数，我可以向它传递一个 Eloquent 模型，并使用我定义的约定获取一个资源路由，例如

create_route($model);
edit_route($model);
show_route($model);
destroy_route($model);

以下是如何在您的 app/helpers.php 文件中定义 show_route 函数（其他函数看起来类似）

if (! function_exists('show_route')) {
    function show_route($model, $resource = null)
    {
        $resource = $resource ?? plural_from_model($model);
 
        return route("{$resource}.show", $model);
    }
}
 
if (! function_exists('plural_from_model')) {
    function plural_from_model($model)
    {
        $plural = Str::plural(class_basename($model));
 
        return Str::kebab($plural);
    }
}

plural_from_model() 函数只是一些可重复使用的代码，助手路由函数使用这些代码根据我喜欢的命名约定预测路由资源名称，这个约定是模型的连字符分隔的复数形式。

例如，以下是一个从模型派生的资源名称示例

$model = new App\LineItem;
plural_from_model($model);
// => line-items
 
plural_from_model(new App\User);
// => users

使用此约定，您可以在 routes/web.php 中这样定义资源路由

Route::resource('line-items', 'LineItemsController');
Route::resource('users', 'UsersController');

然后，在您的 Blade 模板中，您可以执行以下操作

<a href="{{ show_route($lineItem) }}">
    {{ $lineItem->name }}
</a>

这将产生类似于以下 HTML 的内容

<a href="http://localhost/line-items/1">
    Line Item #1
</a>

#包

您的 Composer 包也可以使用助手文件来存储您想要提供给使用您的包的项目的任何助手函数。

您将在包的 composer.json 文件中采用相同的方法，定义一个带有助手文件数组的 files 键。

必须在助手函数周围添加 function_exists() 检查，以确保使用您的代码的项目不会因为命名冲突而崩溃。

您应该选择适合您的包的唯一函数名称，如果您担心函数名称过于通用，可以考虑使用简短的前缀。

#了解更多

查看 Composer 的 自动加载 文档，以了解更多关于包含文件以及自动加载类的通用信息。