Как создать хелпер в Laravel

Russian (Pусский) translation by Masha Kolesnikova (you can also view the original English article)

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

Laravel включает в себя множество глобальных «вспомогательных» функций PHP. Многие из этих функций используются самим фреймворком; Однако вы можете использовать их в своих приложениях, если сочтете их удобными.

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

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

Хелперы в Ларавеле

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

Массивы

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

Пути к папкам и файлам

Я считаю, что хелперы из этой категории наиболее полезные. Они возвращают полностью квалифицированный путь из разных каталогов, таких как app, storage, config и т.п. Бьюсь об заклад, вы уже используете большинство этих хелперов в своем приложении Laravel.

Строки

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

URL-адрес

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

Разное

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

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

Создайте свой первый пользовательский хелпер

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

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

Я предполагаю, что у вас есть таблица пользователей в вашей базе данных, и у нее есть как минимум два поля: userid и username.

Скелет хелпера Laravel

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

App/Helpers/Envato/User.php: Это наш вспомогательный файл, который содержит логику нашего хелпера.
App/Providers/EnvatoServiceProvider.php: это настраиваемый файл поставщика услуг, который загружает наш пользовательский вспомогательный файл.
config/app.php: В этом файле мы объявим нашего специализированного поставщика услуг, а также здесь мы определим псевдоним для нашего хелпера, чтобы нам не пришлось нашего помощника.
routes/web.php: довольно стандартный файл маршрута Laravel, где мы будем тестировать нашего хелпера.

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

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

Итак, двигаемся дальше, создайте каталог Helpers/Envato в директории app и создайте файл User.php со следующим содержимым. Конечно, вы можете разместить его непосредственно в каталоге app или app/Helpers, но дополнительный уровень вложенности позволяет нам удобно организовать наших хелперов, особенно когда у вас их будет много.

<?php
//app/Helpers/Envato/User.php
namespace App\Helpers\Envato;

use Illuminate\Support\Facades\DB;

class User {
    /**
     * @param int $user_id User-id
     * 
     * @return string
     */
    public static function get_username($user_id) {
        $user = DB::table('users')->where('userid', $user_id)->first();
        
        return (isset($user->username) ? $user->username : '');
    }
}

Файл начинается с довольно стандартного объявления пространства имен:

namespace App\Helpers\Envato;

Цель нашего пользовательского хелпера - получить имя пользователя на основе идентификатора пользователя. Следовательно, нам нужно взаимодействовать с базой данных, поэтому мы должны подключить DB Facade.

use Illuminate\Support\Facades\DB;

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

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

$user = DB::table('users')->where('userid', $user_id)->first();

Объект $user хранит запись базы данных с соответствующим идентификатором пользователя. Наконец, метод возвращает имя пользователя в качестве ответа в следующем выражении.

return (isset($user->username) ? $user->username : '');

Это касается нашего вспомогательного файла.

Теперь мы создали наш вспомогательный файл, но вопрос в том, как вы собираетесь его использовать? Мне приходят два быстрых решения:

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

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

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

$php artisan make:provider EnvatoServiceProvider 
Provider created successfully.

Вы должны увидеть сообщение, подтверждающее, что поставщик успешно был создан в каталоге app/Providers.

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

public function register()
{
    require_once app_path() . '/Helpers/Envato/User.php';
}

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

Вот как должен выглядеть файл app/Providers/EnvatoServiceProvider.php после внесенных изменений.

<?php
// app/Providers/EnvatoServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class EnvatoServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap the application services.
     *
     * @return void
     */
    public function boot()
    {
        //
    }

    /**
     * Register the application services.
     *
     * @return void
     */
    public function register()
    {
        require_once app_path() . '/Helpers/Envato/User.php';
    }
}

Так что пока все хорошо. У нас есть наш пользовательский хелпер и поставщик услуг для него.

Затем нам нужно сообщить Laravel о нашем поставщике услуг, чтобы он мог загрузить его во время начальной загрузки. Давайте откроем файл config/app.php и добавим следующую запись в массив providers в конце.

App\Providers\EnvatoServiceProvider::class,

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

'EnvatoUser' => App\Helpers\Envato\User::class,

Определив эту запись, мы можем вызвать наш хелпер, используя ключевое слово EnvatoUser. Довольно удобно, не правда ли? Для справки, вот полный файл config/app.php.

<?php
// config/app.php
return [

    /*
    |--------------------------------------------------------------------------
    | Application Name
    |--------------------------------------------------------------------------
    |
    | This value is the name of your application. This value is used when the
    | framework needs to place the application's name in a notification or
    | any other location as required by the application or its packages.
    */

    'name' => 'Laravel',

    /*
    |--------------------------------------------------------------------------
    | Application Environment
    |--------------------------------------------------------------------------
    |
    | This value determines the "environment" your application is currently
    | running in. This may determine how you prefer to configure various
    | services your application utilizes. Set this in your ".env" file.
    |
    */

    'env' => env('APP_ENV', 'production'),

    /*
    |--------------------------------------------------------------------------
    | Application Debug Mode
    |--------------------------------------------------------------------------
    |
    | When your application is in debug mode, detailed error messages with
    | stack traces will be shown on every error that occurs within your
    | application. If disabled, a simple generic error page is shown.
    |
    */

    'debug' => env('APP_DEBUG', false),

    /*
    |--------------------------------------------------------------------------
    | Application URL
    |--------------------------------------------------------------------------
    |
    | This URL is used by the console to properly generate URLs when using
    | the Artisan command line tool. You should set this to the root of
    | your application so that it is used when running Artisan tasks.
    |
    */

    'url' => env('APP_URL', 'https://localhost'),

    /*
    |--------------------------------------------------------------------------
    | Application Timezone
    |--------------------------------------------------------------------------
    |
    | Here you may specify the default timezone for your application, which
    | will be used by the PHP date and date-time functions. We have gone
    | ahead and set this to a sensible default for you out of the box.
    |
    */

    'timezone' => 'UTC',

    /*
    |--------------------------------------------------------------------------
    | Application Locale Configuration
    |--------------------------------------------------------------------------
    |
    | The application locale determines the default locale that will be used
    | by the translation service provider. You are free to set this value
    | to any of the locales which will be supported by the application.
    |
    */

    'locale' => 'en',

    /*
    |--------------------------------------------------------------------------
    | Application Fallback Locale
    |--------------------------------------------------------------------------
    |
    | The fallback locale determines the locale to use when the current one
    | is not available. You may change the value to correspond to any of
    | the language folders that are provided through your application.
    |
    */

    'fallback_locale' => 'en',

    /*
    |--------------------------------------------------------------------------
    | Encryption Key
    |--------------------------------------------------------------------------
    |
    | This key is used by the Illuminate encrypter service and should be set
    | to a random, 32 character string, otherwise these encrypted strings
    | will not be safe. Please do this before deploying an application!
    |
    */

    'key' => env('APP_KEY'),

    'cipher' => 'AES-256-CBC',

    /*
    |--------------------------------------------------------------------------
    | Logging Configuration
    |--------------------------------------------------------------------------
    |
    | Here you may configure the log settings for your application. Out of
    | the box, Laravel uses the Monolog PHP logging library. This gives
    | you a variety of powerful log handlers / formatters to utilize.
    |
    | Available Settings: "single", "daily", "syslog", "errorlog"
    |
    */

    'log' => env('APP_LOG', 'single'),

    'log_level' => env('APP_LOG_LEVEL', 'debug'),

    /*
    |--------------------------------------------------------------------------
    | Autoloaded Service Providers
    |--------------------------------------------------------------------------
    |
    | The service providers listed here will be automatically loaded on the
    | request to your application. Feel free to add your own services to
    | this array to grant expanded functionality to your applications.
    |
    */

    'providers' => [

        /*
         * Laravel Framework Service Providers...
         */
        Illuminate\Auth\AuthServiceProvider::class,
        Illuminate\Broadcasting\BroadcastServiceProvider::class,
        Illuminate\Bus\BusServiceProvider::class,
        Illuminate\Cache\CacheServiceProvider::class,
        Illuminate\Foundation\Providers\ConsoleSupportServiceProvider::class,
        Illuminate\Cookie\CookieServiceProvider::class,
        Illuminate\Database\DatabaseServiceProvider::class,
        Illuminate\Encryption\EncryptionServiceProvider::class,
        Illuminate\Filesystem\FilesystemServiceProvider::class,
        Illuminate\Foundation\Providers\FoundationServiceProvider::class,
        Illuminate\Hashing\HashServiceProvider::class,
        Illuminate\Mail\MailServiceProvider::class,
        Illuminate\Notifications\NotificationServiceProvider::class,
        Illuminate\Pagination\PaginationServiceProvider::class,
        Illuminate\Pipeline\PipelineServiceProvider::class,
        Illuminate\Queue\QueueServiceProvider::class,
        Illuminate\Redis\RedisServiceProvider::class,
        Illuminate\Auth\Passwords\PasswordResetServiceProvider::class,
        Illuminate\Session\SessionServiceProvider::class,
        Illuminate\Translation\TranslationServiceProvider::class,
        Illuminate\Validation\ValidationServiceProvider::class,
        Illuminate\View\ViewServiceProvider::class,

        /*
         * Package Service Providers...
         */
        Laravel\Tinker\TinkerServiceProvider::class,

        /*
         * Application Service Providers...
         */
        App\Providers\AppServiceProvider::class,
        App\Providers\AuthServiceProvider::class,
        // App\Providers\BroadcastServiceProvider::class,
        App\Providers\EventServiceProvider::class,
        App\Providers\RouteServiceProvider::class,
        App\Providers\EnvatoServiceProvider::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Class Aliases
    |--------------------------------------------------------------------------
    |
    | This array of class aliases will be registered when this application
    | is started. However, feel free to register as many as you wish as
    | the aliases are "lazy" loaded so they don't hinder performance.
    |
    */

    'aliases' => [

        'App' => Illuminate\Support\Facades\App::class,
        'Artisan' => Illuminate\Support\Facades\Artisan::class,
        'Auth' => Illuminate\Support\Facades\Auth::class,
        'Blade' => Illuminate\Support\Facades\Blade::class,
        'Broadcast' => Illuminate\Support\Facades\Broadcast::class,
        'Bus' => Illuminate\Support\Facades\Bus::class,
        'Cache' => Illuminate\Support\Facades\Cache::class,
        'Config' => Illuminate\Support\Facades\Config::class,
        'Cookie' => Illuminate\Support\Facades\Cookie::class,
        'Crypt' => Illuminate\Support\Facades\Crypt::class,
        'DB' => Illuminate\Support\Facades\DB::class,
        'Eloquent' => Illuminate\Database\Eloquent\Model::class,
        'Event' => Illuminate\Support\Facades\Event::class,
        'File' => Illuminate\Support\Facades\File::class,
        'Gate' => Illuminate\Support\Facades\Gate::class,
        'Hash' => Illuminate\Support\Facades\Hash::class,
        'Lang' => Illuminate\Support\Facades\Lang::class,
        'Log' => Illuminate\Support\Facades\Log::class,
        'Mail' => Illuminate\Support\Facades\Mail::class,
        'Notification' => Illuminate\Support\Facades\Notification::class,
        'Password' => Illuminate\Support\Facades\Password::class,
        'Queue' => Illuminate\Support\Facades\Queue::class,
        'Redirect' => Illuminate\Support\Facades\Redirect::class,
        'Redis' => Illuminate\Support\Facades\Redis::class,
        'Request' => Illuminate\Support\Facades\Request::class,
        'Response' => Illuminate\Support\Facades\Response::class,
        'Route' => Illuminate\Support\Facades\Route::class,
        'Schema' => Illuminate\Support\Facades\Schema::class,
        'Session' => Illuminate\Support\Facades\Session::class,
        'Storage' => Illuminate\Support\Facades\Storage::class,
        'URL' => Illuminate\Support\Facades\URL::class,
        'Validator' => Illuminate\Support\Facades\Validator::class,
        'View' => Illuminate\Support\Facades\View::class,
        'EnvatoUser' => App\Helpers\Envato\User::class,
    ],

];

Мы почти сделали это! Мы сделали всю тяжелую работу, чтобы добраться до этого места, и теперь мы можем воспользоваться преимуществами нашего специального хелпера.

Ваш первый пользовательский хелпер в действии

Опять же, чтобы все было просто и понятно, мы определим базовый маршрут Laravel и вызовем наш хелпер!

Идем дальше и создаем файл route/web.php со следующим содержимым.

<?php
// routes/web.php
/*
|--------------------------------------------------------------------------
| Web Routes
|--------------------------------------------------------------------------
|
| Here is where you can register web routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| contains the "web" middleware group. Now create something great!
|
*/

Route::get('/envato-user-helper-demo', function () {
    return EnvatoUser::get_username(1);
});

Это вообще нуждается в объяснении? Мы только что вызвали пользовательский помощник по сокращению EnvatoUser::get_username, и он должен вернуть имя пользователя.

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

На этом наша история заканчивается сегодня.

Вывод

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

Надеюсь, вам понравилась статья, и она поможет вам создавать собственные пользовательские хелперы в повседневной разработке приложений Laravel.

Не стесняйтесь оставлять свои комментарии и запросы в ленте ниже. Я также комментирую мой Twitter и отвечаю на них, как только могу!