آموزش نصب و شروع به کار Filament

اگر به دنبال یک ابزار قدرتمند و ساده برای ساخت پنل‌های مدیریت در پروژه‌های Laravel هستید، نصب و شروع به کار Filament یکی از بهترین گزینه‌هاست. در این مقاله آموزشی Filament، قصد داریم شما را از مراحل اولیه نصب تا پیکربندی پیشرفته راهنمایی کنیم. با این آموزش، حتی اگر مبتدی باشید، می‌توانید به‌راحتی Filament را نصب کرده و شروع به کار کنید.

پیش‌نیازها در Filament

قبل از شروع به نصب و راه‌اندازی Filament، نیاز است که برخی از پیش‌نیازهای نرم‌افزاری و تنظیمات پایه را بر روی سیستم خود آماده کرده باشید. این پیش‌نیازها برای اطمینان از عملکرد صحیح و بهینه Filament ضروری هستند. در این بخش، به تفصیل توضیح می‌دهیم که چه چیزهایی باید روی سیستم شما نصب و پیکربندی شوند تا بتوانید به‌راحتی Filament را نصب و راه‌اندازی کنید.

 نسخه PHP و تنظیمات موردنیاز

برای اجرای Filament، شما نیاز به نسخه‌ای از PHP دارید که حداقل به نسخه 8.0 به‌روز باشد. Filament از ویژگی‌های جدید و قابلیت‌های پیشرفته‌ای که در نسخه‌های جدید PHP وجود دارد، استفاده می‌کند. بنابراین، اطمینان از نصب نسخه مناسب PHP یکی از اولین مراحل نصب است.

نسخه PHP: حداقل 8.0

Filament از ویژگی‌های جدید PHP، مانند ویژگی‌های بهبود یافته در عملکرد، امنیت، و زبان‌شناسی استفاده می‌کند که فقط در نسخه‌های جدید PHP موجود است. بنابراین باید از نسخه 8.0 یا بالاتر استفاده کنید.

برای بررسی نسخه PHP نصب‌شده در سیستم خود، می‌توانید دستور زیر را در ترمینال اجرا کنید:

php -v

این دستور نسخه PHP فعلی را به شما نشان می‌دهد. اگر نسخه PHP شما کمتر از 8.0 است، باید آن را به‌روزرسانی کنید. برای به‌روزرسانی PHP، بسته به سیستم‌عامل خود، روش‌های مختلفی وجود دارد.

افزونه‌های PHP

Filament به چندین افزونه PHP نیاز دارد تا به‌طور صحیح اجرا شود. این افزونه‌ها به Filament کمک می‌کنند تا داده‌ها را به‌درستی پردازش کند و از قابلیت‌های خاصی مانند مدیریت کاراکترهای یونیکد یا درخواست‌های HTTP پشتیبانی کند. افزونه‌های ضروری عبارتند از:

ext-json: این افزونه برای پردازش داده‌های JSON در PHP ضروری است. JSON فرمت استاندارد برای تبادل داده‌ها است و Filament برای ذخیره‌سازی و تبادل داده‌ها از این فرمت استفاده می‌کند.
ext-mbstring: این افزونه برای پردازش رشته‌های چندبایتی (مانند زبان‌های غیرلاتین) ضروری است. به‌ویژه اگر در پروژه‌های خود نیاز به پشتیبانی از زبان‌هایی مانند فارسی یا عربی داشته باشید، این افزونه اهمیت ویژه‌ای دارد.
ext-curl: این افزونه برای ارسال درخواست‌های HTTP به سرورهای خارجی مورد استفاده قرار می‌گیرد. Filament ممکن است برای برخی عملیات‌ها مانند احراز هویت یا ارسال داده‌ها نیاز به این قابلیت داشته باشد.
برای بررسی اینکه آیا این افزونه‌ها فعال هستند یا نه، می‌توانید دستور زیر را در ترمینال اجرا کنید:

php -m

این دستور فهرستی از تمام افزونه‌های فعال PHP را نشان می‌دهد. اگر هرکدام از این افزونه‌ها غیرفعال بودند، می‌توانید آن‌ها را با دستورهای زیر نصب کنید:

برای نصب افزونه ext-json:

sudo apt-get install php-json

برای نصب افزونه ext-mbstring:

sudo apt-get install php-mbstring

برای نصب افزونه ext-curl:

sudo apt-get install php-curl

به‌روزرسانی PHP

اگر سیستم شما به نسخه جدید PHP نیاز دارد، بسته به سیستم‌عامل خود مراحل زیر را دنبال کنید:

در سیستم‌عامل‌های لینوکس (Ubuntu): برای به‌روزرسانی PHP به نسخه 8.0 یا بالاتر، از دستورات زیر استفاده کنید:

sudo apt update
sudo apt install php8.0
sudo apt install php8.0-cli php8.0-fpm php8.0-mbstring php8.0-json php8.0-curl

در macOS (با استفاده از Homebrew): برای نصب یا به‌روزرسانی PHP از طریق Homebrew:

brew install php

در Windows: از وب‌سایت PHP فایل‌های مربوطه را دانلود کرده و نصب کنید.

نصب Composer

Composer یک ابزار مدیریتی برای مدیریت وابستگی‌ها در PHP است و برای نصب Filament و دیگر پکیج‌های PHP ضروری است. Composer به‌طور خودکار تمامی وابستگی‌های موردنیاز پروژه شما را نصب می‌کند و به‌راحتی می‌توانید پکیج‌های مختلف را مدیریت کنید.

نصب Composer

برای نصب Composer در سیستم، مراحل زیر را دنبال کنید:

به وب‌سایت Composer مراجعه کنید و دستور نصب را کپی کنید.
دستور نصب Composer را در ترمینال وارد کنید. در سیستم‌های لینوکس و macOS:

curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

برای نصب در ویندوز، به وب‌سایت Composer رفته و برنامه نصب‌کننده ویندوز را دانلود کنید.

بررسی صحت نصب

پس از نصب Composer، برای اطمینان از نصب صحیح آن، دستور زیر را در ترمینال اجرا کنید:

composer -v

اگر Composer به‌درستی نصب شده باشد، نسخه آن نمایش داده می‌شود.

تنظیم پایگاه داده

Filament برای ذخیره‌سازی اطلاعات مربوط به کاربران، رول‌ها، تنظیمات پنل مدیریت و دیگر داده‌ها به یک پایگاه داده نیاز دارد. Filament از انواع مختلف پایگاه داده‌ها پشتیبانی می‌کند، از جمله MySQL، PostgreSQL، SQLite و دیگر سیستم‌های پایگاه داده.

تنظیم پایگاه داده در فایل .env

برای تنظیم پایگاه داده در پروژه Laravel، شما باید اطلاعات مربوط به اتصال پایگاه داده را در فایل .env وارد کنید. به‌طور پیش‌فرض، Laravel از MySQL استفاده می‌کند، اما شما می‌توانید از پایگاه داده‌های دیگر نیز استفاده کنید.

مقدارهای متداول در فایل .env به‌صورت زیر است:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

DB_CONNECTION: نوع پایگاه داده (mysql، sqlite، postgres و غیره).
DB_HOST: آدرس سرور پایگاه داده. معمولاً برای پایگاه داده محلی به مقدار 127.0.0.1 تنظیم می‌شود.
DB_PORT: پورت پایگاه داده (پورت پیش‌فرض برای MySQL معمولاً 3306 است).
DB_DATABASE: نام پایگاه داده‌ای که می‌خواهید از آن استفاده کنید.
DB_USERNAME: نام کاربری پایگاه داده.
DB_PASSWORD: رمز عبور پایگاه داده.

اجرای دستورات مهاجرت

بعد از تنظیم فایل .env، برای ساخت جداول پایگاه داده مورد نیاز Filament، باید دستورات مهاجرت Laravel را اجرا کنید. این دستورات جداول پیش‌فرض مانند جدول کاربران، نقش‌ها، و تنظیمات Filament را در پایگاه داده ایجاد می‌کنند.

برای انجام این کار، دستور زیر را در ترمینال اجرا کنید:

php artisan migrate

این دستور تمامی جداول مورد نیاز برای Filament را به‌طور خودکار ایجاد می‌کند. پس از اجرای موفق این دستور، می‌توانید از پایگاه داده برای ذخیره‌سازی داده‌ها استفاده کنید.

نصب Filament

در این بخش، به‌طور کامل نحوه نصب Filament در پروژه Laravel و راه‌اندازی پنل مدیریت آن را توضیح خواهیم داد. این مراحل شامل نصب پکیج Filament با استفاده از Composer، ایجاد فایل‌ها و تنظیمات اولیه با دستور make:filament، و در نهایت راه‌اندازی پنل مدیریت است. با دنبال کردن این مراحل، شما به راحتی می‌توانید Filament را به پروژه Laravel خود اضافه کنید و از امکانات آن بهره‌برداری کنید.

نصب با Composer

اولین گام برای نصب Filament این است که پکیج آن را به پروژه Laravel خود اضافه کنید. برای این کار، از ابزار Composer استفاده می‌کنیم. Composer به‌عنوان ابزار مدیریت وابستگی‌ها در PHP، به شما کمک می‌کند تا به‌راحتی پکیج‌ها و کتابخانه‌ها را نصب و مدیریت کنید.

مراحل نصب:
ابتدا ترمینال یا Command Prompt را باز کنید.
به دایرکتوری ریشه پروژه Laravel خود بروید.
دستور زیر را برای نصب Filament اجرا کنید:

composer require filament/filament

این دستور، پکیج filament/filament را به پروژه شما اضافه می‌کند. Composer به‌طور خودکار تمامی وابستگی‌های موردنیاز برای اجرای Filament را نصب می‌کند. پس از اتمام نصب، شما قادر خواهید بود تا از قابلیت‌های پنل مدیریت Filament استفاده کنید.

نکات:
اگر پروژه شما در حالت توسعه (development) قرار دارد، Composer به‌طور خودکار فایل‌های موردنیاز را در پوشه vendor دانلود و نصب می‌کند.
اگر در حین نصب با ارورهای مربوط به نسخه PHP یا تنظیمات Composer مواجه شدید، مطمئن شوید که نسخه PHP شما به‌روز است و Composer به‌درستی نصب شده است.

اجرای دستور make:filament

بعد از نصب پکیج Filament، مرحله بعدی اجرای دستور make:filament است. این دستور به شما کمک می‌کند تا فایل‌ها و تنظیمات اولیه موردنیاز برای راه‌اندازی Filمنت را ایجاد کنید.

مراحل اجرای دستور:
در ترمینال، در دایرکتوری ریشه پروژه، دستور زیر را اجرا کنید:

php artisan make:filament

این دستور به‌طور خودکار فایل‌ها و تنظیمات اولیه Filament را در پروژه شما ایجاد می‌کند. برخی از این فایل‌ها شامل موارد زیر هستند:

فایل‌های پیکربندی: این فایل‌ها شامل تنظیمات مربوط به Filament هستند و در پوشه config پروژه قرار می‌گیرند.
پوشه‌های منبع (source): برای ایجاد پنل مدیریت و رابط کاربری، Filament به پوشه‌هایی در resources/views نیاز دارد.
مسیرها (routes): تنظیم مسیرهای دسترسی به پنل مدیریت در فایل‌های مسیرهای Laravel اعمال می‌شود.
دستورات (commands): برخی دستورات Artisan جدید برای مدیریت Filament به پروژه شما افزوده می‌شود.
نکات:
این دستور تنها یک‌بار باید اجرا شود و به‌صورت خودکار تمامی فایل‌های موردنیاز برای تنظیمات اولیه Filament را ایجاد می‌کند.
اگر به دلایلی نیاز به بازنشانی یا اعمال دوباره این دستور داشته باشید، می‌توانید با استفاده از دستور php artisan migrate:reset جداول را پاک کنید و سپس دوباره دستور make:filament را اجرا کنید.

راه‌اندازی پنل مدیریت
حالا که پکیج Filament به پروژه شما اضافه شد و فایل‌ها و تنظیمات اولیه ایجاد شدند، می‌توانید پنل مدیریت Filament را راه‌اندازی کنید.

دسترسی به پنل مدیریت
برای دسترسی به پنل مدیریت Filament، باید URL مربوطه را در مرورگر وارد کنید. به‌طور پیش‌فرض، Filament پنل مدیریت خود را در مسیر /admin راه‌اندازی می‌کند.

آدرس پیش‌فرض به‌صورت زیر خواهد بود:

http://your-domain.com/admin

جایگزین your-domain.com با دامنه یا آدرس لوکال‌سرور (برای مثال localhost یا 127.0.0.1) خود کنید.

نکته:
اگر می‌خواهید مسیر پیش‌فرض /admin را تغییر دهید، می‌توانید این تنظیمات را در فایل پیکربندی config/filament.php اعمال کنید. به‌عنوان مثال، برای تغییر مسیر به /dashboard:

'path' => 'dashboard',

ورود به پنل مدیریت:
در اولین بار ورود به پنل مدیریت، شما نیاز به یک کاربر ادمین دارید تا دسترسی به پنل مدیریت فراهم شود. Filament این امکان را برای شما فراهم کرده که به‌سادگی کاربر ادمین جدیدی ایجاد کنید.

برای ایجاد کاربر ادمین، دستور زیر را در ترمینال اجرا کنید:

http://your-domain.com/admin

این دستور به شما اجازه می‌دهد تا اطلاعات کاربر ادمین (مانند نام، ایمیل، و رمز عبور) را وارد کنید.

مراحل ایجاد کاربر ادمین:
پس از اجرای دستور، از شما خواسته می‌شود که اطلاعات کاربر جدید را وارد کنید. اطلاعات موردنیاز عبارتند از:

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

دسترسی به پنل مدیریت:
اکنون که کاربر ادمین ایجاد شد، شما می‌توانید به پنل مدیریت از طریق آدرس زیر وارد شوید:

http://your-domain.com/admin

و با استفاده از ایمیل و رمز عبور وارد شده، به عنوان ادمین وارد پنل شوید.

نکات تکمیلی:
Filament به‌طور پیش‌فرض از سیستم احراز هویت Laravel استفاده می‌کند، بنابراین اگر از قبل سیستم احراز هویت را در پروژه خود پیاده‌سازی کرده باشید، Filament به‌طور خودکار از آن استفاده خواهد کرد.
برای ایجاد کاربران و مدیریت سطح دسترسی‌ها، می‌توانید از امکانات پیشرفته‌تری مانند پروژه‌های مختلف، پروفایل‌ها، دسترسی‌های کاربری، و رول‌ها که در Filament وجود دارند، استفاده کنید.

تنظیمات اولیه

در این بخش، به بررسی و تنظیم موارد اولیه برای پیکربندی Filament در پروژه Laravel می‌پردازیم. این تنظیمات به شما کمک می‌کنند تا کنترل بیشتری بر روی مسیرها، امنیت، و دسترسی‌ها در پنل مدیریت خود داشته باشید. با انجام این مراحل، شما می‌توانید محیط مدیریت خود را به‌طور بهینه‌تر و امن‌تر تنظیم کنید.

 پیکربندی مسیرها

به‌طور پیش‌فرض، Filament پنل مدیریت را در مسیر /admin قرار می‌دهد. این مسیر به‌راحتی قابل تغییر است و شما می‌توانید آن را به هر مسیر دلخواهی تنظیم کنید. تغییر مسیر پنل مدیریت می‌تواند برای جلوگیری از مشکلات امنیتی و همچنین ایجاد تجربه کاربری بهتر مفید باشد.

مراحل تغییر مسیر پنل مدیریت:

به فایل پیکربندی Filament بروید که در مسیر config/filament.php قرار دارد.
در این فایل، تنظیمی به نام path وجود دارد که مسیر دسترسی به پنل مدیریت را تعیین می‌کند.
مقدار path را به مسیری که مدنظر دارید تغییر دهید. به‌عنوان مثال، اگر می‌خواهید پنل مدیریت به جای /admin در مسیر /dashboard قرار گیرد، باید این تغییر را اعمال کنید.
مثال:

'path' => 'dashboard',

اکنون مسیر پنل مدیریت شما به http://your-domain.com/dashboard تغییر کرده است. با این تغییر، دیگر نمی‌توان به‌طور پیش‌فرض به پنل مدیریت دسترسی پیدا کرد و تنها از مسیری که شما تعیین کرده‌اید می‌توان به آن دسترسی داشت.

نکات:
این تنظیمات به‌راحتی تغییرپذیر هستند و شما می‌توانید هر مسیری که به‌طور خاص برای پروژه شما مناسب است، انتخاب کنید.
تغییر مسیر می‌تواند برای افزایش امنیت مفید باشد زیرا حملات خودکار یا اسکن‌کننده‌ها معمولاً از مسیرهای پیش‌فرض مانند /admin برای یافتن پنل‌های مدیریت استفاده می‌کنند.

امنیت و دسترسی‌های اولیه

یکی از مهم‌ترین جنبه‌های هر پروژه‌ای که پنل مدیریت دارد، امنیت آن است. Filament به شما این امکان را می‌دهد که امنیت پنل مدیریت خود را افزایش دهید. یکی از روش‌های افزایش امنیت، محدود کردن دسترسی به پنل مدیریت تنها به IPهای خاص است. همچنین، می‌توانید از سیاست‌های دسترسی برای کنترل دقیق‌تر کاربران استفاده کنید.

محدود کردن دسترسی به IPهای خاص

برای افزایش امنیت، می‌توانید پنل مدیریت Filament را تنها برای IPهای خاص محدود کنید. به این ترتیب، تنها کاربران با آدرس‌های IP مشخص شده می‌توانند به پنل مدیریت دسترسی پیدا کنند.

برای این کار، به فایل پیکربندی config/filament.php بروید و مقادیر مربوط به middleware را ویرایش کنید:

در فایل config/filament.php، بخش middleware را پیدا کنید.

مقادیر مربوط به middleware را به‌صورت زیر تغییر دهید:

'middleware' => [
    'web',
    'auth',
    'can:access-filament',
],

سپس به فایل AuthServiceProvider.php بروید که در پوشه app/Providers قرار دارد و یک سیاست دسترسی برای محدود کردن کاربران اضافه کنید.

تعریف سیاست دسترسی

در AuthServiceProvider.php، باید سیاستی برای تعیین اینکه کدام کاربران مجاز به دسترسی به پنل مدیریت هستند، تعریف کنید. این سیاست می‌تواند برای کنترل دسترسی به پنل مدیریت Filament استفاده شود. در اینجا از یک ویژگی ساده به نام is_admin برای تعیین دسترسی استفاده خواهیم کرد.

به فایل AuthServiceProvider.php بروید.

در داخل متد boot()، یک سیاست جدید تعریف کنید:

Gate::define('access-filament', function ($user) {
    return $user->is_admin;
});

این سیاست می‌گوید که فقط کاربرانی که مقدار is_admin آن‌ها true است، می‌توانند به پنل مدیریت دسترسی پیدا کنند.

نکات:
این سیاست به شما این امکان را می‌دهد که دسترسی به پنل مدیریت را تنها به مدیران محدود کنید و سایر کاربران به هیچ عنوان به پنل مدیریت دسترسی نخواهند داشت.
می‌توانید سیاست‌های پیچیده‌تری برای کنترل دسترسی اضافه کنید، به‌عنوان مثال، محدود کردن دسترسی به بخش‌های خاص از پنل مدیریت بر اساس نقش یا سطوح مختلف دسترسی.

تعریف کاربر ادمین

برای اطمینان از اینکه تنها کاربران خاص می‌توانند به پنل مدیریت دسترسی پیدا کنند، باید یک ویژگی به نام is_admin را به جدول کاربران خود اضافه کنید. این ویژگی مشخص می‌کند که کدام کاربران به‌عنوان ادمین در نظر گرفته می‌شوند و می‌توانند به پنل مدیریت دسترسی داشته باشند.

مراحل اضافه کردن ویژگی is_admin به جدول کاربران:

ابتدا با دستور زیر یک مهاجرت جدید برای افزودن ستون is_admin به جدول کاربران ایجاد کنید:

php artisan make:migration add_is_admin_to_users_table --table=users

در فایل مهاجرت که به‌طور خودکار ایجاد می‌شود، ستون is_admin را به جدول users اضافه کنید. این ستون از نوع boolean خواهد بود و به‌طور پیش‌فرض false خواهد بود، که نشان‌دهنده این است که کاربر ادمین نیست.

مثال کد در فایل مهاجرت:

public function up()
{
    Schema::table('users', function (Blueprint $table) {
        $table->boolean('is_admin')->default(false);
    });
}

public function down()
{
    Schema::table('users', function (Blueprint $table) {
        $table->dropColumn('is_admin');
    });
}

پس از اعمال تغییرات در فایل مهاجرت، دستور زیر را اجرا کنید تا ستون is_admin به جدول users اضافه شود:

php artisan migrate

اکنون می‌توانید ویژگی is_admin را برای هر کاربری که نیاز به دسترسی به پنل مدیریت دارد، تنظیم کنید. به‌عنوان مثال، اگر می‌خواهید کاربری با شناسه 1 را به‌عنوان ادمین تعریف کنید، دستور زیر را اجرا کنید:

$user = User::find(1);
$user->is_admin = true;
$user->save();

نکات:
is_admin به‌طور پیش‌فرض به false تنظیم می‌شود، بنابراین برای هر کاربر جدید که ایجاد می‌کنید، باید این ویژگی را به‌طور دستی تنظیم کنید.
شما می‌توانید با افزودن سیاست‌های اضافی (مانند دسترسی به صفحه‌های خاص یا بخش‌های خاص پنل مدیریت) از این ویژگی برای کنترل دقیق‌تر استفاده کنید.

با انجام این تنظیمات اولیه، شما می‌توانید پنل مدیریت Filament خود را به‌طور موثری پیکربندی کرده و امنیت آن را به‌طور قابل توجهی افزایش دهید. از تغییر مسیر پنل مدیریت تا تعیین دسترسی‌ها و ایجاد کاربران ادمین، این تنظیمات به شما این امکان را می‌دهند که یک سیستم مدیریت امن و قابل‌اعتماد بسازید که تنها کاربران مجاز به آن دسترسی دارند.

نتیجه‌گیری

در این مقاله، به‌طور کامل فرآیند نصب و شروع به کار Filament را بررسی کردیم و مراحل نصب، تنظیمات اولیه، و پیکربندی‌های ضروری آن را توضیح دادیم. با استفاده از Composer، توانستید Filament را به پروژه Laravel خود اضافه کنید و با دستورات ساده‌ای مانند make:filament و make:filament-user پنل مدیریت خود را راه‌اندازی کنید. همچنین، با پیکربندی مسیرها، امنیت و دسترسی‌ها، توانستید محیط مدیریت خود را به‌صورت امن‌تر و مطابق نیازهای پروژه تنظیم کنید.

با یادگیری آموزش Filament و پیاده‌سازی این تنظیمات، شما قادر خواهید بود یک پنل مدیریت قدرتمند و انعطاف‌پذیر بسازید که علاوه بر راحتی استفاده، امنیت بالایی نیز داشته باشد. اکنون می‌توانید به‌راحتی از امکانات Filament برای مدیریت و توسعه پروژه‌های Laravel خود استفاده کنید.