اگر یک توسعه دهنده لاراول هستید که به دنبال بهبود داکیومنت کد خود و بهبود فرآیند توسعه خود هستید، به جای درستی آمده اید. در این مقاله از آنوفل گام به گام، ما عمیقاً به کامنت نویسی Laravel PHPDoc (مستند سازی لاراول با PHPDoc) می پردازیم. ما همه چیز را از اصول اولیه تا تکنیک های پیشرفته را با مثال های زیادی در طول مسیر پوشش خواهیم داد.

کامنت نویسی PHPDoc چیست؟

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

کامنت های پایه PHPDoc

بیایید با اصول اولیه شروع کنیم. کامنت‌های PHPDoc معمولاً حاوی اطلاعاتی در مورد کلاس‌ها، متدها، ویژگی‌ها و توابع هستند. در اینجا یک مثال ساده است:

/**
 * Class representing a User in the application.
 */
class User {
    /**
     * @var int
     */
    private $id;
    
    /**
     * Get the user's ID.
     *
     * @return int
     */
    public function getId() {
        return $this->id;
    }
}

در این مثال، ما از کامنت PHPDoc برای مستندسازی کلاس User، پراپرتی id آن و متد getId استفاده کرده‌ایم. این داکیومنت درک هدف و استفاده از این عناصر را برای توسعه دهندگان دیگر (از جمله خود آینده شما) آسان تر می کند.

افزودن پارامترها و انواع بازگشت

یکی از مزایای اصلی کامنت PHPDoc توانایی آنها در تعیین انواع داده ها و توضیحات برای پارامترهای تابع و مقادیر بازگشتی (return) است:

/**
 * Calculate the sum of two numbers.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 *
 * @return int The sum of $a and $b.
 */
function calculateSum($a, $b) {
    return $a + $b;
}

در این مثال، تابع calculateSum را مستند کرده ایم و اطلاعات ارزشمندی در مورد پارامترها و نوع بازگشتی آن ارائه می دهیم.

کامنت های پیشرفته PHPDoc

کامنت PHPDoc لاراول را می توان با تگ های اضافی غنی کرد تا زمینه و اطلاعات بیشتری را ارائه دهد. برخی از تگ های رایج عبارتند از:

param@: پارامترهای تابع/متد را توصیف می کند.
return@: نوع برگشتی یک تابع یا متد را مشخص می کند.
var@: پراپرتی های درون یک کلاس را مستند می‌کند.
throws@: استثناهایی را لیست می کند که یک متد می تواند داشته باشد.
deprecated@: زمانی را نشان می دهد که یک متد یا ویژگی منسوخ شده است.
link@: یک لینک به منابع یا اسناد مرتبط ارائه می دهد.

در اینجا یک مثال برای نمایش چندین تگ PHPDoc آورده شده است:

/**
 * Get the user's email.
 *
 * @param string $format The format of the email (e.g., 'html' or 'text').
 *
 * @return string The user's email address.
 *
 * @throws \Exception If the email cannot be retrieved.
 *
 * @deprecated This method is no longer recommended; use getEmailAddress() instead.
 *
 * @link https://laravel.com/docs/email
 */
public function getEmail($format = 'html') {
    // ...
}

میکروسرویس ها در لاراول

مثال جامع از PHPDoc در لاراول

در مثال زیر نشان می‌دهد که چگونه می‌توان از PHPDoc برای مستندسازی کامل یک کنترلر لاراول استفاده کرد. این کار باعث می‌شود تا توسعه‌دهندگان دیگر به راحتی بتوانند کد را درک کنند و با آن کار کنند.

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;

/**
 * کنترلر مربوط به کاربران
 */
class UserController extends Controller {
    /**
     * لیستی از کاربران را برمی‌گرداند.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function index() {
        $users = User::all();
        return response()->json($users);
    }

    /**
     * کاربر جدیدی ایجاد می‌کند.
     *
     * @param \Illuminate\Http\Request $request
     * @return \Illuminate\Http\JsonResponse
     * @throws \Illuminate\Validation\ValidationException
     */
    public function store(Request $request) {
        $this->validate($request, [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|string|min:8'
        ]);

        $user = User::create([
            'name' => $request->name,
            'email' => $request->email,
            'password' => bcrypt($request->password),
        ]);

        return response()->json($user, 201);
    }

    /**
     * اطلاعات یک کاربر خاص را برمی‌گرداند.
     *
     * @param int $id
     * @return \Illuminate\Http\JsonResponse
     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
     */
    public function show($id) {
        $user = User::findOrFail($id);
        return response()->json($user);
    }

    /**
     * اطلاعات یک کاربر خاص را به‌روز رسانی می‌کند.
     *
     * @param \Illuminate\Http\Request $request
     * @param int $id
     * @return \Illuminate\Http\JsonResponse
     * @throws \Illuminate\Validation\ValidationException
     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
     */
    public function update(Request $request, $id) {
        $this->validate($request, [
            'name' => 'sometimes|required|string|max:255',
            'email' => 'sometimes|required|email|unique:users,email,' . $id,
            'password' => 'sometimes|required|string|min:8'
        ]);

        $user = User::findOrFail($id);
        $user->update($request->only('name', 'email', 'password'));

        return response()->json($user);
    }

    /**
     * یک کاربر خاص را حذف می‌کند.
     *
     * @param int $id
     * @return \Illuminate\Http\JsonResponse
     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
     */
    public function destroy($id) {
        $user = User::findOrFail($id);
        $user->delete();

        return response()->json(null, 204);
    }
}

کد نویسی تمیز در لاراول با اصول سالید

توسعه تست محور در لاراول

استفاده از لاراول IDE Helper برای مستند سازی

در لاراول، PHPDoc برای مستندسازی بخش‌های مختلف کد استفاده می‌شود. این مستندسازی به توسعه‌دهندگان کمک می‌کند تا کد را بهتر درک کنند و با آن راحت‌تر کار کنند. هنگام استفاده از Eloquent ORM، متوجه خواهید شد که مجیک متد های زیادی در اطراف وجود دارد. با آن دسته از منطق در پشت صحنه، طبیعی است که یک IDE متوجه نشود که چه اتفاقی در حال رخ دادن است.

بیشتر مشکلات نوشتن PHP از مستندسازی آن نوع مجیک ناشی می شود. هنگامی که IDE به اندازه کافی هوشمند نیست تا بفهمد در متد هایی مانند ()call__ و ()get__ چه اتفاقی می افتد، در نهایت هیچ کمکی برای کد نمی گیریم. با توجه به پایگاه کد عظیم پشت ORM Eloquent و اهمیت مدل های پایگاه داده، می تواند مشکل ساز باشد.

در این بخش با دسته‌ای از PHPDoc که در بالای اعلان کلاس مدل استفاده خواهیم کرد. این اعلان‌ها به PHPStorm (مورد علاقه من) و سایر IDEها اجازه می‌دهد تا این مجیک را حداقل در یک حالت قابل قبول درک کنند.

در اینجا، ما به بررسی شش بخش مختلف PHPDoc در لاراول می‌پردازیم:

1) Builder Helpers

2)Properties

3)Timestamps

4) Accessors

5)روابط (Relationships) و 6) Scopeها.

Builder Helpers

اول از همه، از آنجایی که تمام متدهایی که در مدل نیستند به یک نمونه Eloquent Builder جدید منتقل می شوند، باید از دستور mixin@ استفاده کنیم و به کلاس Builder اشاره کنیم. این به IDE ما می گوید که می توانیم متدهای کلاس mixin را از این کلاس فراخوانی کنیم.

/**
 * @mixin \Illumiate\Database\Elequent\Builder
 */

class User extends Model 
{
 // ...
}

معمولاً ایده خوبی برای مقابله با متد ()query است که فراخوانی ()newQuery است و بیشتر به صورت داخلی توسط لاراول استفاده می شود. باز کردن با ()query به IDE شما اجازه می‌دهد تا در اسکوپ های محلی شما نیز ترکیب شود، زیرا ما نیز آن را برای برگرداندن مدل تنظیم کرده‌ایم.

بقیه اعلان‌ها برای اینکه به IDE بگوییم که به جای یک نمونه عمومی، همان نمونه مدل را برمی‌گردانیم، مورد نیاز است. لیست بسیار بزرگ است اما با این وجود مفید است.

/**
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post newModelQuery()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post newQuery()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post query()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post whereTitle($value)
 */
 class Post extends Model 
{
 // ...
}

Properties

یکی از مجیک های ORM Eloquent ویژگی های پویا هستند که در صورت عدم وجود آنها null می شوند.

/**
 * App\Models\Post
 *
 * @property integer $id
 * @property integer $author_id
 * @property string $title
 * @property string $text
 * @property-read \User $author

 * …
 */

شما می توانید شروع به نوشتن property@ برای هر کدام با نوع و نام آن کنید. می‌توانید از هر property که برای شما مفید نیست، مانند ستون‌های رمز عبور و یادداشت توکن صرف نظر کنید.

Timestamps

تایم‌استمپ‌ها به صورت خودکار در لاراول برای ردیابی زمان ایجاد و به‌روزرسانی رکوردها استفاده می‌شوند. در اینجا مثالی از مستندسازی یک مدل با استفاده از Laravel IDE Helper برای timestamps آورده شده است:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

/**
 * کلاس مدل کاربر
 *
 * @property \Illuminate\Support\Carbon $created_at
 * @property \Illuminate\Support\Carbon $updated_at
 */
class User extends Model {
    // ...
}

Accessors

Accessors به شما اجازه می‌دهند تا مقادیر ویژگی‌ها را قبل از دسترسی به آن‌ها اصلاح کنید. در اینجا مثالی از مستندسازی یک accessor در مدل User آورده شده است:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

/**

 *
 * @property string $first_name
 * @property string $last_name
 * @property-read string $full_name
 */
class User extends Model {
    // ...

    /**
     * دریافت نام کامل کاربر
     *
     * @return string
     */
    public function getFullNameAttribute() {
        return "{$this->first_name} {$this->last_name}";
    }
}

در این مثال، یک accessor به نام full_name تعریف شده است که نام کامل کاربر را برمی‌گرداند. مستندسازی این ویژگی با استفاده از property-read@ انجام شده است.

Relationships

روابط در لاراول برای تعریف روابط بین مدل‌ها استفاده می‌شوند. در اینجا مثالی از مستندسازی روابط در مدل User آورده شده است:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;

/**
 * @property-read \Illuminate\Database\Eloquent\Collection|Post[] $posts
 * @property-read \Illuminate\Database\Eloquent\Collection|Role[] $roles
 */
class User extends Model {
    // ...

    /**
     * تعریف رابطه یک به چند با پست‌ها
     *
     * @return \Illuminate\Database\Eloquent\Relations\HasMany
     */
    public function posts(): HasMany {
        return $this->hasMany(Post::class);
    }

    /**
     * تعریف رابطه چند به چند با نقش‌ها
     *
     * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany
     */
    public function roles(): BelongsToMany {
        return $this->belongsToMany(Role::class);
    }
}

در این مثال، روابط posts و roles با استفاده از property-read@ مستندسازی شده‌اند تا نشان دهند که این روابط به عنوان مجموعه‌ای از مدل‌های مرتبط عمل می‌کنند.

لاراول ماکرو چیست؟ آشنایی عمیق با Macro

تست معماری در لاراول با PEST

Scopes

Scopes به شما اجازه می‌دهند تا شرایط کوئری های تکراری را در یک مکان مرکزی تعریف کنید. در اینجا مثالی از مستندسازی scopes در مدل User آورده شده است:

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

/**
 *
 * @method static \Illuminate\Database\Eloquent\Builder|User active()
 * @method static \Illuminate\Database\Eloquent\Builder|User inactive()
 */
class User extends Model {
    // ...

    /**
     * محدوده مربوط به کاربران فعال
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeActive(Builder $query) {
        return $query->where('status', 'active');
    }

    /**
     * محدوده مربوط به کاربران غیرفعال
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeInactive(Builder $query) {
        return $query->where('status', 'inactive');
    }
}

تولید مستندات

برای ایجاد مستندات از کامنت PHPDoc خود در لاراول، می توانید از ابزارهایی مانند phpDocumentor استفاده کنید. این نرم افزار کد PHP شما را پردازش می کند و اسناد را به فرمت های مختلف مانند HTML، PDF یا XML استخراج می کند.

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

phpdoc -d app/ -t public/docs

برای آشنایی با ENUM ها در PHP این مقاله از آنوفل را بررسی کنید.

نتیجه

در این مقاله، ما اصول کامنت Laravel PHPDoc، از استفاده اولیه تا تکنیک‌های مستندسازی پیشرفته‌تر را پوشش داده‌ایم. با مستندسازی مؤثر کد خود، نه تنها پایگاه کد خود را قابل درک تر می کنید، بلکه همکاری با سایر توسعه دهندگان را نیز آسان می کنید. علاوه بر این، ابزارهای خودکار می توانند اطلاعات ارزشمندی را از کامنت شما استخراج کنند تا مستندات جامع ایجاد کنند.

کامنت PHPDoc را در گردش کار توسعه لاراول خود بپذیرید و مشاهده کنید که کد شما قابل نگهداری تر و قابل دسترس تر می شود. دقت کنید، کد خوب فقط در مورد نوشتن نرم افزار کاربردی نیست. همچنین در مورد حصول اطمینان از اینکه دیگران به راحتی می توانند آن را درک کنند، استفاده کنند و بر اساس آن بسازند، است.

دوره های آموزشی

مسیر یادگیری

کامنت های PHPDoc لاراول : داکیومنت نویسی به صورت حرفه ای

Mohammad Abdorrahmani