Menu
Table of Contents

CMS Framework - v2.2.2

Helper Functions Reference

The CMS Framework provides a comprehensive set of helper functions to simplify common tasks. All helper functions are prefixed with ap (ArtisanPack) to avoid naming conflicts with other packages.

Naming Convention

All helpers follow the ap prefix convention:

  • apRegisterNotification() - Not registerNotification()
  • apGetSetting() - Not getSetting()
  • apAddAdminPage() - Not addAdminPage()

This ensures the framework's global functions won't conflict with other packages or application code.

Admin Helpers

Defined in: src/Modules/Admin/helpers.php

apAddAdminSection()

Register a new admin section in the navigation menu.

apAddAdminSection(string $id, string $title, string $icon, int $order = 100): void

Example:

apAddAdminSection('marketing', 'Marketing', 'megaphone', 50);

apAddAdminPage()

Register a top-level admin page.

apAddAdminPage(array $config): void

Example:

apAddAdminPage([
    'id' => 'custom-settings',
    'title' => 'Custom Settings',
    'section' => 'settings',
    'capability' => 'manage-settings',
    'callback' => fn() => view('admin.custom-settings'),
]);

apAddSubAdminPage()

Register a sub-page under an existing admin page.

apAddSubAdminPage(string $parentId, array $config): void

Example:

apAddSubAdminPage('settings', [
    'id' => 'email-settings',
    'title' => 'Email Settings',
    'capability' => 'manage-settings',
    'callback' => fn() => view('admin.email-settings'),
]);

apGetAdminMenu()

Retrieve the complete admin menu structure.

apGetAdminMenu(): array

Returns: Array of admin menu sections and pages

Asset Management Helpers

Defined in: src/Modules/Core/helpers.php

Admin Assets

apAdminEnqueueAsset(string $handle, string $src, array $deps = [], string $type = 'script'): void
apAdminDequeueAsset(string $handle, string $type = 'script'): void
apAdminAssets(string $type = 'script'): array

Example:

// Enqueue admin script
apAdminEnqueueAsset('custom-admin', '/js/admin.js', ['jquery'], 'script');

// Enqueue admin style
apAdminEnqueueAsset('custom-admin-css', '/css/admin.css', [], 'style');

// Get all enqueued admin scripts
$scripts = apAdminAssets('script');

// Dequeue asset
apAdminDequeueAsset('custom-admin', 'script');

Public Assets

apPublicEnqueueAsset(string $handle, string $src, array $deps = [], string $type = 'script'): void
apPublicDequeueAsset(string $handle, string $type = 'script'): void
apPublicAssets(string $type = 'script'): array

Example:

// Enqueue public script
apPublicEnqueueAsset('theme-script', '/js/theme.js', [], 'script');

// Enqueue public style
apPublicEnqueueAsset('theme-style', '/css/theme.css', [], 'style');

Auth Assets

apAuthEnqueueAsset(string $handle, string $src, array $deps = [], string $type = 'script'): void
apAuthDequeueAsset(string $handle, string $type = 'script'): void
apAuthAssets(string $type = 'script'): array

Example:

// Enqueue auth page script
apAuthEnqueueAsset('login-script', '/js/auth.js', [], 'script');

Notification Helpers

Defined in: src/Modules/Notifications/helpers.php

apRegisterNotification()

Register a new notification type.

apRegisterNotification(
    string $key,
    string $title,
    string $content,
    NotificationType $type = NotificationType::Info,
    bool $sendEmail = false,
    array $metadata = []
): void

Example:

use ArtisanPackUI\CMSFramework\Modules\Notifications\Enums\NotificationType;

apRegisterNotification(
    'user.welcome',
    'Welcome to the Platform',
    'Thanks for joining us!',
    NotificationType::Success,
    true,
    ['category' => 'onboarding']
);

apSendNotification()

Send a notification to specific users.

apSendNotification(string $key, array $userIds, array $overrides = []): ?Notification

Example:

apSendNotification('user.welcome', [1, 2, 3], [
    'title' => 'Custom Welcome',
]);

apSendNotificationByRole()

Send a notification to all users with a specific role.

apSendNotificationByRole(string $key, string $role, array $overrides = []): ?Notification

Example:

apSendNotificationByRole('system.maintenance', 'admin', [
    'title' => 'System Maintenance Scheduled',
]);

apSendNotificationToCurrentUser()

Send a notification to the currently authenticated user.

apSendNotificationToCurrentUser(string $key, array $overrides = []): ?Notification

Example:

apSendNotificationToCurrentUser('profile.updated', [
    'content' => 'Your profile has been updated successfully.',
]);

apGetNotifications()

Retrieve notifications for a specific user.

apGetNotifications(int $userId, int $limit = 10, bool $unreadOnly = false): Collection

Example:

// Get latest 10 notifications
$notifications = apGetNotifications($userId, 10);

// Get only unread notifications
$unread = apGetNotifications($userId, 10, true);

apMarkNotificationAsRead()

Mark a notification as read for a user.

apMarkNotificationAsRead(int $notificationId, int $userId): bool

Example:

apMarkNotificationAsRead($notificationId, auth()->id());

apDismissNotification()

Dismiss a notification for a user.

apDismissNotification(int $notificationId, int $userId): bool

Example:

apDismissNotification($notificationId, auth()->id());

apMarkAllNotificationsAsRead()

Mark all notifications as read for a user.

apMarkAllNotificationsAsRead(int $userId): int

Returns: Number of notifications marked as read

Example:

$count = apMarkAllNotificationsAsRead(auth()->id());

apDismissAllNotifications()

Dismiss all notifications for a user.

apDismissAllNotifications(int $userId): int

Returns: Number of notifications dismissed

Example:

$count = apDismissAllNotifications(auth()->id());

apGetUnreadNotificationCount()

Get the count of unread notifications for a user.

apGetUnreadNotificationCount(int $userId): int

Example:

$unreadCount = apGetUnreadNotificationCount(auth()->id());

apGetRegisteredNotifications()

Get all registered notification types.

apGetRegisteredNotifications(): array

Example:

$allNotifications = apGetRegisteredNotifications();

Settings Helpers

Defined in: src/Modules/Settings/helpers.php

apGetSetting()

Retrieve a setting value.

apGetSetting(string $key, mixed $default = null): mixed

Example:

$siteName = apGetSetting('site_name', 'My Site');
$postsPerPage = apGetSetting('posts_per_page', 10);

apRegisterSetting()

Register a new setting.

apRegisterSetting(string $key, mixed $value, string $type = 'string', string $description = ''): void

Example:

apRegisterSetting('site_name', 'ArtisanPack CMS', 'string', 'The name of the website');
apRegisterSetting('posts_per_page', 10, 'integer', 'Number of posts per page');

apUpdateSetting()

Update a setting value.

apUpdateSetting(string $key, mixed $value): bool

Example:

apUpdateSetting('site_name', 'New Site Name');
apUpdateSetting('posts_per_page', 20);

User & Role Helpers

Defined in: src/Modules/Users/helpers.php

ap_register_role()

Register a new role.

ap_register_role(string $slug, string $name, string $description = ''): void

Example:

ap_register_role('moderator', 'Moderator', 'Can moderate content and comments');

ap_register_permission()

Register a new permission.

ap_register_permission(string $slug, string $name, string $description = ''): void

Example:

ap_register_permission('moderate-comments', 'Moderate Comments', 'Can approve and delete comments');

ap_add_permission_to_role()

Add a permission to a role.

ap_add_permission_to_role(string $roleSlug, string $permissionSlug): void

Example:

ap_add_permission_to_role('moderator', 'moderate-comments');

apRegisterUserSettingsSection()

Register a user settings section.

apRegisterUserSettingsSection(string $id, string $title, callable $callback, int $order = 100): void

Example:

apRegisterUserSettingsSection('social-links', 'Social Media Links', function ($user) {
    return view('user.settings.social', compact('user'));
}, 50);

Best Practices

1. Always Use Helpers Instead of Facades

// Good - using helper
$siteName = apGetSetting('site_name');

// Less ideal - direct manager access
$siteName = app(SettingsManager::class)->get('site_name');

2. Check Return Values

Some helpers return boolean or null values:

if (apMarkNotificationAsRead($notificationId, $userId)) {
    // Success
} else {
    // Failed - notification or user doesn't exist
}

3. Type-Safe Settings

When registering settings, specify the correct type:

apRegisterSetting('is_maintenance_mode', false, 'boolean', '...');
apRegisterSetting('max_upload_size', 10240, 'integer', '...');
apRegisterSetting('site_tagline', 'A great site', 'string', '...');

4. Use Type Hints

PHP 8+ type hints work well with helpers:

function showNotifications(int $userId, int $limit = 10): Collection
{
    return apGetNotifications($userId, $limit);
}

Extending Helpers

Adding Custom Helpers

You can add your own helpers in your application by creating a helper file and autoloading it in composer.json:

{
    "autoload": {
        "files": [
            "app/helpers.php"
        ]
    }
}

Important: Use your own prefix to avoid conflicts:

// app/helpers.php

if (! function_exists('myapp_custom_helper')) {
    function myapp_custom_helper(): string
    {
        return 'Custom functionality';
    }
}

See Also