تابع preg_filter() در PHP

تابع preg_filter() یکی از توابع قدرتمند پی‌اچ‌پی برای جستجو و جایگزینی بر مبنای الگوهای регуляр اکسپرشن است. اما نکته مهم و متمایز آن نسبت به preg_replace() این است که تنها رشته‌ها یا اعضای آرایه را بازمی‌گرداند که در آنها واقعا جایگزینی انجام شده است. این رفتار در مواردی که می‌خواهیم تنها مقادیر تغییر یافته را نگهداریم، بسیار کاربردی است.

امضای تابع و پارامترها

مقدار بازگشتی

• اگر subject رشته باشد، رشته تغییر یافته بازمی‌گردد یا اگر هیچ تبدیلی رخ ندهد مقدار null برمی‌گردد.
• اگر subject آرایه باشد، تابع آرایه‌ای شامل تنها اعضایی را بازمی‌گرداند که حداقل یک جایگزینی در آنها انجام شده است. اگر هیچ کدام تغییر نکرده باشند، null بازمی‌گردد.

مثال‌های عملی

مثال ساده روی یک رشته

$input = "Contact: john.doe@example.com";
$result = preg_filter('/([a-z0-9._%+-]+)@([a-z0-9.-]+.[a-z]{2,})/i', '###', $input);
echo $result; // "Contact: ###"

در این مثال ایمیل در متن با “###” جایگزین می‌شود. چون یک جایگزینی انجام شده، رشته جدید بازگردانده می‌شود. اگر الگو مطابقت نداشت، مقدار بازگشتی null بود.

مثال با آرایه موضوع (subject)

$arr = [
  "apple",
  "banana",
  "pear123",
  "nochange"
];

$filtered = preg_filter('/d+/', 'NUM', $arr);
var_export($filtered);

خروجی تنها اعضایی را نشان می‌دهد که عددی در آنها وجود داشته و جایگزین شده است. در اینجا فقط “pear123” تغییر می‌یابد و مثلاً آرایه بازگشتی ممکن است [“pearNUM”]. با این روش می‌توانید آرایه را به‌صورت فیلتر شده بر اساس وجود الگوی خاص دریافت کنید.

استفاده از پارامتر count برای شمارش جایگزینی‌ها

$subject = ["a1", "b22", "c"];
$count = 0;
$result = preg_filter('/d+/', '#', $subject, -1, $count);
// $count اکنون تعداد کل جایگزینی‌ها را نشان می‌دهد
var_dump($count);

با ارسال متغیر $count به صورت مرجع، تابع تعداد کل جایگزینی‌هایی که انجام شده را در آن می‌نویسد. این برای گزارش‌دهی یا منطق تصمیم‌گیری مفید است.

نکات پیشرفته و توصیه‌ها

• تفاوت با preg_replace: مهم‌ترین تفاوت این است که preg_replace همیشه مقدار subject را برمی‌گرداند (حتی اگر تغییر نکرده باشد)، ولی preg_filter فقط مقادیری را برمی‌گرداند که تغییر کرده‌اند. این باعث می‌شود preg_filter برای فیلتر-و-جایگزین بسیار مناسب باشد.
• مقدار بازگشتی null: اگر هیچ تغییری در subject رخ ندهد، مقدار null برمی‌گردد نه آرایه خالی. هنگام استفاده با آرایه باید این نکته را در نظر بگیرید و برای جلوگیری از ارور، بررسی کنید که خروجی null نباشد.
• امنیت و عملکرد: برای الگوهایی که از ورودی‌های کاربر استفاده می‌کنند، حتماً از preg_quote برای فرار دادن رشته‌های حرفی استفاده کنید تا از خطاهای regex جلوگیری شود. همچنین الگوهای پیچیده می‌توانند باعث backtracking و کندی شوند؛ در صورت نیاز الگو را ساده‌تر یا از تایم‌اوت/محدودیت استفاده کنید.
• فلگ‌ها: برای پشتیبانی از یونیکد از فلگ ‘u’ استفاده کنید. برای حساسیت مورد نظر از ‘i’ (case-insensitive) و سایر فلگ‌ها بهره ببرید.

نمونه پیشرفته: چند الگو و چند جایگزین

$patterns = ['/cat/i', '/dog/i'];
$replacements = ['feline', 'canine'];
$subjects = ['My Cat', 'dog days', 'bird'];

$result = preg_filter($patterns, $replacements, $subjects);
var_export($result);

در این مثال دو الگو تعریف شده‌اند و هر الگو با جایگزین متناظرش جایگزین می‌شود. خروجی تنها شامل “My feline” و “canine days” خواهد بود، چرا که “bird” تغییری نداشته و حذف می‌شود.

روند نگهداری اندیس‌ها و مرتب‌سازی نتیجه

اگر بخواهید آرایه خروجی را بازاندیس‌دهی کنید (index را از صفر شروع کنید)، می‌توانید از array_values استفاده کنید:

$out = preg_filter('/d+/', '#', ['one1', 'two', 'three3']);
if ($out !== null) {
  $out = array_values($out);
}
var_export($out);

ترکیب array_values باعث می‌شود اندیس‌ها فشرده و مرتب شوند. این کار مخصوصاً برای ارسال نتیجه به JSON یا استفاده در توابعی که اندیس مشخصی انتظار دارند مفید است.

موارد استفاده رایج

• فیلتر و استخراج آیتم‌هایی که با الگو منطبق می‌شوند (مثلاً استخراج آدرس‌های ایمیل یا شماره‌ها در یک آرایه).
• پاکسازی یا نرمال‌سازی داده‌ها در مجموعه داده‌ها (ارسال تنها مواردی که تغییر کرده‌اند برای به‌روزرسانی پایگاه داده).
• جایگزینی قالبی برای مقادیر خاص در متن‌های طولانی، بدون برگرداندن موارد دست‌نخورده.

چک‌لیست برای استفاده امن و بهینه

• الگوهای پیچیده را تست کنید تا از backtracking جلوگیری شود.
• برای ورودی‌های کاربر از preg_quote استفاده کنید.
• همیشه خروجی را برای null چک کنید قبل از اعمال توابعی مثل foreach یا array_values.
• در صورت نیاز به استفاده از callback ها از preg_replace_callback بهره ببرید، چرا که preg_filter از callback پشتیبانی نمی‌کند.

تابع preg_filter ابزار ساده اما بهینه‌ای برای مواقعی است که می‌خواهید هم جایگزینی انجام شود و هم تنها موارد تغییر یافته را دریافت کنید. با درک دقیق پارامترها و رفتار بازگشتی می‌توانید از آن به‌صورت مؤثری در پاکسازی، فیلتر و نرمال‌سازی داده‌ها استفاده کنید.

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

ارسال