آموزش ارتباط با دیتابیس در جوملا

برای به دست آوردن یک نمونه(instance) جدید از کلاس JDatabaseQuery، می توانیم از متد JDatabaseDriver getQuery استفاده کنیم:

$db = JFactory::getDbo();
$query = $db->getQuery(true);

دستور JDatabaseDriver::getQuery یک آرگومان اختیاری دارد که می تواند true یا false باشد(مقدار پیش فرض آن false است).

انتخاب چند رکورد از یک جدول در جوملا

در زیر یک مثال از ایجاد یک کوئری دیتابیس با استفاده از کلاس JDatabaseQuery ایجاد شده است. با استفاده از متد های select یا from یا where و order می توانیم کوئری هایی ایجاد کنیم که انعطاف پذیر و قابل خواندن ایجاد کنیم:

// دریافت یک کانکشن دیتابیس
$db = JFactory::getDbo();

// ایجاد یک آبجکت کوئری
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".

// Order it by the ordering field.
$query->select($db->quoteName(array('user_id', 'profile_key', 'profile_value', 'ordering')));
$query->from($db->quoteName('#__user_profiles'));
$query->where($db->quoteName('profile_key') . ' LIKE ' . $db->quote('custom.%'));
$query->order('ordering ASC');

// query ریست کردن کوئری با استفاده از آبجکت جدید به دست آمده ی
$db->setQuery($query);

// stdclass لود کردن نتایج به صورت یک لیست از آبجکت های
$results = $db->loadObjectList();

 در اینجا، تابع quoteName() علامت های نقل قول مناسبی را به دور نام ستون ها اضافه می کند تا از ایجاد تضاد با هر کلمه ی رزرو شده جلوگیری شود(چه حالا و چه در آینده). کوئری همچنین می تواند برای ساده سازی بیشتر، به صورت زنجیره ای مشخص شود، مانند زیر:

$query
    ->select($db->quoteName(array('user_id', 'profile_key', 'profile_value', 'ordering')))
    ->from($db->quoteName('#__user_profiles'))
    ->where($db->quoteName('profile_key') . ' LIKE ' . $db->quote('custom.%'))
    ->order('ordering ASC');

زنجیره وار کردن متدها خوانایی کدها را بهبود می بخشد و از طولانی شدن و پیچیده شدن کدها جلوگیری می کند. گروه بندی کردن کدها نیز به سادگی انجام می شود. کوئری زیر، تعداد مقاله های درون هر دسته(category) را شمارش می کند:

$query
    ->select(array('catid', 'COUNT(*)'))
    ->from($db->quoteName('#__content'))
    ->group($db->quoteName('catid'));

با استفاده از دستور setLimit می توانیم یک حدّ(limit) را برای یک کوئری تنظیم کنیم. بعنوان مثال، در کوئری زیر، تعداد 10 رکورد را برمی گرداند:

$query
    ->select($db->quoteName(array('user_id', 'profile_key', 'profile_value', 'ordering')))
    ->from($db->quoteName('#__user_profiles'))
    ->setLimit('10');

انتخاب رکوردها از چند جدول

با استفاده از متدهای join از کلاس JDatabaseQuery، می توانیم رکوردهایی را از چند جدول مرتبط انتخاب(select) کنیم. متد عمومی join دو آرگومان می گیرد: نوع join (یعنی inner، outer، left،right) و شرط join.

در مثال زیر، متوجه خواهید شد که اگر داریم یک کوئری SQL محلی می نویسیم، می توانیم از تمام کلمه های کلیدی که به صورت نرمال استفاده می کرده ایم، استفاده کنیم. که شامل کلمه ی کلیدی AS برای نام مستعار دهی به جدول ها و کلمه ی کلیدی ON برای ایجاد ارتباط بین جدول ها، می شود. همچنین توجه کنید که نام مستعار جدول(table alias) در تمام متدهایی که به ستون های جدول رجوع می کنند، مورد استفاده قرار می گیرد(مثلا select یا where یا order).

// دریافت کانکشن دیتابیس
$db = JFactory::getDbo();

// ایجاد یک آبجکت کوئری جدید
$query = $db->getQuery(true);

// شروع می شوند a انتخاب تمام مقالات برای کاربرانی که یک نام کاربری دارند که با حرف
// مرتب کردن آن بر اساس تاریخ ایجاد شده
//  حساب شود 'a' بعنوان  #__content بعنوان پارامتر دوم باعث می شود 'a' توجه کنید که با قرار دادن
$query
    ->select(array('a.*', 'b.username', 'b.name'))
    ->from($db->quoteName('#__content', 'a'))
    ->join('INNER', $db->quoteName('#__users', 'b') . ' ON ' . $db->quoteName('a.created_by') . ' = ' . $db->quoteName('b.id'))
    ->where($db->quoteName('b.username') . ' LIKE ' . $db->quote('a%'))
    ->order($db->quoteName('a.created') . ' DESC');

// ریست کردن کوئری با استفاده از آبجکت query که جدیدا ایجاد شده است.
$db->setQuery($query);

// stdClass لود کردن نتایج بعنوان یک آبجکت
$results = $db->loadObjectList();

متد join در بالا، به ما امکان می دهد تا روی هردوی جدول های content و user کوئری بزنیم و مقالاتی را با جزئیات نویسنده ی آنها بازیابی کنیم. برای joinها متدهای زیر نیز وجود دارند:

innerJoin()
leftJoin()
rightJoin()
outerJoin()

ما می توانیم از چندین join برای کوئری زدن روی بیش از دو جدول، استفاده کنیم:

$query
    ->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
    ->from($db->quoteName('#__content', 'a'))
    ->join('INNER', $db->quoteName('#__users', 'b') . ' ON ' . $db->quoteName('a.created_by') . ' = ' . $db->quoteName('b.id'))
    ->join('LEFT', $db->quoteName('#__user_profiles', 'c') . ' ON ' . $db->quoteName('b.id') . ' = ' . $db->quoteName('c.user_id'))
    ->join('RIGHT', $db->quoteName('#__categories', 'd') . ' ON ' . $db->quoteName('a.catid') . ' = ' . $db->quoteName('d.id'))
    ->where($db->quoteName('b.username') . ' LIKE ' . $db->quote('a%'))
    ->order($db->quoteName('a.created') . ' DESC');

توجه کنید که چگونه مرتب کردن زنجیره ای برای این کوئری های طولانی، باعث شده است که کدها خواناتر شوند. در برخی موارد، نیاز داریم وقتی که آیتم ها را انتخاب می کنیم، برای اجتناب از تضاد نام ستون ها، از دستور AS استفاده کنیم. در این مورد، دستورهای انتخاب(select) چندگانه و طولانی را می توان با استفاده از پارامتر دوم $db->quoteName  خلاصه کرد. یعنی بعنوان یک نام مستعار:

$query
    ->select('a.*')
    ->select($db->quoteName('b.username', 'username'))
    ->select($db->quoteName('b.name', 'name'))
    ->from($db->quoteName('#__content', 'a'))
    ->join('INNER', $db->quoteName('#__users', 'b') . ' ON ' . $db->quoteName('a.created_by') . ' = ' . $db->quoteName('b.id'))
    ->where($db->quoteName('b.username') . ' LIKE ' . $db->quote('a%'))
    ->order($db->quoteName('a.created') . ' DESC');

برای استفاده کردن مقادیر از دستور AS می توانیم از یک آرایه (ی دوم) بعنوان پارامتر دوم دستور select استفاده کنیم. به یاد داشته باشید که در آرایه دوم، مقادیری که نمی خواهید در آرایه اول از دستور AS برای آنها استفاده شود، خالی بگذارید.

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

$query
    ->select(array('a.*'))
    ->select($db->quoteName(array('b.username', 'b.name'), array('username', 'name')))
    ->from($db->quoteName('#__content', 'a'))
    ->join('INNER', $db->quoteName('#__users', 'b') . ' ON ' . $db->quoteName('a.created_by') . ' = ' . $db->quoteName('b.id'))
    ->where($db->quoteName('b.username') . ' LIKE ' . $db->quote('a%'))
    ->order($db->quoteName('a.created') . ' DESC');

استفاده از کوئری های OR

 وقتی که از چند دستور WHERE در کوئری خود استفاده می کنیم، آنها بعنوان یک AND تلقی خواهند شد. بنابراین، بعنوان مثال، کوئری زیر نتایجی را برمی گرداند که فیلد 'name'  و (AND) فیلد 'state' مورد تطابق قرار می گیرند:

$query = $db
    ->getQuery(true)
    ->select('COUNT(*)')
    ->from($db->quoteName('#__my_table'))
    ->where($db->quoteName('name') . " = " . $db->quote($value)
    ->where($db->quoteName('state') . " = " . $db->quote($state));

برای استفاده از دستور WHERE بعنوان یک OR می توانیم از کوئری زیر استفاده کنیم:

$query = $db
    ->getQuery(true)
    ->select('COUNT(*)')
    ->from($db->quoteName('#__my_table'))
    ->where($db->quoteName('name') . " = " . $db->quote($name_one), 'OR')
    ->where($db->quoteName('name') . " = " . $db->quote($name_two));

همچنین می توانیم آن را به صورت زیر نیز بنویسیم:

$query = $db
    ->getQuery(true)
    ->select('COUNT(*)')
    ->from($db->quoteName('#__my_table'))
    ->where($db->quoteName('name') . " = " . $db->quote($name_one)
    ->orWhere($db->quoteName('name') . " = " . $db->quote($name_two));

به دست آوردن نتایج کوئری

کلاس دیتابیس(database) حاوی متدهای زیادی برای کار با یک مجموعه نتایج کوئری می باشد. اگر برای کوئری هیچ تطابقی وجود نداشته باشد، نتیجه null خواهد بود.

یک نتیجه ی تکی - loadResult

از دستور loadResult() وقتی که تنها می خواهید یک مقدار تکی از کوئری دیتابیس خود برگردانده شود، استفاده کنید.

 در زیر، یک کوئری count وجود دارد که تعداد رکوردها را بعنوان نتیجه برمی گرداند:

$db = JFactory::getDbo();
$query = $db
    ->getQuery(true)
    ->select('COUNT(*)')
    ->from($db->quoteName('#__my_table'))
    ->where($db->quoteName('name') . " = " . $db->quote($value));

// Reset the query using our newly populated query object.
$db->setQuery($query);
$count = $db->loadResult();

 یا درجایی که فقط به دنبال یک فیلد تکی از یک ردیف از جدول هستیم (یا احتمالا یک فیلد تکی از اولین ردیف برگردانده می شود:) به صورت زیر عمل می کنیم:

$db = JFactory::getDbo();
$query = $db
    ->getQuery(true)
    ->select('field_name')
    ->from($db->quoteName('#__my_table'))
    ->where($db->quoteName('some_name') . " = " . $db->quote($some_value));

$db->setQuery($query);
$result = $db->loadResult();

نتایج یک ردیفی(Single Row)

هریک از این نتایج و تابع ها، یک رکورد تکی را از دیتابیس برمی گرداند؛ حتی اگر چندین رکورد وجود داشته باشد که معیارهای تعیین شده ی ما را برآورده کند. برای دریافت رکوردهای بیشتر، نیاز داریم این تابع ها را دوباره فراخوانی کنیم.

استفاده از دستور loadRow

دستور loadRow() یک آرایه ی اندیسی که حاوی یک رکورد تکی در جدول است را برمی گرداند.

. . .
$db->setQuery($query);
$row = $db->loadRow();
print_r($row);

که نتیجه ی زیر را تولید می کند:

با استفاده از روش زیر، می توانیم مقادیر فردی را مورد دسترسی قرار دهیم:

$row['index'] // e.g. $row['2']

نکته 1: اندیس های این آرایه، عددی هستند و از 0 شروع می شوند.

نکته 2: درحالیکه می توانیم درخواست خود را تکرار کنیم تا ردیف های(row) بیشتری را به دست بیاوریم، اما اگر از یک تابع که چندین ردیف(row) را برمی گرداند، استفاده کنیم مفید تر است.

استفاده از loadAssoc

دستور loadAssoc() یک آرایه ی انجمنی را از یک رکورد تکی در جدول برمی گرداند:

. . .
$db->setQuery($query);
$row = $db->loadAssoc();
print_r($row);

نتیجه به صورت زیر خواهد بود:

برای دسترسی به مقادیر فردی، می توانید به صورت زیر عمل کنید:

$row['name'] // e.g. $row['email']

نکته: درحالیکه می توانیم این فراخوانی را تکرار کنیم تا ردیف های بیشتری را به دست آوریم، اما اگر از یک تابع که چندین ردیف(row) را برمی گرداند، استفاده کنیم مفید تر است.

متد loadObject

متد loadObject() یک آبجکت PHP را از یک رکورد تکی در یک جدول برمی گرداند:

. . .
$db->setQuery($query);
$result = $db->loadObject();
print_r($result);

نتیجه به صورت زیر خواهد بود:

برای دسترسی به مقادیر فردی، می توانید از دستور زیر استفاده کنید:

$result->index // e.g. $result->email

نکته: در حالی که می توانیم در خواست خود را تکرار کنیم تا ردیف های بیشتری را دریافت کنیم، اما اگر از یک تابع که چندین ردیف(row) را برمی گرداند، استفاده کنیم مفید تر است.

نتایج تکی ستونی

هریک از این نتایج و تابع ها، یک رکورد تکی ستونی را از دیتابیس برمی گرداند؛

 استفاده از تابع loadColumn

تابع loadColumn() یک آرایه ی اندیسی را از یک ستون تکی در جدول برمی گرداند:

$query->select('name'));
      ->from . . .";
. . .
$db->setQuery($query);
$column= $db->loadColumn();
print_r($column);

 نتیجه به صورت زیر خواهد بود:

 مقادیر فردی را می توانیم با استفاده از دستور زیر به دست بیاوریم:

$column['index'] // e.g. $column['2']

نکته: 

1. اندیس های آرایه عددی هستند و از 0 شروع می شوند.

2. loadColumn() معادل است با loadColumn(0)

استفاده از loadColumn($index)

دستور loadColumn($index) یک آرایه ی اندیسی را از یک ستون تکی در جدول برمی گرداند:

$query->select(array('name', 'email', 'username'));
      ->from . . .";
. . .
$db->setQuery($query);
$column= $db->loadColumn(1);
print_r($column);

 نتیجه به صورت زیر خواهد بود:

برای دسترسی به مقادیر فردی، می توانیم به صورت زیر عمل کنیم:

$column['index'] // e.g. $column['2']

دستور loadColumn($index) به ما امکان می دهد تا روی یک سری از ستون ها در ناتیج، حلقه ی تکرار بزنیم:

. . .
$db->setQuery($query);
for ( $i = 0; $i <= 2; $i++ ) {
  $column= $db->loadColumn($i);
  print_r($column);
}

نتیجه به صورت زیر خواهد بود:

نکته: اندیس های این آرایه عددی هستند و از 0 شروع می شوند.

 ایجاد نتایج چند ردیفی(Multi-Row Results)

هر یک از این نتایج و تابع ها، چندین رکورد از دیتابیس را برمی گرداند:

 بررسی تابع loadRowList

تابع loadRowList() یک آرایه ی اندیسی از آرایه های اندیسی رکوردهای جدول که توسط کوئری برگردانده شده اند را برمی گرداند:

 . .
$db->setQuery($query);
$row = $db->loadRowList();
print_r($row);

نتیجه به صورت زیر خواهد بود(برای وضوع از شکست خط یا line break استفاده شده است):

 برای دسترسی به ردیف های فردی، می توانید به صورت زیر عمل کنید:

$row['index'] // e.g. $row['2']

برای دسترسی به مقادیر فردی، می توانید به صورت زیر عمل کنید:

$row['index']['index'] // e.g. $row['2']['3']

 نکته: اندیس های این آرایه عددی هستند و از 0 شروع می شوند.

تابع loadAssocList

تابع loadAssocList() یک آرایه ی اندیسی از آرایه های انجمنی از رکوردهای برگردانده شده با کوئری، را برمی گرداند:

. . .
$db->setQuery($query);
$row = $db->loadAssocList();
print_r($row);

نتیجه به صورت زیر خواهد بود(برای وضوح از شکست های خط یا line break استفاده شده است:

برای دسترسی به ردیف های فردی، می توانید از دستور زیر استفاده کنید:

$row['index'] // e.g. $row['2']

و برای دسترسی به مقادیر فردی می توانید به صورت زیر عمل کنید:

$row['index']['column_name'] // e.g. $row['2']['email']

استفاده از تابع loadAssocList($key)

تابع loadAssocList($key) یک آرایه ی انجمنی -اندیس شده روی key - را از آرایه های انجمنی از رکوردهای جدول که توسط کوئری برگردانده شده اند را برمی گرداند:

. . .
$db->setQuery($query);
$row = $db->loadAssocList('username');
print_r($row);

نتیجه به صورت زیر خواهد بود(برای وضوح، از شکست خط یا line-break استفاده شده است):

برای دسترسی به ردیف های(row) فردی، می توانیم به صورت زیر عمل کنیم:

$row['key_value'] // e.g. $row['johnsmith']

و برای دسترسی به مقادیر فردی، می توانیم به صورت زیر عمل کنیم:

$row['key_value']['column_name'] // e.g. $row['johnsmith']['email']

نکته: Key باید یک نام ستون معتبر از جدول باشد. Key نباید یک اندیس یا یک کلید اصلی(Primary Key) باشد. اما اگر این، یک مقدار یکتا(unique) نداشته باشد، ممکن است نتوانیم نتایج را به طور قابل اعتماد دریافت کنیم.

استفاده از تابع loadAssocList($key, $column)

تابع loadAssocList('key', 'column') یک آرایه ی انجمنی -اندیس شده روی key - از مقادیر یک ستون به نام column را که توسط کوئری برگردانده شده است را برمی گرداند.

. . .
$db->setQuery($query);
$row = $db->loadAssocList('id', 'username');
print_r($row);

نتیجه به صورت زیر خواهد بود(برای وضوح از شکست خط یا line break استفاده شده است):

Array (
[1] => John Smith,
[2] => Magda Hellman,
[3] => Yvonne de Gaulle,
)

نکته: key باید یک نام ستون متعبر از جدول باشد. key نباید یک اندیس یا یک کلید اصلی(Primary Key) باشد. اما اگر یک مقدار یکتا(unique) نداشته باشد، ممکن است نتوانیم نتایج را به طور قابل اعتماد دریافت کنیم.

استفاده از تابع loadObjectList

تابع loadObjectList() یک آرایه ی اندیسی از آبجکت های PHP از رکوردهای جدول که توسط کوئری برگردانده شده اند را برمی گرداند:

. . .
$db->setQuery($query);
$row = $db->loadObjectList();
print_r($row);

نتیجه به صورت زیر خواهد بود(برای وضوح، از شکست خط یا line break استفاده شده است:

 برای دسترسی به ردیف های فردی، می توانید به صورت زیر عمل کنید:

$row['index'] // e.g. $row['2']

برای دسترسی به مقادیر فری، می توانید به صورت زیر عمل کنید:

$row['index']->name // e.g. $row['2']->email

استفاده از تابع loadObjectList($key)

تابع loadObjectList('key') یک آرایه ی انجمنی - ایندکس شده روی key - از آبجکت ها، از رکوردهای جدول که توسط کوئری برگردانده شده اند را برمی گرداند.

. . .
$db->setQuery($query);
$row = $db->loadObjectList('username');
print_r($row);

نتیجه به صورت زیر خواهد بود(برای وضوح از شکست خط یا line break استفاده شده است:

برای دسترسی به ردیف های(row) فردی می توانید به صورت زیر عمل کنید:

$row['key_value'] // e.g. $row['johnsmith']

 برای دسترسی به مقادیر فردی می توانید از دستور زیر استفاده کنید:

$row['key_value']->column_name // e.g. $row['johnsmith']->email

نکته: Key باید یک نام ستون معتبر از جدول باشد؛ و نباید یک اندیس یا کلید اصلی(Primary Key) باشد. اما اگر key یک مقدار یونیک(unique) نداشته باشد، ممکن است نتوانید نتایج را به طور قابل اعتماد بازیابی کنید.

 بررسی تابع getNumRows

تابع getNumRows() تعداد ردیف های نتایج که توسط آخرین کوئری SELECT یا SHOW  پیدا شده اند و منتظر خواندن هستند را برمی گرداند. برای دریافت نتیجه از تابع getNumRows() باید آن را پس از کوئری خود و قبل از اینکه هرگونه نتیجه ای را بازیابی کنید، اجرا کنید. برای بازیابی تعداد ردیف هایی که متاثر از یک کوئری INSERT یا UPDATE یا REPLACE یا DELETE هستند، از تابع  getAffectedRows() استفاده کنید.

. . .
$db->setQuery($query);
$db->execute();
$num_rows = $db->getNumRows();
print_r($num_rows);
$result = $db->loadRowList();

 نتیجه:

3

نکته: تابع getNumRows() تنها برای دستوراتی مانند SELECT یا SHOW که یک مجموعه نتایج واقعی را برمی گردانند، معتبر است. اگر تابع getNumRows() را پس از تابع loadRowList() یا هر متد بازیابی کننده ی دیگری، اجرا کنیم، یک خطای PHP را دریافت خواهیم کرد.

Warning: mysql_num_rows(): 80 is not a valid MySQL result resource
in libraries\joomla\database\database\mysql.php on line 344

Sample Module Code

منابع: https://docs.joomla.org