Helpers & Utilities

Helper Functions

The framework provides numerous helper functions to simplify common tasks. These functions are globally available throughout your application.

Application Helpers

HTTP Helpers

Routing & URLs

Database

Views & Assets

Authentication

File System

Cache Utility

The Cache utility provides a simple yet powerful caching mechanism for storing and retrieving data with expiration support.

Cache Interface Methods

Helper Functions

// Get or create cache instance
$cache = cache('user_cache');

// Store data with expiration
cache()->store('key', $data, '+1 day');

// Retrieve data (with callback if not exists)
$data = cache()->load('key', function() {
    return expensiveOperation();
}, '+30 minutes');

// Remove cache instance
unload_cache('user_cache');

Expiration Formats

Expiration times can be specified as:

• Relative time: '+1 hour', '+30 minutes'
• Absolute time: '2023-12-31 23:59:59'
• null for no expiration

HTTP Utility

The HTTP utility provides a simple interface for making HTTP requests using cURL.

HTTP Interface Methods

Helper Functions

// Simple GET request
$response = http('https://api.example.com');

// With parameters and headers
$response = http()
    ->header('Accept', 'application/json')
    ->send('https://api.example.com/users', ['page' => 2]);

// POST request example
$response = http()
    ->option(CURLOPT_POST, true)
    ->option(CURLOPT_POSTFIELDS, json_encode(['name' => 'John']))
    ->header('Content-Type', 'application/json')
    ->send('https://api.example.com/users');

Response Format

Requests return an array with these keys:

[
    'body' => 'Response content',
    'status' => 200,
    'last_url' => 'Final URL after redirects',
    'length' => 'Content length'
]

Common cURL Options

• CURLOPT_TIMEOUT - Request timeout
• CURLOPT_FOLLOWLOCATION - Follow redirects
• CURLOPT_RETURNTRANSFER - Return response as string
• CURLOPT_SSL_VERIFYPEER - Verify SSL certificate

Image Utility

The Image utility provides a simple interface for common image manipulation tasks including compression, resizing, and rotation.

Image Interface Methods

Helper Function

// Basic usage
$image = image('path/to/source.jpg');

// Chain operations
image('photo.jpg')
    ->resize(1200, 800)
    ->compress(85, 'optimized.jpg');

Compression Details

• For JPEG: Quality range 0-100 (higher is better quality)
• For PNG: Compression level 0-9 (higher is more compression)
• If no destination is provided, modifies the original image

Resizing Options

// Single resize
image('photo.jpg')->resize(800, 600, 'resized.jpg');

// Multiple sizes (returns array of generated files)
$resized = image('photo.jpg')->bulkResize([
    300 => 200,  // thumbnail
    800 => 600,  // medium
    1200 => 900  // large
]);

Supported Image Formats

The utility supports common image formats including:

• JPEG/JPG
• PNG

Mail Utility

The Mail utility provides a fluent interface for sending emails, supporting both plain text and HTML content, with options for templates, attachments, and multiple recipients.

Core Methods

Helper Function

// Simple text email
mailer(
    to: 'user@example.com',
    subject: 'Welcome',
    body: 'Thank you for registering',
    isHtml: false
)->send();

// Template-based HTML email
mailer(
    to: 'user@example.com',
    subject: 'Your Order',
    template: 'emails/order-confirmation',
    context: ['order' => $order],
    from: 'orders@example.com'
)->send();

// Fluent interface
mailer()
    ->to('user@example.com')
    ->subject('Reminder')
    ->view('emails/reminder', ['days' => 3])
    ->cc('manager@example.com')
    ->send();

Template Usage

Template files should be placed in your views directory (typically resources/views/emails/):

<!-- resources/views/emails/welcome.php -->
<h1>Welcome, <?= $name ?>!</h1>
<p>Thank you for joining our service.</p>

Configuration

Mail settings are configured in your environment file (env.php):

// SMTP Configuration
'mail' => [
    'mailer' => [
        'address' => '{MAILER_ADDRESS}',
        'name' => '{MAILER_NAME}'
    ],
    'reply' => [
        'address' => '{REPLY_ADDRESS}',
        'name' => '{REPLY_NAME}'
    ],
    'smtp' => [
        'enabled' => false,
        'host' => '{SMTP_HOST}',
        'port' => 2525,
        'username' => '{SMTP_USERNAME}',
        'password' => '{SMTP_PASSWORD}',
        'encryption' => 'tls|ssl',
    ],
],

Attachment Support

You can attach files to the email using the addAttachment() method:

mailer()
    ->to('user@example.com')
    ->subject('Your Document')
    ->body('Please find attached document')
    ->addAttachment('/path/to/document.pdf')
    ->send();

Paginator Utility

The Paginator utility provides a complete solution for splitting data into pages and generating pagination links with customizable styling.

Basic Usage

// Initialize paginator with total items and per-page limit
$paginator = paginator(total: 150, limit: 15, data: $arrayOfData);

// In controller (with database query)
$paginator = DB::table('users')->paginate(15);

// In view
<?php foreach ($paginator->getData() as $user): ?>
    <!-- Display user -->
<?php endforeach ?>

<?= $paginator->getLinks() ?>

Core Methods

Customizing Pagination Links

// Custom CSS classes
$paginator->getLinks(2, [
    'ul' => 'pagination-list',
    'li' => 'pagination-item',
    'a' => 'pagination-link',
    'li.current' => 'is-active',
    'a.current' => 'current-link'
]);

// Custom previous/next text
$paginator->getLinks(2, [], [
    'prev' => '«',
    'next' => '»'
]);

Database Integration

When working with databases, use the offset and limit for queries:

// In controller
$paginator = paginator(
    total: DB::table('products')->count(),
    limit: 20
);

$products = DB::table('products')
    ->offset($paginator->getOffset())
    ->limit($paginator->getLimit())
    ->get();

$paginator->setData($products);

// or simply use (RECOMMENDED)
$paginator = DB::table('products')->paginate(20);

Lazy Loading vs Eager Loading

// Eager loading (pre-sliced data)
$paginator->setData($fullArray)->getData(false);

// Lazy loading (auto-slices data)
$paginator->setData($fullArray)->getData(true);

URL Customization

Change the page parameter keyword:

// Initialize with custom parameter
$paginator = paginator(200, 10, 'pg');

// Will generate URLs like: /items?pg=2

File Uploader Utility

The Uploader utility provides a robust solution for handling file uploads with support for validation, automatic resizing, compression, and secure file naming.

Basic Usage

// Simple file upload
$uploader = uploader(uploadTo: 'products', extensions: ['jpg', 'png']);
$filePath = $uploader->upload('file_input_name');

// Multiple file upload with size limit
$uploader = uploader(
    uploadTo: documents/25-March',
    extensions: ['pdf', 'docx'],
    maxSize: 5 * 1024 * 1024 // 5MB
);
$filePaths = $uploader->upload('multiple_files_input');

Core Methods

Image Processing Features

// Single resize + compression
$uploader = uploader(
    uploadDir: root_dir('uploads/products'),
    extensions: ['jpg', 'png'],
    resize: [800 => 600],  // width => height
    compress: 80           // quality percentage
);
$imagePath = $uploader->upload('product_image');

// Multiple resizes
$uploader = uploader(
    uploadDir: root_dir('uploads/gallery'),
    resizes: [
        [300 => 200],  // thumbnail
        [800 => 600],  // medium
        [1200 => 900]  // large
    ]
);
$imageVersions = $uploader->upload('gallery_photos');  // Returns array of paths

Security Features

• Automatic secure filename generation
• File extension validation
• File size limits
• Directory permission checks
• Automatic directory creation

Helper Function

// Using the uploader() helper
$uploader = uploader(
    uploadTo: 'avatars',
    extensions: ['jpg', 'jpeg', 'png'],
    maxSize: 2 * 1024 * 1024, // 2MB
    compress: 75
);

// Handle form submission
if (request()->hasFile('avatar')) {
    try {
        $avatarPath = $uploader->upload('avatar');
        // Save path to database
    } catch (UploaderUtilException $e) {
        // Handle error
        $error = $e->getMessage();
    }
}

Configuration Options

Error Handling

try {
    $file = uploader('protected')->upload('document');
} catch (UploaderUtilException $e) {
    // Handle specific error cases
    switch ($e->getCode()) {
        case 501:
            // Failed to create upload directory.
            break;
        case 502:
            // Upload directory is not writable.
            break;
        case 503:
            // File size exceeds the maximum limit.
            break;
        case 504:
            // Invalid file extension.
            break;
        default:
            // Failed to move uploaded file.
            break;
    }
}

Support Classes

The framework includes powerful support classes inspired by Laravel's support components to make working with arrays, strings, and collections more expressive and convenient.

Collection Class

The Collection class provides a fluent, convenient wrapper for working with arrays of data.

Basic Usage

// Create collection
$collection = collect(['taylor', 'abigail', null])
    ->map(fn ($name) => strtoupper($name))
    ->reject(fn ($name) => empty($name));

// Chain methods
$collection->filter()->each()->map()->sort()

Common Methods

👉 Laravel Collection Docs

Helper Function

// Create collection from array
$collection = collect([1, 2, 3]);

Array Support (Arr)

The Arr class provides helper methods for array manipulation.

Common Methods

👉 Laravel Arr Helper Docs

Helper Functions

// Dot notation access
$value = data_get($array, 'user.address.street');

// Set nested value
data_set($array, 'user.address.street', '123 Main');

// Remove nested value
data_forget($array, 'user.address.street');

// Fill missing value
data_fill($array, 'user.role', 'guest');

String Support (Str & Stringable)

The Str and Stringable classes provide fluent string manipulation.

Common Methods

Fluent Strings

// Using Stringable
$string = str('Hello World')
    ->after('Hello')
    ->trim()
    ->append('!')
    ->upper();

// Using helper
$slug = str($title)->slug();

👉 Laravel Strings Docs

Other Support Classes

Number

use Spark\Support\Number;

Number::format(1000); // 1,000
Number::percentage(50); // 50%

👉 Laravel Number Helper Docs

Pluralizer

use Spark\Support\Pluralizer;

Pluralizer::plural('child'); // children
Pluralizer::singular('children'); // child

👉 Laravel

HtmlString

use Spark\Support\HtmlString;

new HtmlString('<h1>Safe HTML</h1>');

Js

use Spark\Support\Js;

Js::from($array); // JSON encoded with escaped characters

// Add macro to Collection
Collection::macro('uppercase', function () {
    return $this->map(fn ($item) => strtoupper($item));
});

// Use the macro
collect(['a', 'b'])->uppercase(); // ['A', 'B']