/ laravel

Создание собственных функций хелперов в Laravel

В Laravel из коробки встроено достаточно много функций-хелперов, которые мы можем вызывать в любом месте приложения. Они упрощают работу с массивами, объектами, маршрутами, строками, env-переменными и прочими компонентами фреймворка.

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

Давайте рассмотрим, каких хелперы уже существуют в фреймворке, и какие есть способы добавления новых.

Ранее, я уже публиковал несколько статей на тему того, какие хелперы сделают вашу жизнь легче а так же, 10 хелперов, которые обязательно нужно знать.

Хелперы в Laravel

Как упоминалось выше, в Laravel уже доступно много хелперов, которые вы можете использовать в вашем проекте. Список всех доступных функций можете посмотреть на странице документации.

Массивы & Объекты

В этой группе сосредоточены хелпперы, упрощающие работу с массивами и объектами. Это группа содержит функции объединения 2 массивов, слияние многомерных массивов в один массив, позвращение первого элемента массива, и много других методов по работе с массивами и объектами.

Путь

Эта группа хелпперов упрощает работу с путями проекта к директориям приложения. Эти функции возвращают абсолютные пути к различным каталогам вашего приложения, таким как app, config, public, resource, storage и базовый путь вашего приложения.

URL-адреса

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

Остальные хелперы

Эта категория хелпперов содержит функции для работы с HTTP-статусами, редиректами, контейнером, аутентификацией, кешем и т.д.

Создание собственного файла с хелпперами

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

Вы можете разместить файл с хелпперами в любом удобном для вам месте, однако я предпочитаю хранить свои вспомогательные функции в файле helpers.php, папки app/Helpers.

Создание хелпера

Давайте создадим папку Helpers в app и создадим файл helpers.php со следующим содержимым:

<?php

if (!function_exists('format_bytes')) {
function format_bytes($bytes, $precision = 2) {
$units = array('B', 'KB', 'MB', 'GB', 'TB');

    $bytes = max($bytes, 0); 
    $pow = floor(($bytes ? log($bytes) : 0) / log(1024)); 
    $pow = min($pow, count($units) - 1); 
    $bytes /= pow(1024, $pow);
    
    return round($bytes, $precision) . ' ' . $units[$pow]; 
} 

}

if(!function_exists('str_plural_ru'))
{
function str_plural_ru($n, $forms)
{
return $n%10==1&&$n%100!=11?$forms[0]:($n%10>=2&&$n%10<=4&&($n%100<10||$n%100>=20)?$forms[1]:$forms[2]);
}
}

Если вы, для написания хелперов будете использовать класс, где его методы будут являться хелперами, вам нужно объявить указанное пространства имен:

namespace App\Helpers;

Если вы не используете объявление пространства имен, эти функции станут глобально доступными, и вы можете использовать их в любом месте, даже не указывая пространство имён. Все встроенные функции хелперы вLaravel определены без пространства имен. Кроме того, вспомогательный класс также будет доступен во всем мире. Поэтому, если вы хотите использовать хелперы без указания пространства имен, просто удалите эту строку с namespace.

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

if (!function_exists('format_bytes')) {
    function format_bytes($bytes, $precision = 2)
    {
        // ...
    }
}

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

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

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

  • Вы можете автоматически загрузить созданный файл с хелперами с помощью composer. Затем вы можете использовать эти функции в любом месте вашего приложения.
  • Вы также можете использовать Laravel Service Provider для регистрации этого файла. А фреймворк уже сам загрузит его вместе с другими зависимостями.
  • Вы также можете использовать composer-пакет, который предоставляет вам все эти функции (если он существует, конечно же).

Теперь же, давайте посмотрим, как использовать все эти методы на практике.

Использование Composer-а для автозагрузки файлов

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

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

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

После изменения файла composer.json и добавления нового пути к массиву файлов вам необходимо выгрузить автозагрузчик. Для этого просто запустите команду из терминала в каталоге вашего проекта: composer dump-autoload

Использование Service Provider для загрузки файла

Давайте посмотрим, как вы можете использовать Service Provider-ы для автозагрузки файла хелперов. Перейдите в командную строку в корне вашего приложения и выполните следующую команду, чтобы создать новый Service Provider: php artisan make:provider HelpersLoaderProvider

После выполнения которой, вы увидите сообщение: Provider created successfully.

Как только Service Provider будет успешно создан, откройте этот файл (который появится в папке app/Providers). В методе register нужно описать код регистрации хелперов.

public function register()
{
$file = app_path('Helpers/helpers.php');
if (file_exists($file)) {
require_once($file);
}
}

В методе register мы должны подключить все зависимости. В большом проекте, возможно, у вас будет несколько вспомогательных файлов с хелперами в каталоге, и вы захотите подключить их всех. Вы можете изменить метод register, как указано ниже, и ваш Service Provider загрузит все файлы из каталога Helpers.
public function register()
{
foreach (glob(app_path() . '/Helpers/*.php') as $file) {
require_once($file);
}
}

Этот код подключит все файлы, которые находятся в директории app/Helpers. Теперь, когда наш Service Provider полностью дописан, нам нужно зарегистрировать его, чтобы Laravel автоматически загружал его во время загрузки приложения. Для этого нужно перейти в config / app.php и добавьте следующую строку в массив providers:
App\Providers\HelpersLoaderProvider::class,

Если вы создали вспомогательный файл в виде класса с пространством имён, который имеет методы в виде хелперов, вы можете использовать этот класс без пространства имён, определив псевдоним. Сделать это вы можете, добавив следующий код в конец массива aliases в файле config / app.php.
'Helper' => App\Helpers\Helper::class,

Добавив это в массив секцию aliases, вы сможете вызвать любой их хелперов, используя ключевое слово Helper. И это всё, что можно было поведать о создании собственных хелперов с помощью Service Provider-ов.

Использование стороннего пакета

Вы также можете использовать сторонние пакеты, подключая их через composer. На Github есть библиотека упрощающая создание Laravel хелперов. Вы можете установить её через composer, запустив эту команду из корня вашего приложения в консоли.
composer require browner12/helpers

После выполнения необходимых шагов вы можете использовать эту команду для создания файлов с хелперами.
php artisan make:helper MyStrHelper

Эта команда создаст файл MyStrHelper.php в App \ Helpers, куда вы можете легко добавить все свои вспомогательные функции.

Helper в экшене контроллера

Теперь, когда мы определили необходимые хелперы в нашем файле, подключили, мы можем использовать их очень легко. Для теста перейдите к файлу маршрутов route / web.php и используйте эту функцию для маршрута домашней страницы. Например, код файла route / web.php будет выглядеть:
<?php

Route::get('/', function () {
return format_bytes(1024*1024);
});

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

Резюме

Хоть и в примерах на официальном сайте и показан пример подключения файла хелпера через composer, секцию autoload, я считаю этот метод недостаточно удобным и "чистым". Более удобным способом является подгрузка файлов хелперов через Laravel Service Provider. И, если вас интересовала лучшая практика по созданию собственных функций хелперов, то второй вариант как раз и является таковым.

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