Laravel: Как создать функцию хелпер

В Laravel уже есть множество встроенных хелперов, таких, как dd(), abort() и session(). Но по мере роста проекта вы обнаружите потребность в собственных хелперах. В этой статье мы рассмотрим, как создавать и использовать наши собственные вспомогательные PHP функции в Laravel.

Создание функции хелпера

Создание собственного хелпера необходимо начать с создания нового PHP файла, в котором он будет размещён. Давайте создадим файл helpers.php в каталоге app нашего приложения. Кстати, его расположение зависит от личных предпочтений. Ещё одно место, где размещают этот файл — app/Helpers/helpers.php. Вам нужно выбрать каталог, который, по вашему мнению, лучше всего подходит.

Теперь, когда у нас есть файл, мы можем добавить к нему наш хелпер (вспомогательную функцию). В качестве примера для этой статьи мы создадим супер простую функцию, которая преобразует секунды в часы.

Создадим вспомогательную функцию в нашем helper.php:

<?php

if (! function_exists('seconds_to_hours')) {
    function seconds_to_hours(int $seconds): float
    {
        return $seconds / 3600;
    }
}

Как видно из примера наш хелпер — довольно простая функция. Однако, вы можете заметить одну вещь: имя функции написано в snake case/змеином регистре (seconds_to_hours), а не в camel case/верблюжьем регистре (secondsToHours), как вы обычно указываете имена классов. Вам необязательно использовать snake case для имени хелпера, но все хелперы Laravel написаны именно так. Советую использовать этот формат, что бы следовать стандарту. Но это полностью зависит от вас.

Ещё одна вещь, которую вы могли заметить — это то, что мы заключили имя функции в if. Это сделано для того, что бы мы случайно не переопределили уже зарегистрированный хелпер с таким же именем. Например, мы использовали пакет, в котором уже была зарегистрирована функция seconds_to_hours(), это помешало бы нам зарегистрировать нашу собственную функцию с таким же именем. Для решения этого конфликта, мы можем переименовать нашу функцию.

При создании вспомогательных функций важно помнить, что они должны использоваться только как хелперы. На самом деле они не предназначены для выполнения какой-либо бизнес-логики, а скорее для того, что бы привести в порядок ваш код. Конечно, вы можете добавлять к ним сложную логику. Но я бы посоветовал подумать о том, что не будет ли этот код смотреться лучше в другом месте. Таком как сервисный класс, action класс или trait.

Регистрация хелпера/вспомогательной функции

Когда мы создали хелпер, необходимо зарегистрировать его, что бы воспользоваться новой функцией. Для этого, мы можем обновить наш composer.json, чтобы файл загружался во время каждого запроса и был доступен для использования. Это возможно потому, что Laravel включает загрузчик классов composer в файле public/index.php.

В вашем файле composer.json есть раздел autoload который выглядит примерно так:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    }
},

В этом разделе нужно добавить следующие строки, что бы composer знал, что вы хотите загрузить свой файл:

"files": [
    "app/helpers.php"
],

Раздел autoload вашего файла composer.json теперь должен выглядеть так:

"autoload": {
    "files": [
        "app/helpers.php"
    ],
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    }
},

После того как мы в ручную обновили composer.json нам необходимо выполнить следующую команду, что бы выгрузить наш файл автозагрузки и создать новый:

composer dump-autoload

Использование хелпера

Поздравляю! Ваш хелпер должен быть полностью настроен и готов к использованию. Что бы использовать его, вы можете просто вставить в код:

seconds_to_hours(331);

Поскольку он зарегистрирован как глобальная функция, вы можете использовать его в контроллерах, сервисных классах и даже других хелперах. Что мне больше всего нравиться в хелперах, это возможность использовать их в шаблонах Blade. Например, у нас есть класс TimeServiceClass, содержащий метод secondsToHours(), выполняющий то же самое, что и наша вспомогательная функция. Если бы мы использовали сервисный класс в нашем шаблоне Blade, нам, пришлось бы сделать что-то вроде этого:

{{ \App\Services\TimeService::secondsToHours(331) }}

Как вы понимаете, если бы это использовалось в нескольких местах на странице, то сильно бы ухудшило визуальное восприятие кода шаблона.

Идём дальше

Узнав как можно регистрировать хелперы, мы рассмотрим ещё один шаг вперёд. По мере роста ваших Laravel проектов, вы обнаружите, что у вас большое количество вспомогательных функций, которые находятся в одном файле. Как вы понимаете, этот файл будет выглядеть неорганизованно. Нам следует подумать о разделении наших хелперов на отдельные файлы.

Представим, что у нас множество хелперов в файле app/helpers.php; некоторые из них связаны с деньгами, некоторые со временем, а не которые с пользовательскими настройками. Мы могли бы начать разделение этих функций на отдельные файлы, такие как: app/Helpers/money.php, app/Helpers/time.php и app/Helpers/settings.php. Значит мы можем удалить наш файл app/helpers.php, потому что он не нужен.

После этого нам нужно обновить наш composer.json так же, как и раньше, но загружая 3 новых файла:

"autoload": {
    "files": [
        "app/Helpers/money.php",
        "app/Helpers/settings.php",
        "app/Helpers/time.php",
    ],
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    }
},

Не забывайте сбрасывать дамп автозагрузки composer выполняя следующую команду:

composer dump-autoload

Вы можете продолжать использовать свои хелперы, и у вас есть возможность разбивать их на логически разделённые файлы.

Вывод

Надеюсь, эта статья показала вам, как создавать свои хелперы/вспомогательные функции PHP для ваших проектов Laravel. Помните, что не следует их использовать для сложной бизнес-логики и следует рассматривать, как возможность упорядочить вспомогательные фрагменты кода.