معین پس از مدت‌ها حضور در **کوئرا،** تصمیم گرفت برای ایجاد تنوع، در مصاحبه استخدامی **جونیورا** شرکت کند؛ در این مصاحبه از او خواسته‌اند که پروژه‌ای با استفاده از [_ORM_](https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping) مخصوص _Laravel_ انجام دهد؛ اما او معتقد است *هرکسی می‌تواند با کمی آموزش، رانندگی را یاد بگیرد؛ ولی فقط یک مکانیک دقیقاً می‌داند ماشین چگونه کار می‌کند.* بنابراین، تصمیم گرفت با هدف نشان‌دادن تبحر واقعی خود، به‌جای استفاده از _ORM_ آماده، **یک _ORM_ اختصاصی به زبان _PHP_ بنویسد** و آن را به افتخار خودش **معین سخنور (_Moein Eloquent_)** نام‌گذاری کند. مشکل اینجاست که پروژه اصلی به‌اندازه کافی وقت‌گیر است و معین برای پیاده‌سازی _ORM_ اختصاصی‌اش به زمان بیشتری نیاز دارد؛ از همین رو، او از شما کمک می‌خواهد تا در تکمیل این _ORM_ همراهش باشید.
# جزئیات پروژه
پروژه اولیه را از [این لینک](/problemset/assignments/4367/download_problem_initial_project/280060/) دانلود کنید.
<details class="yellow">
<summary>**ساختار فایل‌ها**</summary>
```
moein-eloquent
├── Database.php
├── <mark class="orange" title="این فایل باید پیاده‌سازی شود">> QueryBuilder.php <</mark>
├── <mark class="orange" title="این فایل باید پیاده‌سازی شود">> Model.php <</mark>
├── User.php
├── autoload.php
└── test
└── EloquentSampleTest.php
```
</details>
<details class="grey">
<summary>**راه‌اندازی پروژه**</summary>
برای راه‌اندازی پروژه، به پایگاه‌داده _MySQL_ نیاز است. در این بخش، به راه‌اندازی _MySQL_ در داکر می‌پردازیم. اگر تاکنون داکر را نصب نکرده‌اید، به‌کمک [این لینک](https://www.docker.com/get-started/) آن را نصب کنید.
برای نصب و راه‌اندازی کانتینر _MySQL_ به‌کمک داکر، دستور زیر را در ترمینال وارد کنید تا ایمیج _MySQL_ دانلود شود و کانتینر راه‌اندازی شود:
``` bash terminal terminal
docker run --name mysql-container \
-e MYSQL_ALLOW_EMPTY_PASSWORD=yes \
-e MYSQL_DATABASE=testdb \
-p 3306:3306 \
-d mysql:latest
```
وقتی مراحل نصب کامل شد، دستور زیر را در ترمینال وارد کنید تا با سرویس _MySQL_ در کانتینر ساخته‌شده ارتباط برقرار کنید:
``` bash terminal terminal
docker exec -it mysql-container mysql -u root
```
حال دستور زیر را در محیط تعاملی _MySQL_ وارد کنید تا پایگاه‌داده `testdb` استفاده شود:
``` sql sql sql
USE testdb;
```
اکنون می‌توانیم جدول `users` را ایجاد کنیم؛ دستور زیر را وارد کنید تا جدول `users` در پایگاه‌داده `testdb` ساخته شود:
``` sql sql sql
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
email VARCHAR(100) UNIQUE NOT NULL,
age INT NOT NULL
);
```
</details>
این پروژه **شامل ۵ فایل است که ۳ فایل از قبل تکمیل شده‌اند**. شما باید فایل‌های `Model.php` و `QueryBuilder.php` را پیاده‌سازی کنید؛ در ادامه، جزئیات هرکدام از فایل‌ها و متدهای آن‌ها را می‌توانید مشاهده کنید:
<details class="blue">
<summary>**فایل** `Database.php`</summary>
این فایل شامل یک کلاس به‌نام `Database` است که یک شی `pdo` را مقداردهی اولیه می‌کند و می‌توان با استفاده از `Database::getInstance()` به آن دسترسی پیدا کرد. **این فایل از قبل پیاده‌سازی شده و شما نیازی به تغییر در آن ندارید**؛ در پروژه ارسالی شما، این فایل جایگزین می‌شود، بنابراین هر تغییری در آن ایجاد کنید، نادیده گرفته خواهد شد. اما اگر می‌خواهید نتایج کوئری‌هایتان ببینید، باید مقادیر موجود در این فایل را تغییر دهید تا بتوانید پروژه را روی سیستم خودتان اجرا کنید.
``` php Database.php php
<?php
class Database {
private static $instance = null;
private $pdo;
private function __construct() {
$this->pdo = new PDO("mysql:host=127.0.0.1;dbname=testdb", "root", "");
$this->pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
}
public static function getInstance() {
if (self::$instance === null) {
self::$instance = new Database();
}
return self::$instance->pdo;
}
}
?>
```
</details>
<details class="red">
<summary>**فایل** `QueryBuilder.php`</summary>
کلاس `QueryBuilder` برای **ساخت و اجرای کوئری‌های پایگاه‌داده** طراحی شده است. این کلاس امکاناتی مانند `SELECT`، `WHERE`، `GROUP BY`، `HAVING`، `ORDER BY`، `LIMIT` و عملیات [**CRUD**](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) را فراهم می‌کند. در پیاده‌سازی متدهای این کلاس، از [**دیزاین پترن Builder**](https://refactoring.guru/design-patterns/builder) استفاده کنید.
<details class="yellow">
<summary>متد `select()`</summary>
این متد تعیین می‌کند که **کدام ستون‌ها** در نتایج `SELECT` آورده شوند.
``` php
public function select(...$columns): self
{
// TODO
}
```
### مثال
``` php
User::select('name', 'age')->get();
User::select(['name', 'age'])->get();
User::select('*')->get();
User::select('age', 'COUNT(*) AS count')->groupBy('age')->get();
```
</details>
<details class="yellow">
<summary>متد `where()`</summary>
این متد برای **افزودن شرط‌ها به کوئری‌های `WHERE`** استفاده می‌شود.
- امکان استفاده از عملگرهای مقایسه‌ای (`=`, `>`, `<`, `LIKE`، و ...) وجود دارد.
- در صورتی که فقط دو آرگومان به متد داده شود، عملگر مقایسه‌ای پیش‌فرض (`=`) در نظر گرفته می‌شود.
``` php
public function where(string $column, mixed $operator = null, mixed $value = null): self
{
// TODO
}
```
### مثال
``` php
User::where('age', '>=', '32')->get();
User::where('age', '=', '40')->get();
User::where('age', '22')->get();
User::where('name', 'LIKE', 'M%')->get();
```
</details>
<details class="yellow">
<summary>متد `groupBy()`</summary>
این متد کوئری را براساس یک یا چند ستون گروه‌بندی (`GROUP BY`) می‌کند.
``` php
public function groupBy(...$columns): self
{
// TODO
}
```
### مثال
``` php
User::select('age', 'COUNT(*) AS count')->groupBy('age')->get();
User::select('age', 'email', 'COUNT(*) AS count')->groupBy('age', 'email')->get();
```
</details>
<details class="yellow">
<summary>متد `having()`</summary>
این متد برای فیلترکردن نتایج پس از `GROUP BY` استفاده می‌شود.
``` php
public function having(string $column, string $operator, mixed $value): self
{
// TODO
}
```
### مثال
``` php
User::select('age', 'COUNT(*) AS count')->groupBy('age')->having('age', '>', 32)->get();
```
</details>
<details class="yellow">
<summary>متد `orderBy()`</summary>
این متد **چیدمان نتایج** را براساس یک ستون و ترتیب `ASC` یا `DESC` تعیین می‌کند.
``` php
public function orderBy(string $column, string $direction = 'ASC'): self
{
// TODO
}
```
### مثال
``` php
User::orderBy('age')->get();
User::orderBy('age')->orderBy('name', 'DESC')->get();
```
</details>
<details class="yellow">
<summary>متد `limit()`</summary>
این متد تعداد نتایج بازگشتی را محدود (`LIMIT`) می‌کند.
``` php
public function limit(int $limit): self
{
// TODO
}
```
### مثال
``` php
User::orderBy('age')->limit(1)->get();
```
</details>
<details class="yellow">
<summary>متد `offset`</summary>
این متد تعدادی از نتایج بازگشتی را رد (_skip_) می‌کند.
``` php
public function offset(int $offset): self
{
// TODO
}
```
### مثال
``` php
User::orderBy('age')->offset(1)->limit(1)->get();
```
</details>
<details class="yellow">
<summary>متد `get()`</summary>
این متد کوئری نهایی را **اجرا** کرده و نتایج را **به‌صورت آرایه‌ای از اشیا مدل** برمی‌گرداند.
``` php
public function get(): array
{
// TODO
}
```
</details>
<details class="yellow">
<summary>متد `first()`</summary>
این متد **اولین نتیجه‌ی** کوئری را دریافت کرده و مقدار `null` را در صورت خالی‌بودن بازمی‌گرداند.
``` php
public function first()
{
// TODO
}
```
### مثال
``` php
User::orderBy('age', 'DESC')->first();
```
</details>
<details class="yellow">
<summary>متد `count()`</summary>
این متد تعداد کل ردیف‌های خروجی کوئری را برمی‌گرداند (`COUNT(*)`).
``` php
public function count(): int
{
// TODO
}
```
### مثال
``` php
User::count();
User::where('age', 24)->count()
```
</details>
<details class="yellow">
<summary>متدهای `sum()`, `avg()`, `min()`, `max()`</summary>
این متدها مقدار **مجموع**، **میانگین**، **حداقل** و **حداکثر** یک ستون را محاسبه می‌کنند.
``` php
private function aggregate($function, $column)
{
// TODO
}
public function sum($column)
{
// TODO
}
public function avg($column)
{
// TODO
}
public function min($column)
{
// TODO
}
public function max($column)
{
// TODO
}
```
### مثال
``` php
User::sum('age');
User::avg('age');
User::min('age');
User::max('age');
```
</details>
<details class="yellow">
<summary>متد `insert()`</summary>
این متد یک **رکورد جدید** در پایگاه‌داده درج (`INSERT`) کرده و `id` آن را برمی‌گرداند.
``` php
public function insert(array $data): int
{
// TODO
}
```
### مثال
``` php
User::insert(
[
'id' => 10,
'name' => 'New User',
'age' => 50,
'email' => 'newuser@email.com'
]
)
```
</details>
<details class="yellow">
<summary>متد `update()`</summary>
این متد داده‌های جدول را بر اساس `WHERE` **به‌روزرسانی** می‌کند.
- اگر شرط `WHERE` تعیین نشده باشد، خطا (`Exception`) ایجاد می‌شود.
``` php
public function update(array $data): bool
{
// TODO
}
```
### مثال
``` php
User::where('id', 10)->update(['name' => 'Newer Name']);
```
</details>
<details class="yellow">
<summary>متد `delete()`</summary>
این متد رکوردهای پایگاه‌داده را حذف (`DELETE`) می‌کند.
- اگر `WHERE` تعیین نشده باشد، عملیات متوقف شده و خطا (`Exception`) صادر می‌شود.
``` php
public function delete(): bool
{
// TODO
}
```
### مثال
``` php
User::where('id', 10)->delete();
```
</details>
</details>
<details class="red">
<summary>**فایل** `Model.php`</summary>
این فایل باید پیاده‌سازی شود. در این فایل یک **کلاس انتزاعی (_abstract_)** به‌نام `Model` وجود دارد که **مدل‌های پایگاه‌داده از آن ارث‌بری می‌کنند**. این کلاس دو پراپرتی دارد؛ نام جدول و آرایه `attributes`. نام جدول باید توسط مدل‌هایی که از این کلاس ارث‌بری می‌کنند _Overwrite_ شود. آرایه `attributes` برای ست‌کردن پراپرتی‌های _dynamic_ است. این کلاس دارای چند متد است که باید پیاده‌سازی شوند:
<details class="yellow">
<summary>متد `query()`</summary>
این متد یک **شیء از کلاس `QueryBuilder`** ایجاد کرده و برای اجرای کوئری‌های پایگاه‌داده مورد استفاده قرار می‌گیرد.
``` php
public static function query(): QueryBuilder
{
// TODO
}
```
</details>
<details class="yellow">
<summary>متد `allQuery()`</summary>
این متد تمام رکوردهای موجود در جدول مرتبط با مدل را دریافت کرده و **به‌صورت آرایه‌ای از اشیا** برمی‌گرداند.
``` php
public static function allQuery(): array
{
// TODO
}
```
### مثال
``` php
User::all();
```
</details>
<details class="yellow">
<summary>متد `findQuery()`</summary>
این متد یک رکورد خاص را بر اساس مقدار `id` جست‌وجو می‌کند.
- اگر رکوردی یافت شود، **نمونه‌ای از مدل** را برمی‌گرداند.
- در غیر این صورت مقدار `null` برمی‌گردد.
``` php
public static function findQuery(int $id): ?self
{
// TODO
}
```
### مثال
``` php
User::find(1);
```
</details>
<details class="yellow">
<summary>متد `createQuery()`</summary>
این متد یک رکورد جدید در جدول مرتبط با مدل ایجاد می‌کند.
- داده‌های جدید را در پایگاه‌داده **درج** کرده و نمونه‌ای از مدل را که شامل این داده‌ها است، برمی‌گرداند.
``` php
public static function createQuery(array $data): ?self
{
// TODO
}
```
### مثال
``` php
User::create([
'id' => 20,
'name' => 'Jason Voorhees',
'email' => 'jason@gmail.com',
'age' => 60
]);
```
</details>
<details class="yellow">
<summary>متد `firstQuery()`</summary>
این متد **اولین رکورد موجود** در جدول را دریافت کرده و به‌عنوان نمونه‌ای از مدل برمی‌گرداند.
``` php
public static function firstQuery(): ?self
{
// TODO
}
```
### مثال
``` php
User::first();
```
</details>
<details class="yellow">
<summary>متد `hydrateQuery()`</summary>
این متد یک نمونه از مدل را با داده‌های ورودی مقداردهی می‌کند.
- برای **پر کردن شیء مدل از یک آرایه داده** استفاده می‌شود.
``` php
public static function hydrateQuery(array $data): self
{
// TODO
}
```
</details>
<details class="yellow">
<summary>متد `updateQuery()`</summary>
این متد مقدار فیلدهای یک رکورد را **به‌روزرسانی** می‌کند.
- رکورد مورد نظر باید در _object_ و پایگاه‌داده همزمان به‌روزرسانی شود.
- اگر به‌روزرسانی موفقیت‌آمیز باشد، مقدار `true` برمی‌گردد.
- در غیر این صورت مقدار `false` بازمی‌گردد.
``` php
public function updateQuery(array $data): bool
{
// TODO
}
```
### مثال
``` php
$user = User::find(1);
$user->update(['age' => 30]);
```
</details>
<details class="yellow">
<summary>متد `deleteQuery()`</summary>
این متد رکورد مربوطه را از پایگاه‌داده **حذف** می‌کند.
- اگر حذف موفقیت‌آمیز باشد، مقدار `true` برمی‌گردد.
- در غیر این صورت مقدار `false` بازمی‌گردد.
``` php
public function deleteQuery(): bool
{
// TODO
}
```
### مثال
``` php
$user = User::find(1);
$user->delete();
```
</details>
</details>
<details class="blue">
<summary>**فایل** `User.php`</summary>
این فایل شامل یک کلاس `User` است که از کلاس `Model` ارث‌بری می‌کند. در این کلاس، صرفا مقادیر مورد نیاز تعریف یا مقداردهی شده‌اند. شما نیازی به پیاده‌سازی این فایل ندارید.
``` php User.php php
<?php
require_once 'autoload.php';
class User extends Model {
protected static string $table = 'users';
public int $id;
public string $name;
public string $email;
public int $age;
}
?>
```
</details>
<details class="blue">
<summary>**فایل** `autoload.php`</summary>
این فایل صرفا شامل یک رجیستر است که کلاس‌های مورد نیاز را از فایل‌های دیگر فراخوانی می‌کند. شما نیازی به پیاده‌سازی این فایل ندارید.
``` php autoload.php php
<?php
spl_autoload_register(function ($class_name) {
require __DIR__ . "/$class_name.php";
});
?>
```
</details>
# نکات
- برای حل این سوال باید از [**دیزاین پترن Builder**](https://refactoring.guru/design-patterns/builder) استفاده کنید.
- دقت کنید که صرفا تغییراتی که در فایل‌های `QueryBuilder.php` و `Model.php` ایجاد می‌کنید بررسی خواهند شد؛ **تغییراتی که در فایل‌های دیگر پروژه ایجاد می‌کنید در سیستم داوری نادیده گرفته خواهند شد.**
# آن‌چه باید آپلود کنید
پس از پیاده‌سازی فایل‌های مورد نیاز، فایل‌های `QueryBuilder.php` و `Model.php` را به‌صورت فایل _Zip_ ارسال کنید.