کلاس JUserHelper - ابزار کمکی برنامه نویسان جوملا

اگر شما هم یک برنامه نویس جوملا باشید که تولید افزونه های جوملا مانند کامپوننت ، ماژول و پلاگین می کند ، قطعا کار با سیستم کاربران جوملا رو تجربه داشتید که بخواهید از این قابلیت که بصورت پیشفرض در جوملا وجود دارد استفاده کنید؛ در این آموزش ما به شما آموزش خواهیم داد که چطور می توانید با استفاده از توابع و کلاس های موجود در هسته جوملا ، کار خود را پیش ببرید.

 کلاس JUserHelper یکی از اصلی ترین کلاس های مرتبط با com_users در جوملاست که به شما قابلیت های فراوانی از جمله :

•  بررسی کردن اینکه کاربر با نام کاربری خاص وجود دارد یا خیر
•  ساخت پسورد تصادفی برای تغییر پسورد کاربران در جدول  #__users
•  Hash کردن پسورد دلخواه شما با الگوریتم ایجاد پسورد جوملا
•  فعال سازی حساب کاربری جوملا
•  تغییر گروه کاربری هر کاربر
•  و ...

رو میده که اگر بخواهیم تابع های مشابه ای که این کار رو انجام میده بنویسیم ، قطعا زمان زیادی از ما تلف میشه ! خب وقتی این توابع از قبل نوشته شده چرا باید دوباره نوشته شوند ؟! قطعا دلیل منطقی وجود نداره مگر در شرایط خاص که نیاز به یک قابلیت اضافه بر سازمانی احساس شود.

 این آموزش برای جوملا نسخه 3.2+ می باشد و نسخه های قبل تر نمی توانید از این آموزش استفاده کنید.

 خب بریم سراغ شروع آموزش

 یکی یکی توابع مهم و کاربری رو در سرتیتر می نویسم و درباره اش کمی توضیح و در نهایت یک مثال از اون میزنم که بتونید کامل درکش کنید.

getUserId

getUserId(string $username) : integer

Arguments :
$username
    stringThe username to search on.

Response :
integerThe user id or 0 if not found.

 این تابع که یکی از ساده ترین تابع ها هست (یک Query ساده هست به جدول #__users) با آرگومان نام کاربری (username) که بهش داده میشه ، میگرده تا ببینه آیا همچین نام کاربری در دیتابیس وجود داره یا خیر

 اگر وجود داشت شناسه اون کاربر رو در پاسخ بر میگردونه اما اگر پیدا نکرد مقدار NULL بر میگردونه.

 به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::getUserId('admin');
var_dump($output);

اگر کد بالا رو در یک ماژول یا کامپوننت یا پلاگین خودتون اجرا کنید می بینید که عبارت NULL یا عددی رو میگردونه (منظور شناسه کاربری هست).

 genRandomPassword

genRandomPassword(integer $length = 8) : string

Arguments :
$length
    integerLength of the password to generate

Response :
stringRandom Password

 با کمک این تابع شما می تونید یک پسورد تصادفی با هر بار فراخوانی آن بسازید.

 در آرگومان اول این تابع می تونید تعداد کارکترهای پسورد ایجاد شده رو بهش بدید تا بر اساس تعدادی که شما میدید بهش تابع اجرا بشه به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::genRandomPassword(20);
var_dump($output);

 اگر تابع فوق رو در برنامه خود اجرا کنید می بینید که یک خروجی شبیه به iaZtY2n4sRIBAB2Y3zay می دهد و با هر بار رفرش این مقدار عوض می شود.

 activateUser

activateUser(string $activation) : boolean

Arguments :
$activation
    stringActivation string

Response :
booleanTrue on success

 این تابع می تونه به شما در فعال سازی یک حساب کاربری کمک کنه! خب حتما می پرسید دقیقا این تابع کجاها به کار میاد ؟

 من شخصا یک پروژه ای رو انجام دادم که بر میگرده به چند سال پیش؛ توی این پروژه باید در مراحل ثبت نام که توی کامپوننت اختصاصی مشتری هم نوشته شده بود ، ثبت نام با لینک فعال سازی انجام میشد اما نمیشد با ایمیل ارسال لینک فعال سازی جوملا این کار رو انجام داد چون مشتری در صفحه لینک فعال سازی نیاز به یک سری شخصی سازی هایی برای خودش بود اما من داشتم از سیستم com_users استفاده میکردم و همون طور که می دونید اگر در تنظیمات کاربران جوملا در مدیریت ، فعال سازی کاربر را روی "خودش" تنظیم کنید ، جوملا کاربر رو در جدول #__users درج میکنه اما ستون block رو مساوی با 1 قرار میده و در ستون activation یک رشته نا مفهوم تقریبا 30 کارکتری هم ثبت می کنه! این رشته 30 کارکتری همون مقدار امنیتی هست که باید به ایمیل کاربر ارسال بشه تا کاربر با کلیک روی اون لینک ، جوملا بتونه تشخیص بده که کدوم کاربر احراز هویت رو با موفقیت انجام داده.

 خب این تابع می تونه با گرفتن همین رشته 30 کارکتری در آرگومان اول ، کاربر مربوطه رو شناسایی و اون رو فعالش کنه. به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::activateUser('663d4b16642e5915ff8e63dd278eaa68');
var_dump($output);

 من کاربری با عنوان test ایجاد کردم که رشته احراز هویت اون رو دادم به تابع activateUser و این تابع اون رو فعال کرد.

 getProfile

getProfile(integer $userId) : object

Arguments :
$userId
    integerThe id of the user.

Response :
object

 حتما دیدید که تو جوملا یک پلاگین هست به نام User Profile یا پروفایل کاربر ، که وقتی فعال کنید یک سری از فیلدهای اضافه ای در بخش کاربران جوملا پدیدار میشن که موقع ثبت نام ، کاربر می تونه اونا رو تکمیل کنه.

 با کمک این تابع می تونید با دادن شناسه کاربر در آرگومان اول آن ، اطلاعات پر شده در این فیلدها را در پاسخ دریافت کنید. به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::getProfile(609);
var_dump($output);

 عدد 609 شناسه کاربری هست که بصورت تستی وارد شده و شما می تونید شناسه کاربر خودتون رو وارد کنید.

 getUserGroups

getUserGroups(integer $userId) : mixed

Arguments :
$userId
    integerThe id of the user.

Response :
mixedArray on success, JException on error.

 با استفاده از این تابع می تونید با دادن شناسه کاربر مربوطه در آرگومان اول آن ، لیست شناسه گروه هایی که این کاربر در آنها عضو است را در پاسخ دریافت کنید.

 به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::getUserGroups(609);
var_dump($output);

 در مثال بالا کاربری با شناسه 609 رو مورد آزمایش قرار داده ایم که خروجی زیر را به ما در پاسخ برگردانده است :

array(1) { [8]=> string(1) "8" } 

 خب میبینیم که در جواب به شما عدد 8 رو در یک آرایه برگردانده است اما سوال اینجاست این 8 دقیقا در چه سطح دسترسی قرار داد ؟

 برای فهمیدن این موضوع باید به جدول #__usergroups مراجعه کنید. به تصویر زیر دقت کنید (عدد 8 در تصویر زیر به ستون id که دور آن خط کشیده شده است اشاره دارد)

 کاربر با شناسه 609 در واقع مدیر کل یا Super Users می باشد.

 hashPassword

hashPassword(string $password) : string

Arguments :
$password
    stringThe plaintext password to encrypt.

Response :
stringThe encrypted password.

اگر بخواهید یک کاربر درون جدول #__users ثبت کنید که کاربر بتواند یا نام کاربری و کلمه عبور وارد سایت شود ، مجبور خواهید بود برای ذخیره سازی کلمه عبور آن از الگوریتم ساخت پسورد توسط جوملا استفاده کنید یا اصطلاحا از آن پیروی کنید.

 با کمک این تابع شما می تونید با دادن پسورد مورد نظر در آرگومان اول آن ، مقدار Hash شده توسط هسته جوملا را در پاسخ دریافت کنید؛ به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::hashPassword('abc123');
var_dump($output);

 در خروجی باید یک عبارت مشابه زیر ببینید :

$2y$10$0RULIXxrE8BZaVger24vceecMdZSd94RW1vGYQEsYqbSl9bs3WBSe

 که البته با هر بار رفرش عوض می شود

 اینگونه می توانید با کمک الگوریتم جوملا یک کاربر درون سیستم کاربران جوملا با پسورد صحیح درج کنید که کاربر بتواند بعدا به راحتی به سایت لاگین کند.

 removeUserFromGroup

removeUserFromGroup(integer $userId, integer $groupId) : mixed

Arguments :
$userId
    integerThe id of the user.

$groupId
    integerThe id of the group.

Response :
mixedBoolean true on success, JException on error.

 این تابع به شما این امکان را می دهد که بتوانید یک کاربر را از یک گروه کاربر حذف کنید؛ به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::hashPassword(609, 8);
var_dump($output);

 در آرگومان اول که عدد 609 می باشد شناسه کاربر را قرار داده ایم و در آرگومان دوم که 8 می باشد ، شناسه گروهی که میخواهیم این کاربر از آنجا حذف شود را قرار داده ایم؛ برای مشاهده لیست گروه ها می تونید به عکس بالا که از جدول #__usergroups ارسال شده است مراجعه کنید.

 setUserGroups

setUserGroups(integer $userId, array $groups) : mixed

Arguments :
$userId
    integerThe id of the user.

$groups
    arrayAn array of group ids to put the user in.

Response :
mixedBoolean true on success, Exception on error.

 این تابع هم به شما قابلیت انتساب دادن یک کاربر را به یک گروه خاص می دهد؛ به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::setUserGroups(609, array(2,4,8));
var_dump($output);

در مثال بالا کاربری با شناسه 609 که در آرگومان اول قرار داده شده است ، را به گروه های 2 ، 4 ، 8 انتساب داده ایم.

 دقت کنید که آرگومان دوم شامل شناسه های گروه های کاربری می باشد که باید درون یک آرایه قرار بگیرد؛ برای لیست گروه ها می تونید به عکس قرار داده شده در همین مقاله که در بالاتر قرار دارد مراجعه کنید عکس از جدول #__usergroups می باشد.

 verifyPassword

verifyPassword(string $password, string $hash, integer $user_id) : boolean

Arguments :
$password
    stringThe plaintext password to check.

$hash
    stringThe hash to verify against.

$user_id
    integerID of the user if the password hash should be updated

Response
booleanTrue if the password and hash match, false otherwise

با کمک این تابع معروف در جوملا می تونید اعتبار سنجی پسورد ها را انجام دهید؛ از خودتون می پرسید یعنی چی دقیقا ؟! خب در جواب این سوال باید یک مثال براتون بزنم

 فرض کنید سیستم لاگین کاربران از بخش com_users را باید در کامپوننت خودتون شبیه سازی کنید خب برای این کار نیاز دارید ابتدا نام کاربری سپس با پیدا شدن کاربر در جدول #__users ، کلمه عبور آن را بررسی کنید که آیا درست است یا خیر. به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::verifyPassword('123456', '$2y$10$9jP90cA.ovgD6EP4fs2tCOyKB55vIBrrsrRpNu8CfRxFlXs.zi4AOS');
var_dump($output);

در پارامتر اول شما باید پسوردی که میخواهید اعتبارسنجی آن را بررسی کنید قرار دهید و در پارامتر دوم پسورد Hash شده ای که در ستون password جدول #__users قرار دارد را بنویسید

 در پاسخ اگر به شما عبارت true برگردانده شد یعنی پسورد ها با هم یکسان می باشند و اگر false برگردانده شود یعنی پسورد مربوطه اشتباه است.

 checkSuperUserInUsers

checkSuperUserInUsers(array $userIds) : boolean

Arguments :
$userIds
    arrayAn array of user IDs on which to operate

Response
booleanTrue on success, false on failure

 با کمک این تابع شما می تونید با دادن لیست شناسه های کاربران آرگومان اول آن ، بررسی کنید آیا هیچ کاربری با دسترسی مدیر کل در بین آنها وجود دارد یا خیر

 در پاسخ اگر true برگردانده شود یعنی یک کاربر مدیر وجود دارد ولی اگر false برگردانده شود یعنی هیچ یک از کاربران درخواست داده شده با دسترسی مدیر کل نمی باشند به مثال زیر دقت کنید :

jimport( 'joomla.user.helper' );
$output = JUserHelper::checkSuperUserInUsers(array(101,607,606,520));
var_dump($output);

 امیدواریم مفید واقع شده باشد

 تیم آموزشی جومینا/