Справочник вспомогательных функций

Flute CMS предоставляет множество вспомогательных функций (helpers), которые упрощают разработку модулей. Эти функции доступны глобально и могут использоваться в контроллерах, шаблонах и сервисах.

Основные категории хелперов:

Сервис-контейнер и DI
Работа с базой данных и ORM
HTTP запросы и ответы
Шаблоны и представления
Аутентификация и авторизация
Локализация и переводы
Кеширование и производительность
Файловая система и ассеты
События и логирование

Быстрая справка

Функция	Описание	Пример использования
`rep()`	Получение репозитория ORM	`rep(User::class)->findByPK(1)`
`transaction()`	Создание транзакции БД	`transaction($entity)->run()`
`request()`	Текущий HTTP запрос	`request()->get('page', 1)`
`response()`	Создание HTTP ответа	`response()->json($data)`
`user()`	Текущий пользователь	`user()->can('permission')`
`template()`	Система шаблонов	`template()->render('view', $data)`
`route()`	Генерация URL маршрута	`route('blog.show', ['id' => 1])`
`url()`	Генерация URL	`url('/path/to/resource')`
`active()/is_active()`	Активный маршрут (классы/проверка)	`active('admin.*', 'active')`
`__()`	Перевод строки	`__('blog.welcome')`
`translation()`	Сервис переводов	`translation()->setLocale('ru')`
`cache()`	Система кеширования	`cache()->get('key', 'default')`
`config()`	Конфигурация	`config('app.name')`
`events()`	Система событий	`events()->dispatch($event)`
`logs()`	Логирование	`logs()->info('message')`
`session()`	Работа с сессией	`session()->set('key', 'value')`
`cookie()`	Работа с cookies	`cookie()->set('name', 'value')`
`email()`	Почта	`email()->to('user@test')->subject('Hi')->send()`
`encrypt()`	Шифрование	`encrypt()->encryptString('data')`

Сервис-контейнер

`app()`

Получение экземпляров сервисов из DI-контейнера.


<?php
// Получение сервиса
$logger = app(\Flute\Core\Services\LoggerService::class);
 
// Привязка сервиса
app()->bind('my.service', function() {
    return new MyService();
});
 
// Получение привязанного сервиса
$service = app('my.service');

Конфигурация

`config()`

Работа с конфигурационными файлами.


<?php
// Получение значения
$perPage = config('blog.articles_per_page', 10);
 
// Получение всего конфига
$blogConfig = config('blog');
 
// Установка значения (в рантайме)
config(['blog.enabled' => false]);

События

`events()`

Работа с системой событий.


<?php
// Регистрация слушателя
events()->addDeferredListener('user.registered', function($event) {
    // Обработка события
});
 
// Диспетчеризация события
events()->dispatch(new UserRegisteredEvent($user));

Логирование

`logs()`

Запись логов в систему.


<?php
// Основной лог
logs()->info('User logged in', ['user_id' => $user->id]);
 
// Специфический канал
logs('security')->warning('Suspicious activity detected', [
    'ip' => request()->getClientIp(),
    'user_agent' => request()->headers->get('User-Agent')
]);
 
// Логирование ошибок
logs('errors')->error('Database connection failed', [
    'error' => $e->getMessage(),
    'trace' => $e->getTraceAsString()
]);

Файловая система

`fs()`

Работа с файлами и директориями.


<?php
// Проверка существования файла
if (fs()->exists('uploads/image.jpg')) {
    // Файл существует
}
 
// Чтение файла
$content = fs()->read('config/app.php');
 
// Запись файла
fs()->write('logs/custom.log', 'Log message');
 
// Создание директории
fs()->makeDirectory('uploads/thumbnails');
 
// Копирование файла
fs()->copy('source.jpg', 'destination.jpg');
 
// Удаление файла
fs()->delete('temp/file.tmp');

`finder()`

Symfony Finder для поиска файлов.


<?php
// Поиск PHP файлов
$files = finder()
    ->files()
    ->name('*.php')
    ->in('app/Modules')
    ->getIterator();
 
// Поиск по глубине
$controllers = finder()
    ->files()
    ->name('*Controller.php')
    ->in('app/Modules')
    ->depth('== 2')
    ->getIterator();

HTTP запросы и ответы

`request()`

Работа с текущим HTTP запросом.


<?php
// Получение параметров
$page = request()->get('page', 1);
$search = request()->query->get('search');
 
// Получение тела запроса
$data = request()->request->all();
 
// Заголовки
$userAgent = request()->headers->get('User-Agent');
$contentType = request()->headers->get('Content-Type');
 
// Файлы
$uploadedFile = request()->files->get('image');
 
// Атрибуты маршрута
$id = request()->getAttribute('id');
 
// Проверка метода
if (request()->isMethod('POST')) {
    // POST запрос
}
 
// Проверка типа контента
if (request()->expectsJson()) {
    // Ожидается JSON ответ
}
 
// HTMX helpers
request()->htmx()->isHtmxRequest();
request()->htmx()->isBoosted();

`response()`

Создание HTTP ответов.


<?php
// JSON ответ
return response()->json(['data' => $articles]);
 
// Представление
return response()->view('blog::index', compact('articles'));
 
// Редирект
return response()->redirect('/dashboard');
 
// Ошибка
return response()->error(404, 'Страница не найдена');
 
// Загрузка файла
return response()->download('file.pdf');

`json()`

Создание JSON ответов.


<?php
// Простой JSON
return json(['message' => 'Success']);
 
// С данными и статусом
return json(['data' => $user], 201);
 
// С заголовками
return json(['token' => $token], 200, ['Authorization' => 'Bearer ' . $token]);

`redirect()`

Создание редиректов.


<?php
// Простой редирект
return redirect('/dashboard');
 
// Редирект на маршрут
return redirect(route('user.profile', ['id' => $user->id]));
 
// Редирект с flash сообщением
return redirect('/login')->with('error', 'Неверные учетные данные');

Шаблоны

`template()`

Работа с системой шаблонов.


<?php
// Рендеринг шаблона
$content = template()->render('blog::article', ['article' => $article]);
 
// Добавление глобальной переменной
template()->addGlobal('site_name', 'My Blog');
 
// Регистрация компонента
template()->registerComponent('alert', AlertComponent::class);
 
// Добавление скрипта
template()->addScript('/js/custom.js');
 
// Добавление стиля
template()->addStyle('/css/custom.css');
 
// Получение Blade и Yoyo
$blade = template()->getBlade();
$yoyo = template()->getYoyo(); // автоматически имеет маршрут /live или /admin/live

`view()` и `render()`

Рендеринг представлений.


<?php
// Рендеринг с данными
$content = render('blog::index', ['articles' => $articles]);
 
// Получение объекта View
$view = view('blog::index', ['articles' => $articles]);

Маршрутизация

`router()`

Работа с маршрутами.


<?php
// Получение текущего маршрута
$currentRoute = router()->getCurrentRoute();
 
// Генерация URL
$url = router()->url('blog.articles.show', ['id' => 1]);
 
// Проверка существования маршрута
if (router()->hasRoute('blog.articles.show')) {
    // Маршрут существует
}

`route()`

Генерация URL маршрутов.


<?php
// Простая генерация
$url = route('blog.articles.index');
 
// С параметрами
$url = route('blog.articles.show', ['id' => $article->id]);
 
// С дополнительными параметрами
$url = route('blog.search', ['q' => 'php', 'page' => 1]);

Активные маршруты


<?php
// Получение активного роутера
$activeRouter = active_router();
 
// Проверка активного маршрута
if (is_active('blog.articles.*')) {
    // Мы на странице статей блога
}
 
// CSS класс для активного пункта меню
$class = active('blog.articles.index', 'active');

База данных и ORM

`dbal()` и `db()`

Низкоуровневая работа с базой данных через Cycle Database (DBAL).


<?php
// Менеджер подключений
$manager = dbal(); // \Cycle\Database\DatabaseManager
 
// Активная БД (по умолчанию) или именованная
$db = db();            // default
$analytics = db('analytics');
 
// Примеры: SELECT COUNT(*)
$exists = db()->select()->from('users')->where('email', $email)->count() > 0;
 
// Удаление всех строк из таблицы
db()->delete('logs')->run();
 
// Примечание: для большинства случаев предпочтительнее использовать ORM (ActiveRecord)

`orm()`

Работа с ORM.


<?php
// Получение ORM
$orm = orm();
 
// Транзакция ORM
$article = new Article();
$article->title = 'Hello';
transaction($article)->run();
 
// База данных ORM-источника сущности
// Позволяет получить подключение, к которому привязана сущность в схеме ORM
$entityDb = ormdb(\Flute\Core\Database\Entities\User::class);

`rep()`

Получение репозитория сущности (RepositoryInterface).


<?php
// Репозиторий пользователей
$userRepository = rep(\Flute\Modules\User\Database\Entities\User::class);
 
// Поиск по ID
$user = $userRepository->findByPK(1);
 
// Поиск по условиям (через Select)
$activeUsers = $userRepository->select()
    ->where('active', true)
    ->fetchAll();
 
// ActiveRecord API (рекомендуемый способ)
$user = \Flute\Core\Database\Entities\User::findByPK(1);
$users = \Flute\Core\Database\Entities\User::findAll(['active' => true]);

Рекомендуется использовать ActiveRecord API: User::findByPK(1), User::query()->where(...)->fetchAll().

`transaction()`

Управление транзакциями ORM (EntityManager).


<?php
// Сохранение/удаление нескольких сущностей одной командой
$em = transaction([$article, $comment], 'persist');
$em->run();
 
// Поддерживаемые операции: 'persist', 'persistState', 'delete', 'clean', а также chain-методы на EntityManager
transaction($entity, 'delete')->run();

Аутентификация и авторизация

`user()`

Работа с текущим пользователем.


<?php
// Текущий пользователь
$currentUser = user();
 
// Проверка аутентификации
if (user()->isLoggedIn()) {
    $userId = user()->id;
    $userName = user()->name;
}
 
// Проверка прав
if (user()->can('manage_articles')) {
    // Пользователь может управлять статьями
}
 
// Проверка роли
if (user()->hasRole('admin')) {
    // Пользователь администратор
}
 
// Специальные проверки
user()->isLoggedIn();
user()->isGuest();

Локализация

`__()`

Перевод строк.


<?php
// Простой перевод
$message = __('blog.welcome');
 
// С параметрами
$message = __('blog.articles_count', ['count' => $count]);
 
// С множественным числом
$message = __('blog.comment_count', ['count' => $count]);

`translation()`

Работа с сервисом переводов.


<?php
// Установка локали
translation()->setLocale('ru');
 
// Получение текущей локали
$currentLocale = translation()->getLocale();
 
// Добавление переводов
translation()->addTranslations([
    'custom.message' => 'Пользовательское сообщение'
]);
 
// Сброс кеша каталога (в performance-режиме)
translation()->flushLocaleCache('ru');

UI компоненты (Blade)

Краткий пример использования UI‑компонентов. Полный обзор — в разделе «Компоненты и их использование».


<x-card class="my-3">
  <x-forms.field class="mb-3">
    <x-forms.label for="title" required>@t('def.title'):</x-forms.label>
    <x-input name="title" id="title" :value="old('title')" />
  </x-forms.field>
  <button class="btn btn-primary">@t('def.save')</button>
</x-card>

Кеширование

`cache()`

Работа с кешем.


<?php
// Сохранение в кеш
cache()->set('user_profile_' . $userId, $profile, 3600);
 
// Получение из кеша
$profile = cache()->get('user_profile_' . $userId);
 
// Проверка существования
if (cache()->has('user_profile_' . $userId)) {
    // Данные есть в кеше
}
 
// Удаление из кеша
cache()->delete('user_profile_' . $userId);
 
// Очистка всего кеша
cache()->clear();
 
// Callback кеширование
$user = cache()->callback('user_' . $userId, function() use ($userId) {
    return rep(User::class)->findByPK($userId);
}, 3600);
 
// Временное кеширование и ручной сброс (используется в events()->addDeferredListener)
cache()->getKeys('flute.deferred_listeners*');

Платежи

`payments()`

Работа с платежной системой.


<?php
// Получение всех шлюзов
$gateways = payments()->getAllGateways();
 
// Получение конкретного шлюза
$stripeGateway = payments()->getGateway('stripe');
 
// Создание платежа
$result = payments()->processor()->processPayment($paymentData);

Валидация

`validator()`

Валидация данных.


<?php
// Создание валидатора
$validator = validator();
 
// Валидация данных
$validated = $validator->validate($input, [
    'title' => 'required|string|min-str-len:3|max-str-len:255',
    'email' => 'required|email',
    'age' => 'nullable|integer|min:18|max:100'
]);
 
if (!$validated) {
    $errors = $validator->getErrors();
    // Обработка ошибок
}

Flash сообщения

`flash()`

Работа с flash сообщениями.


<?php
// Установка сообщения
flash()->add('success', 'Статья успешно создана');
 
// Разные типы сообщений
flash()->add('error', 'Произошла ошибка');
flash()->add('warning', 'Предупреждение');
flash()->add('info', 'Информация');

`toast()`

Toast уведомления.


<?php
// Успешное уведомление
toast()->success('Данные сохранены')->push();
 
// Ошибка
toast()->error('Не удалось сохранить')->push();
 
// С кастомным заголовком
toast()->warning('Внимание!')
    ->message('Сессия истекает')
    ->push();

Работа с URL

`url()`

Генерация URL.


<?php
// Абсолютный URL
$fullUrl = url('/blog/articles');
 
// URL актива
$assetUrl = url('css/app.css');
 
// С протоколом
$secureUrl = url('/admin', true); // https

Работа с датами

`now()`

Работа с датами.


<?php
// Текущая дата и время
$now = now(); // DateTime
 
// Манипуляции с датами
$tomorrow = now()->modify('+1 day');
$lastWeek = now()->modify('-1 week');

Шифрование

`encrypt()`

Шифрование данных.


<?php
// Шифрование строки
$encrypted = encrypt()->encryptString('секретные данные');
 
// Расшифровка
$decrypted = encrypt()->decryptString($encrypted);

Сессии

`session()`

Работа с сессиями.


<?php
// Установка значения
session()->set('user_id', $userId);
 
// Получение значения
$userId = session()->get('user_id');
 
// Проверка существования
if (session()->has('cart')) {
    $cart = session()->get('cart');
}
 
// Удаление
session()->remove('temp_data');
 
// Очистка сессии
session()->clear();

Cookies

`cookie()`

Работа с cookies.


<?php
// Установка cookie
cookie()->set('theme', 'dark', 86400); // 24 часа
 
// Получение cookie
$theme = cookie()->get('theme', 'light');
 
// Проверка существования
if (cookie()->has('preferences')) {
    $prefs = cookie()->get('preferences');
}
 
// Удаление cookie
cookie()->delete('temp_token');

Отправка email

`email()`

Отправка email сообщений.


<?php
// Отправка простого сообщения
email()->to('[email protected]')
    ->subject('Добро пожаловать')
    ->body('Добро пожаловать на наш сайт!')
    ->send();
 
// HTML сообщение
email()->to('[email protected]')
    ->subject('Новый заказ')
    ->html('<h1>Ваш заказ принят</h1><p>Номер заказа: #123</p>')
    ->send();
 
// С вложениями
email()->to('[email protected]')
    ->subject('Отчет')
    ->body('Ваш ежемесячный отчет')
    ->attach('/path/to/report.pdf')
    ->send();

Справочник вспомогательных функций

Быстрая справка

Сервис-контейнер

app()

Конфигурация

config()

События

events()

Логирование

logs()

Файловая система

fs()

finder()

HTTP запросы и ответы

request()

response()

json()

redirect()

Шаблоны

template()

view() и render()