ابزارهای کمکی (Utilities)

این سند توابع و کلاس‌های کمکی موجود در پروژه و همچنین راهنمایی‌هایی برای زمان و نحوه ایجاد ابزارهای کمکی جدید را تشریح می‌کند.

چه زمانی از Utilities استفاده کنیم

طبق راهنمایی‌های پروژه ما:

1. اگر نیاز دارید فقط یک کار یا یک نوع کار انجام دهید، از utility استفاده کنید.
2. اگر نیاز دارید چندین کار یا مجموعه‌ای از کارها را برای رسیدن به نتیجه انجام دهید، یک سرویس بنویسید.

Utility ها باید:

• بر یک مسئولیت واحد متمرکز باشند
• بدون وضعیت باشند (بدون متغیرهای نمونه)
• در بخش‌های مختلف اپلیکیشن قابل استفاده مجدد باشند
• با هدف واضح به خوبی مستندسازی شده باشند

Utility های موجود

URL Parser

ابزار کمکی URL parser در تجزیه و دستکاری URL ها کمک می‌کند:

use App\Utilities\UrlParser;

// تجزیه یک URL
$parsedUrl = UrlParser::parse('https://example.com/path?query=value');

// دریافت اجزای مشخص
$host = UrlParser::getHost('https://example.com/path');
$path = UrlParser::getPath('https://example.com/path');
$query = UrlParser::getQueryParams('https://example.com/path?query=value');

// تغییر URL ها
$newUrl = UrlParser::addQueryParam('https://example.com', 'key', 'value');
$cleanUrl = UrlParser::removeQueryParam('https://example.com?key=value', 'key');

CKEditor

توابع کمکی برای کار با محتوای CKEditor:

use App\Utilities\CKEditorUtil;

// تمیز کردن محتوای CKEditor
$cleanContent = CKEditorUtil::cleanContent($rawContent);

// استخراج تصاویر از محتوا
$images = CKEditorUtil::extractImages($content);

// جایگزینی URL های موقت تصاویر با URL های دائمی
$updatedContent = CKEditorUtil::replaceImageUrls($content, $oldToNewUrlMap);

Switcher

ابزار کمکی برای تغییر بین مقادیر مختلف:

use App\Utilities\Switcher;

// تغییر بین دو مقدار
$newValue = Switcher::toggle($currentValue, $value1, $value2);

// چرخش در میان چندین مقدار
$nextValue = Switcher::cycle($currentValue, [$value1, $value2, $value3]);

ایجاد Utility های جدید

هنگام ایجاد کلاس‌های utility جدید:

1. آن‌ها را در namespace App\Utilities قرار دهید
2. از نام توصیفی که با "Util" تمام می‌شود یا به وضوح نشان می‌دهد که یک utility است استفاده کنید
3. همه متدها را static کنید
4. کامنت‌های جامع PHPDoc اضافه کنید
5. برای همه متدهای utility تست واحد بنویسید
6. متدها را بر یک مسئولیت واحد متمرکز نگه دارید

مثال یک کلاس utility با ساختار مناسب:

<?php

namespace App\Utilities;

/**
 * ابزار کمکی برای عملیات دستکاری رشته.
 */
class StringUtil
{
    /**
     * تبدیل رشته به snake_case.
     *
     * @param string $input رشته ورودی
     * @return string نسخه snake_case رشته ورودی
     */
    public static function toSnakeCase(string $input): string
    {
        return strtolower(preg_replace('/[^a-zA-Z0-9]/', '_', 
            preg_replace('/([a-z])([A-Z])/', '$1_$2', $input)));
    }
    
    /**
     * کوتاه کردن رشته به حداکثر طول و اضافه کردن سه نقطه در صورت کوتاه شدن.
     *
     * @param string $input رشته ورودی
     * @param int $maxLength حداکثر طول
     * @param string $suffix پسوند برای اضافه کردن در صورت کوتاه شدن
     * @return 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;
    }
}

بهترین شیوه‌ها

1. عملکردی که از قبل در PHP یا Laravel وجود دارد را تکرار نکنید
2. متدهای utility را کوچک و متمرکز نگه دارید
3. برای پارامترها و return type ها از type hint استفاده کنید
4. مدیریت خطای مناسب اضافه کنید
5. موارد استثنایی و محدودیت‌ها را مستند کنید
6. utility ها را واقعاً بدون وضعیت کنید
7. از نام‌های معنادار برای پارامترها استفاده کنید
8. در نظر بگیرید که utility ها را immutable کنید (نمونه‌های جدید برگردانید به جای تغییر موجودی‌ها)
9. از اصل مسئولیت واحد پیروی کنید