آموزش جامع تعریف تابع سفارشی در PHP طبق استاندارد گوگل و PSR

مقدمه؛ چرا تعریف استاندارد توابع در PHP حیاتی است؟

توابع (Functions) سنگ بنای توسعه نرم‌افزار هستند. نوشتن یک تابع در PHP کار ساده‌ای است؛ اما نوشتن تابعی که امن، خوانا، بهینه و منطبق بر استانداردهای جهانی باشد، مرز بین یک برنامه‌نویس تازه‌کار و یک توسعه‌دهنده حرفه‌ای است. گوگل و سازمان استاندارد پی‌اچ‌پی (PHP-FIG) دستورالعمل‌های خاصی (مانند PSR-12) برای نوشتن کدهای استاندارد ارائه داده‌اند که رعایت آن‌ها به افزایش کیفیت پروژه و هماهنگی تیمی کمک شایانی می‌کند. در این مقاله یاد می‌گیریم چطور توابع سفارشی خود را بر اساس این استانداردها بازطراحی کنیم.

۱. فعال‌سازی حالت سخت‌گیرانه (Strict Types)

گوگل در راهنماهای کدنویسی خود بر امنیت نوع داده‌ها تأکید زیادی دارد. به طور پیش‌فرض، PHP تلاش می‌کند انواع داده‌ها را به یکدیگر تبدیل کند (ضعف Type Safety). برای جلوگیری از این رفتار غیرمنتظره، همیشه باید در اولین خط فایل PHP خود از دستور زیر استفاده کنید:

declare(strict_types=1);

با این کار، اگر تابعی ورودی از نوع عدد اعشاری (float) بخواهد و شما رشته (string) ارسال کنید، برنامه با خطا مواجه می‌شود و از بروز باگ‌های پنهان جلوگیری می‌کند.

۲. ساختار کلی یک تابع استاندارد طبق PSR-12

بر اساس استاندارد PSR-12، نام توابع باید به صورت camelCase (شروع با حروف کوچک و کلمات بعدی با حروف بزرگ) نوشته شوند. همچنین باز و بسته شدن آکولادها باید طبق قواعد خاصی هماهنگ شود:

function calculateDiscount(float $totalAmount, float $discountPercent): float
{
    return $totalAmount * ($discountPercent / 100);
}

ویژگی‌های این کد استاندارد:

• نام‌گذاری خوانا: از نام مخفف مثل calcDisc استفاده نشده است.
• Type Hinting ورودی‌ها: نوع ورودی‌ها (float) کاملاً مشخص است.
• Return Type: نوع خروجی تابع بعد از دو نقطه با عبارت : float معین شده است.

۳. مستندسازی با ساختار استاندارد PHPDoc

یکی از مهم‌ترین بخش‌های استانداردهای گوگل، مستندسازی کدها برای فهم بهتر توسط سایر توسعه‌دهندگان و محیط‌های توسعه (IDE) است. برای توابع خود از فرمت بلاک کامنت زیر استفاده کنید:

/**
 * Calculates the final price after tax calculation.
 *
 * @param float $price The base price.
 * @param float $taxRate The tax rate percentage (e.g. 0.09 for 9%).
 * @return float The final price with tax added.
 * @throws InvalidArgumentException If price is negative.
 */
function getFinalPrice(float $price, float $taxRate): float
{
    if ($price < 0) {
        throw new InvalidArgumentException('Price cannot be negative.');
    }
    return $price + ($price * $taxRate);
}

۴. اصل تک‌مسئولیتی (Single Responsibility Principle)

یک قانون طلایی در استانداردهای گوگل می‌گوید: «یک تابع باید فقط و فقط یک کار را انجام دهد و آن را به بهترین شکل ممکن انجام دهد.»

اگر تابع شما هم اطلاعات را از دیتابیس می‌خواند، هم محاسبات ریاضی انجام می‌دهد و هم ایمیل ارسال می‌کند، شما در حال نقض این اصل هستید. در این حالت باید تابع بزرگ خود را به چند تابع کوچک‌تر و تخصصی تقسیم کنید.

نتیجه‌گیری

رعایت استانداردهای کدنویسی در PHP شاید در ابتدا زمان‌بر به نظر برسد، اما در پروژه‌های بزرگ باعث صرفه‌جویی در صدها ساعت زمان عیب‌یابی و توسعه می‌شود. با فعال‌سازی strict_types، استفاده از تایپ هینتینگ و مستندسازی با PHPDoc، کدهای شما در سطح استانداردهای شرکت‌های بزرگی مثل گوگل قرار خواهد گرفت.

پیشنمایش