Utilities

This document outlines the utility functions and classes available in the project, as well as guidelines for when and how to create new utilities.

When to Use Utilities

According to our project guidelines:

1. If you need to perform only one task or one type of task, use a utility.
2. If you need to perform multiple tasks or a collection of tasks to achieve a result, write a service.

Utilities should be:

• Focused on a single responsibility
• Stateless (no instance variables)
• Reusable across different parts of the application
• Well-documented with clear purpose

Available Utilities

URL Parser

The URL parser utility helps with parsing and manipulating URLs:

use App\Utilities\UrlParser;

// Parse a URL
$parsedUrl = UrlParser::parse('https://example.com/path?query=value');

// Get specific components
$host = UrlParser::getHost('https://example.com/path');
$path = UrlParser::getPath('https://example.com/path');
$query = UrlParser::getQueryParams('https://example.com/path?query=value');

// Modify URLs
$newUrl = UrlParser::addQueryParam('https://example.com', 'key', 'value');
$cleanUrl = UrlParser::removeQueryParam('https://example.com?key=value', 'key');

CKEditor

Utility functions for working with CKEditor content:

use App\Utilities\CKEditorUtil;

// Clean CKEditor content
$cleanContent = CKEditorUtil::cleanContent($rawContent);

// Extract images from content
$images = CKEditorUtil::extractImages($content);

// Replace temporary image URLs with permanent ones
$updatedContent = CKEditorUtil::replaceImageUrls($content, $oldToNewUrlMap);

Switcher

A utility for toggling between different values:

use App\Utilities\Switcher;

// Toggle between two values
$newValue = Switcher::toggle($currentValue, $value1, $value2);

// Cycle through multiple values
$nextValue = Switcher::cycle($currentValue, [$value1, $value2, $value3]);

Creating New Utilities

When creating new utility classes:

1. Place them in the App\Utilities namespace
2. Use a descriptive name that ends with "Util" or clearly indicates it's a utility
3. Make all methods static
4. Add comprehensive PHPDoc comments
5. Write unit tests for all utility methods
6. Keep methods focused on a single responsibility

Example of a well-structured utility class:

<?php

namespace App\Utilities;

/**
 * Utility for string manipulation operations.
 */
class StringUtil
{
    /**
     * Convert a string to snake_case.
     *
     * @param string $input The input string
     * @return string The snake_case version of the input
     */
    public static function toSnakeCase(string $input): string
    {
        return strtolower(preg_replace('/[^a-zA-Z0-9]/', '_', 
            preg_replace('/([a-z])([A-Z])/', '$1_$2', $input)));
    }
    
    /**
     * Truncate a string to a maximum length and append an ellipsis if truncated.
     *
     * @param string $input The input string
     * @param int $maxLength The maximum length
     * @param string $suffix The suffix to append if truncated
     * @return string The truncated string
     */
    public static function truncate(string $input, int $maxLength, string $suffix = '...'): string
    {
        if (mb_strlen($input) <= $maxLength) {
            return $input;
        }
        
        return mb_substr($input, 0, $maxLength - mb_strlen($suffix)) . $suffix;
    }
}

Best Practices

1. Don't duplicate functionality that already exists in PHP or Laravel
2. Keep utility methods small and focused
3. Use type hints for parameters and return types
4. Add appropriate error handling
5. Document edge cases and limitations
6. Make utilities truly stateless
7. Use meaningful parameter names
8. Consider making utilities immutable (return new instances rather than modifying existing ones)
9. Follow the Single Responsibility Principle