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 חותך float לכיוון אפס, ולכן 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: רוחב וספרות עשרוניות יחד

ב-floats, הרוחב סופר כל תו בתוצאה, כולל הנקודה העשרונית וסימן המינוס. לכן %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 משתמש בנקודה העשרונית של ה-locale הנוכחי (שמוגדר עם setlocale()), בעוד %F תמיד משתמש בנקודה. אם הקוד שלכם מגדיר locale ואתם צריכים נקודה ל-JSON, ל-CSV או ל-API, השתמשו ב-%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" הוא 6 בתים. בטקסט מרובה בתים היא סופרת בתים, לא תווים.

מעט מדי ארגומנטים זורק שגיאה

מאז 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.