الدالة sprintf() في PHP: تنسيق النصوص والحشو والكسور

تعيد sprintf() نصًا مبنيًا من تنسيق وقائمة قيم: كل عنصر نائب % في التنسيق يُستبدل بالقيمة التالية. تعيد sprintf('%s is %d years old', 'Ada', 36) النص "Ada is 36 years old". وتأخذ printf() الوسائط نفسها لكنها تطبع النتيجة بدل إعادتها.

<?php
$name = 'Ada';
$age = 36;
$price = 4.5;

$line = sprintf('%s is %d years old', $name, $age);
echo $line, "\n";

// Two decimals, always
echo sprintf('Total: %.2f EUR', $price), "\n";

// printf prints directly
printf("Order #%05d for %s\n", 42, $name);

تُملأ العناصر النائبة بالترتيب، من أول التنسيق إلى آخره. يعرض %.2f منزلتين عشريتين دائمًا (4.50، لا 4.5)، ويحشو %05d العدد بالأصفار إلى خمسة أرقام.

محددات التنسيق

العنصر النائب هو %، ثم معدّلات اختيارية، ثم حرف واحد للنوع:

غيّر القيم أدناه وشغّله مرة أخرى:

<?php
echo sprintf('%s', 'PHP'), "\n";
echo sprintf('%d', 42.9), "\n";      // the decimals are cut off, not rounded
echo sprintf('%f', 1.5), "\n";
echo sprintf('%.2f', 1.5), "\n";
echo sprintf('%e', 1234.5678), "\n";
echo sprintf('%x %X', 255, 255), "\n";
echo sprintf('%o', 8), "\n";
echo sprintf('%b', 5), "\n";
echo sprintf('%08b', 5), "\n";       // binary padded to 8 bits
echo sprintf('%c', 65), "\n";
echo sprintf('%d%%', 50), "\n";
echo sprintf('%+d %+d', 5, -5), "\n"; // always show the sign

يقتطع %d العدد العشري نحو الصفر، فيصبح 42.9 العدد 42. إذا أردت 43، فقرّب أولًا: sprintf('%d', round(42.9)). والنص الذي ليس عددًا، مثل 'abc'، يصبح 0 مع %d.

الحشو بأصفار بادئة

بين % والحرف يمكنك وضع محرف حشو وعرض. يعني %05d «احشُ بـ 0 حتى عرض 5». وهذه الطريقة المعتادة لتنسيق أرقام الطلبات ومعرّفات الفواتير والأوقات والتواريخ.

<?php
echo sprintf('%05d', 42), "\n";         // 00042
echo sprintf('%03d', 7), "\n";          // 007
echo sprintf('INV-%06d', 1234), "\n";   // INV-001234

// Times and dates from numbers
$h = 9; $m = 5; $s = 3;
echo sprintf('%02d:%02d:%02d', $h, $m, $s), "\n";
echo sprintf('%04d-%02d-%02d', 2026, 3, 14), "\n";

// A width smaller than the number never cuts it
echo sprintf('%03d', 123456), "\n";

العرض حد أدنى. والعدد الأطول من العرض يُطبع كاملًا.

%05.2f: العرض والمنازل العشرية معًا

مع الأعداد العشرية، يعدّ العرض كل محرف في النتيجة، بما فيه الفاصلة العشرية وإشارة السالب. لهذا يعطي %05.2f على 3.14159 النتيجة 03.14: خمسة محارف إجمالًا، اثنان منها بعد الفاصلة.

<?php
$pi = 3.14159;

echo sprintf('%05.2f', $pi), "\n";   // 5 characters in total
echo sprintf('%08.2f', $pi), "\n";   // 8 characters in total
echo sprintf('%.2f', $pi), "\n";     // no width, just 2 decimals
echo sprintf('%.0f', $pi), "\n";     // no decimals
echo sprintf('%.2f', 5), "\n";       // integers get decimals too
echo sprintf('%08.2f', -3.5), "\n";  // the minus sign counts

يستخدم %f الفاصلة العشرية للإعدادات المحلية الحالية (المضبوطة بـ setlocale())، بينما يستخدم %F النقطة دائمًا. إذا كانت شيفرتك تضبط إعدادات محلية واحتجت إلى نقطة لـ JSON أو CSV أو واجهة برمجية، فاستخدم %F.

محاذاة النص في أعمدة

يحاذي العرض الموجب إلى نهاية الحقل، ويحاذي - قبل العرض إلى بدايته، ويضبط ' متبوعًا بمحرف محرف حشو مخصصًا. ومجتمعةً تصفّ التقارير النصية والإيصالات.

<?php
$items = [
    ['Coffee', 2, 3.5],
    ['Croissant', 1, 2.25],
    ['Orange juice', 3, 4],
];

printf("%-14s %3s %8s\n", 'Item', 'Qty', 'Price');
printf("%'-27s\n", '');

$total = 0;
foreach ($items as [$name, $qty, $price]) {
    $line = $qty * $price;
    $total += $line;
    printf("%-14s %3d %8.2f\n", $name, $qty, $line);
}

printf("%'-27s\n", '');
printf("%-14s %12.2f\n", 'Total', $total);
printf("[%'*10s]\n", 'stars');

يحشو %-14s اسم الصنف بعده حتى 14 محرفًا، ويحاذي %8.2f السعر إلى نهاية 8 محارف، ويطبع %'-27s مع نص فارغ خطًا من 27 شرطة. ويحشو %'*10s بـ * بدل المسافات.

ترقيم الوسائط لإعادة استخدامها أو تغيير ترتيبها

يعني %1$s «الوسيط الأول نصًا»، و%2$d «الثاني عددًا صحيحًا». تتيح لك العناصر النائبة المرقمة استخدام قيمة مرتين أو تغيير الترتيب دون تغيير قائمة الوسائط، وهذا ما يحتاجه المترجمون عندما يختلف ترتيب الكلمات بين اللغات.

<?php
// Single quotes: in double quotes PHP would read $s as a variable
$format = '%1$s has %2$d new messages. Open them, %1$s?';
echo sprintf($format, 'Ada', 3), "\n";

// Same arguments, different order in the sentence
$en = 'Page %1$d of %2$d';
$ja = '全%2$dページ中%1$dページ目';
echo sprintf($en, 2, 10), "\n";
echo sprintf($ja, 2, 10), "\n";

// Modifiers go after the $
echo sprintf('%1$05.1f / %1$.3f', 2.71828), "\n";

vsprintf وprintf والقيم المعادة

تأخذ vsprintf() القيم في مصفوفة واحدة، وهذا مفيد عندما تكون القيم في مصفوفة أصلًا. وتعيد printf() عدد البايتات التي طبعتها، وvprintf() هي نسخة المصفوفة من printf().

<?php
$row = ['Ada', 'Lovelace', 1815];
echo vsprintf("%s %s was born in %d.\n", $row);

$bytes = printf("%s\n", 'Hello');
echo "printf printed $bytes bytes\n";

// Same result, two ways
echo sprintf('%.1f%%', 12.345), "\n";
printf("%.1f%%\n", 12.345);

العدد الذي تعيده printf() يشمل السطر الجديد، لذا فإن "Hello\n" ستة بايتات. وللنصوص متعددة البايتات تعدّ البايتات لا المحارف.

قلة الوسائط ترمي خطأً

منذ PHP 8، يرمي التنسيق الذي فيه عناصر نائبة أكثر من القيم الخطأ ArgumentCountError بدل إعادة false. عُدّ العناصر النائبة % (متجاهلًا %%) عندما ترى هذا الخطأ.

<?php
// This throws an ArgumentCountError on purpose: 3 placeholders, 2 values
echo sprintf('%s bought %d items for %.2f', 'Ada', 3);

تعدّ الرسالة نص التنسيق وسيطًا: ArgumentCountError: 4 arguments are required, 3 given. وتُتجاهل الوسائط الزائدة بصمت، لذا لا يظهر الخطأ المعاكس على شكل خطأ. إذا بدت نتيجة sprintf خاطئة، فاطبع التنسيق بجانب القيم. وعندما لا تحتاج إلا إلى فاصل الآلاف، تكون number_format() أبسط من بنائه بـ sprintf. والقائمة الكاملة للمعدّلات على php.net.