متد key() در PHP

در PHP یکی از توابع مفید برای کار با آرایه‌ها و نگهداری موقعیت داخلی آن‌ها، تابع key() است. این تابع کلید (index) عنصر جاری در آرایه را برمی‌گرداند. کلید می‌تواند عددی (integer) یا رشته‌ای (string) باشد. در این مقاله به کاربردها، رفتار در برابر حرکت اشاره‌گر داخلی، مقایسه با توابع مشابه و مثال‌های عملی می‌پردازیم.

چرا key() مهم است؟

• وقتی آرایه به صورت ترتیبی پیمایش می‌شود، گاهی به کلید فعلی نیاز داریم تا تصمیم‌گیری انجام دهیم.
• در پردازش‌های مرحله‌ای (مثل حلقه‌ای که با توابع pointer-based پیاده‌سازی شده) دسترسی به کلید فعلی ضروری است.
• برای سازگاری با کلاس‌هایی که اینترفیس Iterator را پیاده‌سازی می‌کنند، متد key() بخشی از قرارداد است.

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

تعامل با اشاره‌گر داخلی آرایه

آرایه‌ها در PHP یک اشاره‌گر داخلی دارند که موقعیت «عنصر جاری» را نگه می‌دارد. توابعی مثل current(), next(), prev(), reset() و end() این اشاره‌گر را دستکاری می‌کنند. تابع key() صرفاً کلید عنصر در موقعیت فعلی اشاره‌گر را برمی‌گرداند و اشاره‌گر را تغییر نمی‌دهد.

نکته درباره foreach

حلقه foreach از اشاره‌گر داخلی آرایه استفاده نمی‌کند؛ بنابراین پیمایش با foreach معمولاً باعث تغییر وضعیت key() نخواهد شد. با این حال، اگر از ارجاع (by reference) در foreach استفاده کنید یا آرایه را داخل حلقه تغییر دهید، رفتار می‌تواند متفاوت شود.

مثال‌های کاربردی

// مثال 1: استفاده ساده با توابع اشاره‌گر
$arr = ['a' => 10, 'b' => 20, 'c' => 30];
echo key($arr) . PHP_EOL; // "a"
next($arr);
echo key($arr) . PHP_EOL; // "b"
end($arr);
echo key($arr) . PHP_EOL; // "c"
next($arr);
var_dump(key($arr)); // null (خارج از محدوده)

توضیح: در این مثال ابتدا آرایه تعریف شده و اشاره‌گر داخلی به اولین عنصر اشاره می‌کند. key($arr) کلید عنصر جاری را برمی‌گرداند. با استفاده از next() به عنصر بعدی می‌رویم و پس از end() به آخر می‌رسیم. وقتی از آخر جلوتر برویم، key مقدار null بازمی‌گرداند چون اشاره‌گر خارج از محدوده است.

// مثال 2: استفاده در یک حلقه while برای پیمایش با دسترسی به کلید
$arr = [100, 200, 300];
reset($arr);
while (key($arr) !== null) {
    $k = key($arr);
    $v = current($arr);
    echo "Key: $k, Value: $vn";
    next($arr);
}

توضیح: این الگو زمانی مفید است که بخواهیم همزمان کلید و مقدار را در یک حلقه با کنترل کامل اشاره‌گر پردازش کنیم. توجه کنید که برای تشخیص انتها از مقایسه با null استفاده شده است.

// مثال 3: پیاده‌سازی ساده Iterator و متد key()
class MyIterator implements Iterator {
    private $data = [];
    private $pos = 0;
    public function __construct($arr) { $this->data = array_values($arr); }
    public function current() { return $this->data[$this->pos]; }
    public function key() { return $this->pos; } // متد key در اینجا
    public function next() { ++$this->pos; }
    public function rewind() { $this->pos = 0; }
    public function valid() { return isset($this->data[$this->pos]); }
}

$it = new MyIterator(['x','y','z']);
foreach ($it as $k => $v) {
    echo "$k: $vn"; // خروجی کلید را از متد key() می‌گیرد
}

توضیح: وقتی یک کلاس Iterator تعریف می‌کنید، متد key() نقش بازگرداندن کلید جاری تکرارکننده را دارد. foreach هنگام پیمایش از این متد برای دریافت کلید استفاده می‌کند.

مقایسه با توابع مشابه

• current(): مقدار عنصر جاری را برمی‌گرداند؛ key() فقط کلید را برمی‌گرداند.
• array_key_first() (از PHP 7.3): کلید اولین عنصر را بدون تغییر اشاره‌گر داخلی بازمی‌گرداند. مفید زمانی که فقط کلید اول را لازم دارید.
• each(): تابعی قدیمی و منسوخ‌شده که هر بار یک عنصر را برمی‌گرداند؛ استفاده از آن توصیه نمی‌شود.

نکات و جزئیات عملی

• key() ممکن است مقدار null بازگرداند که نشان‌دهندهٔ خارج شدن اشاره‌گر از حدود آرایه است. برای تشخیص صریح‌تر از !== null استفاده کنید.
• برای تشخیص وجود کلیدی مشخص در آرایه از in_array یا array_key_exists استفاده کنید؛ key() برای این هدف مناسب نیست مگر اینکه بدانید اشاره‌گر دقیقاً روی آن عنصر است.
• در برخی نسخه‌ها و محیط‌ها تفاوت‌های جزئی در رفتار با انواع داده‌ها وجود دارد؛ همیشه در پروژه‌های حساس تست کنید.
• در کدهایی که از اشاره‌گر داخلی استفاده می‌کنند، دقت کنید که همترازی (synchronization) بین توابع مختلف حفظ شود (مثلاً قبل از شروع یک پیمایش جدید reset کنید).

الگوهای پیشنهادی

• اگر فقط کلید اولین یا آخرین عنصر را می‌خواهید از array_key_first یا array_key_last استفاده کنید تا اشاره‌گر داخلی تغییر نکند.
• برای پیمایش کامل با کنترل اشاره‌گر، از ترکیب reset(), key(), current(), next() استفاده کنید.
• در کلاس‌های Iterable از متد key() برای تعریف سیاست کلیددهی استفاده کنید تا foreach رفتار پیش‌بینی‌شده داشته باشد.

جمع‌بندی: key() تابع ساده اما کاربردی‌ای است که در مواقعی که باید بر موقعیت جاری آرایه نظارت داشته باشیم بسیار مفید است. فهم تعامل آن با اشاره‌گر داخلی و تفاوتش با توابع مشابه، کمک می‌کند کد خواناتر و قابل‌اعتمادتری بنویسید.

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

ارسال