الدالة rename()‎ في PHP

(PHP 4, PHP 5, PHP 7)

تعيد الدالة rename()‎ تسمية الملف أو المجلَّد.

الوصف

bool rename ( string $oldname , string $newname [, resource $context ] )

تحاول هذه الدالة تغيير الاسم oldname القديم للملف أو المجلَّد إلى الاسم newname الجديد، ونقله إلى موقع آخر إن تطلَّب الأمر. إن ظهر عند تغيير اسم الملف إلى اسمه الجديد newname أنَّه موجود مسبقًا، فسيستبدل حينئذٍ. إن ظهر عند تغيير اسم المجلَّد إلى اسمه الجديد newname أنَّه موجود مسبقًا أيضًا، فستُصدر هذه الدالة تحذيرًا حينئذٍ.

المعاملات

oldname

اسم الملف أو المجلَّد القديم المراد تغييره.

ملاحظة: يجب أن يتطابق البروتوكول المستخدم في الاسم القديم oldname مع البروتوكول المستخدم في الاسم الجديد newname.

newname

الاسم الجديد.

context

ملاحظة: أُضيف دعم المحتوى منذ إصدار PHP 5.0.0. راجع قسم المجرى (stream) للمزيد من الشرح عن المحتوى (context).

القيم المعادة

تُعاد القيمة TRUE عند نجاح العمليَّة، أو القيمة FALSE عند فشلها.

سجل التغييرات

الإصدار	الوصف
5.3.1	تستطيع الدالة rename()‎ الآن تغيير أسماء الملفات عبر الأقراص في ويندوز.
5.0.0	يمكن استخدام الدالة rename()‎ الآن مع بعض بروتوكولات URL. راجع صفحة البروتوكولات المدعومة لمعرفة البروتوكول الذي يدعم الدالة rename()‎.
4.3.3	تستطيع الدالة rename()‎ الآن تغيير أسماء الملفات الموجودة في الأقسام الأخرى الموصولة (mounted) في الأنظمة الشبيهة بيونكس شرط أن تسمح لها الأذونات المناسبة للملف أو المجلَّد بذلك. قد يُصدر تحذير إن كان نظام الملفات المقصود لا يسمح بتنفيذ النظام للدالة chown()‎ أو الدالة chmod()‎ على الملفات المحدَّدة مثل أن يكون نظام الملفات المقصود FAT.

أمثلة

المثال 1: استعمال الدالة rename()‎

<?php

rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");

?>

انظر أيضًا

• الدالة copy()‎: تنسخ الملف أو المجلَّد.
• الدالة unlink()‎: تحذف الملف.
• الدالة move_uploaded_file()‎: تنقل ملفًا مرفوعًا إلى موقع جديد.

مصادر

• صفحة الدالة rename في توثيق PHP الرسمي.