تابع vprintf() در PHP

تابع vprintf() در PHP یکی از توابع فرمت‌دهی است که شبیه printf() عمل می‌کند با این تفاوت که پارامترهای جایگزینی را به صورت یک آرایه می‌گیرد. این تابع فرمت مشخص شده را پردازش می‌کند، رشته نهایی را چاپ می‌کند و در صورت موفقیت، تعداد بایت‌هایی که چاپ شده‌اند را بازمی‌گرداند. vprintf زمانی مفید است که پارامترهای پویا در قالب آرایه‌ای در اختیار دارید (مثلاً از دیتابیس یا یک API) و می‌خواهید آنها را درون یک الگوی فرمت قرار دهید.

سینتکس و مقدار بازگشتی

سینتکس کلی:

int vprintf ( string $format , array $args )

مقدار بازگشتی: در صورت موفقیت، تعداد بایت‌هایی که چاپ شده‌اند (یک عدد صحیح) و در صورت خطا مقدار false بازگردانده می‌شود.

مثال پایه

$format = "Name: %s, Age: %dn";
$args = ['Alice', 30];
vprintf($format, $args);

در این مثال رشته “Name: Alice, Age: 30” چاپ می‌شود. آرایه $args المان‌های %s و %d را به ترتیب پر می‌کند.

قواعد فرمت — مشخصه‌های رایج

vprintf از همان قواعد قالب‌بندی printf استاندارد پیروی می‌کند. برخی از مشخصه‌های متداول:

• %s — رشته
• %d, %i — عدد صحیح (decimal)
• %f — عدد اعشاری (float)
• %b — نمایش دودویی
• %o — نمایش اکتال
• %x, %X — نمایش هگزا (حروف کوچک/بزرگ)
• %c — کاراکتر از کد ASCII
• %e — علمی/نمای نمایش

همچنین می‌توانید از عرض، دقت و فلگ‌ها (مثل 0, +, -, space, #) و شماره‌گذاری پارامترها (%1$s) استفاده کنید.

مثال پیشرفته با پارامتر شماره‌ای (برای ترجمه)

$fmt = "Order %1$d: %2$s (%3$01.2f USD)n";
$args = [42, "Widget", 9.5];
vprintf($fmt, $args);

در این مثال از شماره‌گذاری پارامترها استفاده شده تا بتوان ترتیب جایگزینی را به صراحت کنترل کرد — این قابلیت برای محلی‌سازی و ترجمه بسیار مفید است.

تفاوت vprintf با توابع مشابه

• printf(): فرمت را گرفته و پارامترها را به‌صورت جداگانه می‌پذیرد و سپس چاپ می‌کند.
• vsprintf(): مانند vprintf است اما به‌جای چاپ، رشته فرمت‌شده را برمی‌گرداند (برای ذخیره یا پردازش بیشتر).
• vfprintf(): خروجی را به یک resource از نوع stream (مثلاً فایل) می‌فرستد.
• از PHP 5.6 به بعد می‌توانید از argument unpacking استفاده کنید: printf($format, …$args) که معادل کارایی دارد و گاهی خواناتر است.

موارد کاربرد عملی

• ایجاد پیام‌های قالب‌بندی‌شده از داده‌های ذخیره‌شده در آرایه (مانند گزارش‌ها).
• قالب‌بندی دینامیک برای فایل‌های لاگ یا خروجی CLI.
• همکاری با سیستم‌های ترجمه که نیاز به شماره‌گذاری پارامترها دارند.

مثال: تولید پیام گزارش از آرایه رکورد

$record = ['id' => 101, 'user' => 'reza', 'amount' => 250.75];
$fmt = "Transaction #%d by %s: amount = %.2fn";
vprintf($fmt, [$record['id'], $record['user'], $record['amount']]);

کد بالا یک خط گزارش متنی برای یک تراکنش چاپ می‌کند. آرایه سطری ($record) نادیده گرفته نشده و مقادیر به ترتیب به قالب فرستاده می‌شوند.

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

• هرگز از ورودی مستقیم کاربر به‌صورت فرمت استفاده نکنید. اگر فرمت از ورودی می‌آید می‌تواند موجب رفتار غیرمنتظره یا حملات قالب-رشته‌ای شود.
• بهتر است فرمت را در کد ثابت نگه دارید و تنها مقادیر را از ورودی بگیرید.
• برای خروجی در صفحات وب، پس از فرمت کردن مقادیر را با htmlspecialchars یا توابع مشابه ایمن کنید تا تزریق HTML یا XSS رخ ندهد.
• از شماره‌گذاری پارامترها در متون ترجمه‌شده استفاده کنید تا ترتیب پارامترها قابل کنترل باشد.

مثال: ایمن‌سازی خروجی HTML

$fmt = "User: %sn";
$name = "alert('x')";
vprintf($fmt, [htmlspecialchars($name, ENT_QUOTES, 'UTF-8')]);

در این نمونه مقدار نام کاربر قبل از قرار گرفتن در قالب، از نظر HTML ایمن می‌شود تا از تزریق اسکریپت جلوگیری شود.

خطاها و مواردی که باید مراقب باشید

• اگر تعداد آرگومان‌ها کمتر از جای‌گیرهای قالب باشد، هشدار (warning) تولید خواهد شد. همواره تعداد و ترتیب پارامترها را بررسی کنید.
• نوع نامناسب برای یک مشخصه (مثلاً ارسال رشته برای %d) ممکن است منجر به تبدیل ضمنی یا هشدار شود؛ بهتر است داده‌ها را پیش از فرمت به نوع مناسب تبدیل کنید.
• vprintf مقدار را چاپ می‌کند؛ اگر می‌خواهید رشته را ذخیره یا بازبینی کنید، از vsprintf استفاده کنید.

مثال جایگزینی: استفاده از vsprintf یا argument unpacking

// using vsprintf to capture string
$fmt = "Price: %.2f USD";
$args = [12.5];
$str = vsprintf($fmt, $args);
echo $str;

// using argument unpacking (PHP 5.6+)
$fmt2 = "Hello %s, you have %d messagesn";
$args2 = ['Sara', 5];
printf($fmt2, ...$args2);

در مثال اول از vsprintf برای دریافت رشته فرمت‌شده استفاده شده که سپس با echo چاپ می‌شود. در مثال دوم از unpacking استفاده شده که معادل vprintf است ولی ممکن است خوانایی بهتری داشته باشد.

جدول مرجع سریع مشخصه‌ها

جمع‌بندی

vprintf یک ابزار مفید برای چاپ رشته‌های فرمت‌شده است، مخصوصاً وقتی پارامترها در قالب آرایه در دسترس باشند. با این حال باید به همسانی تعداد و نوع پارامترها، ایمن‌سازی خروجی و گزینه‌های جایگزین مانند vsprintf یا argument unpacking توجه کرد. با رعایت نکات امنیتی و استفاده از شماره‌گذاری پارامترها در متن‌های ترجمه، می‌توانید از vprintf در پروژه‌های عملی و بین‌المللی‌سازی به‌صورت مطمئن و موثر استفاده کنید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال