آموزش صفر تا صد نصب و راه‌اندازی Larapex Charts در لاراول

استفاده از نمودارها بهترین ابزار برای خلاصه‌سازی داده‌های حجیم دیتابیس و نمایش آن‌ها به کاربران است. در فرآیند توسعه وب و به خصوص در طراحی پنل مدیریت، طراحی CRM یا حتی طراحی ERP، نمایش بصری داده‌ها اهمیت دوچندانی پیدا می‌کند. در این مقاله قصد داریم قدم‌به‌قدم طبق مستندات وب‌سایت رسمی پکیج Larapex Charts جلو برویم و یاد بگیریم چطور انواع چارت‌های جذاب را در لایه فرانت‌اِند لاراول رندر کنیم. این مبحث برای هر توسعه دهنده Laravel یا برنامه نویس Laravel که به دنبال پیاده‌سازی اصولی گزارش‌های گرافیکی است، اهمیت بالایی دارد.

⚡ قدم اول: نصب پکیج و انتشار فایل کانفیگ

ابتدا ترمینال پروژه خود را باز کرده و با اجرای دستور زیر، پکیج را از طریق کامپوزر نصب کنید:

composer require arielmejiadev/larapex-charts

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

php artisan vendor:publish --tag=larapex-charts-config

📊 قدم دوم: ساخت کلاس نمودار با منوی انتخابی ترمینال

حالا یک کلاس اختصاصی برای مدیریت داده‌های نمودار می‌سازیم:

php artisan make:chart MonthlyUsersChart

💡

"نکته مهم در ترمینال"

به محض اجرای این دستور، لاراول از شما می‌پرسد که مایلید از کدام نوع چارت استفاده کنید. کافیست با کلیدهای جهت‌نما (Arrow Keys) روی گزینه مورد نظر (مثلاً Pie Chart) بروید و کلید Enter را بزنید.

حالا فایل نمودار شما در مسیر app/Charts/MonthlyUsersChart.php آماده ویرایش است تا به عنوان یک برنامه نویس وب یا توسعه دهنده وب بتوانید داده‌ها را به شکل بهینه مدیریت کنید.

کافی است این فایل را باز کرده و ساختار آن را به شکل زیر پیکربندی کنید:

namespace App\Charts;

use ArielMejiaDev\LarapexCharts\LarapexChart;

class MonthlyUsersChart
{
    public function build()
    {
        return (new LarapexChart)->pieChart()
            ->setTitle('Top 3 scorers of the team.')
            ->setSubtitle('Season 2021.')
            ->addData([40, 50, 30])
            ->setLabels(['Player 7', 'Player 10', 'Player 9']);
    }
}

این متد به صورت پیش‌فرض یک نمودار دایره‌ای (Pie Chart) با داده‌های استاتیک ایجاد می‌کند که بعداً می‌توانید آن را به بانک اطلاعاتی متصل کنید؛ ابزاری حیاتی که در پروژه هایی مثل طراحی فروشگاه اینترنتی یا ساخت سامانه آنلاین، به توسعه دهنده Laravel کمک می‌کند گزارش‌های بصری خیره‌کننده‌ای برای بخش مدیریتی خلق کند.

⚙️ قدم سوم: اتصال نمودار به کنترلر و روت

ابتدا یک کنترلر به صورت Resource بسازید:

php artisan make:controller UserController -r

سپس فایل app/Http/Controllers/UserController.php را باز کرده و کلاس چارت را به متد index تزریق کنید:

namespace App\Http\Controllers;

use App\Charts\MonthlyUsersChart;

class UserController extends Controller
{
    public function index(MonthlyUsersChart $chart)
    {
        return view("users.index", ["chart" => $chart->build()]);
    }
}

حالا مسیر زیر را در فایل routes/web.php بنویسید تا درخواست‌ها به کنترلر هدایت شوند:

use App\Http\Controllers\UserController;

Route::get("/users", [UserController::class, "index"])->name("users.index");

🖥️ قدم چهارم: نمایش چارت در قالب Blade (با Tailwind CSS)

یک فایل ویو در مسیر resources/views/users/index.blade.php ایجاد کنید و کدهای زیر را درون آن قرار دهید:

<!doctype html>
<html lang="fa" dir="rtl">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>نمونه نمودار لاراول</title>
    <link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">
</head>
<body class="h-screen bg-gray-100">

<div class="container px-4 mx-auto">
    <div class="p-6 m-20 bg-white rounded shadow">
        {!! $chart->container() !!}
    </div>
</div>

<script src="{{ $chart->cdn() }}"></script>
{{ $chart->script() }}
</body>
</html>

💡 بررسی متدها و پیش‌نمایش گرافیکی انواع چارت‌ها

برای تغییر نوع نمودار، کافیست متد بازگشتی را در متد build کلاس چارت خود عوض کنید. در باکس‌های زیر کدهای کنترلر به همراه خروجی زنده و بصری آن‌ها شبیه‌سازی شده است که این ساختار تاثیر مستقیمی بر بهبود شاخص‌های Laravel Performance در مانیتورینگ سیستم دارد:

۱. نمودار دایره‌ای (Pie Chart)

مناسب برای نشان دادن سهم‌های مختلف از یک کل (مانند برترین گلزنان تیم)

<?php
return (new LarapexChart)->pieChart()
    ->setTitle("Top 3 scorers of the team.")
    ->setSubtitle("Season 2021.")
    ->addData([20, 24, 30])
    ->setLabels(["Player 7", "Player 10", "Player 9"]);

Total

Player 7 (40%) Player 10 (30%) Player 9 (30%)

۲. نمودار حلقوی (Radial Chart)

فوق‌العاده برای نمایش میزان پیشرفت یا بازدهی مقایسه‌ای با رنگ‌بندی دلخواه

<?php
return (new LarapexChart)->radialChart()
    ->setTitle("Passing effectiveness.")
    ->setSubtitle("Barcelona city vs Madrid sports.")
    ->addData([75, 60])
    ->setLabels(["Barcelona city", "Madrid sports"])
    ->setColors(["#D32F2F", "#03A9F4"]);

75%

60%

Barca Madrid

۳. نمودار قطبی (Polar Area Chart)

یک جایگزین جذاب برای نمودارهای دایره‌ای زمانی که شعاع هر بخش مقادیر متفاوتی دارد

<?php
return (new LarapexChart)->polarAreaChart()
    ->setTitle("Top 3 scorers of the team.")
    ->setSubtitle("Season 2021.")
    ->addData([20, 24, 30])
    ->setLabels(["Player 7", "Player 10", "Player 9"]);

P7 P10 P9

۴. نمودار خطی (Line Chart)

بهترین انتخاب برای نمایش روند تغییرات در طول ماه‌های سال (مانند مقایسه فروش)

<?php
return (new LarapexChart)->lineChart()
    ->setTitle("Sales during 2021.")
    ->setSubtitle("Physical sales vs Digital sales.")
    ->addData([40, 93, 35, 42, 18, 82], "Physical sales")
    ->addData([70, 29, 77, 28, 55, 45], "Digital sales")
    ->setXAxis(["January", "February", "March", "April", "May", "June"]);

Physical Digital

Jan - Jun

۵. نمودار مساحتی (Area Chart)

نمایش روند تغییرات فروش فیزیکی و دیجیتال در طول زمان

<?php
return (new LarapexChart)->areaChart()
    ->setTitle("Sales during 2021.")
    ->setSubtitle("Physical sales vs Digital sales.")
    ->addData([40, 93, 35, 42, 18, 82], "Physical sales")
    ->addData([70, 29, 77, 28, 55, 45], "Digital sales")
    ->setXAxis(["January", "February", "March", "April", "May", "June"]);

Physical Digital

Jan - Jun

۶. نمودار ستونی عمودی (Bar Chart)

مقایسه تعداد بردهای دو تیم سان‌فرانسیسکو و بوستون

<?php
return (new LarapexChart)->barChart()
    ->setTitle("San Francisco vs Boston.")
    ->setSubtitle("Wins during season 2021.")
    ->addData([6, 9, 3, 4, 10, 8], "San Francisco")
    ->addData([7, 3, 8, 2, 6, 4], "Boston")
    ->setXAxis(["January", "February", "March", "April", "May", "June"]);

SF Boston

Jan - Apr

۷. نمودار ستونی افقی (Horizontal Bar Chart)

مقایسه افقی بردهای لس‌آنجلس و میامی

<?php
return (new LarapexChart)->horizontalBarChart()
    ->setTitle("Los Angeles vs Miami.")
    ->setSubtitle("Wins during season 2021.")
    ->addData([6, 9, 3, 4, 10, 8], "Los Angeles")
    ->addData([7, 3, 8, 2, 6, 4], "Miami")
    ->setXAxis(["January", "February", "March", "April", "May", "June"]);

LA Miami

M1 - M3

۸. نمودار حرارتی (Heatmap Chart)

تراکم تعداد پوش‌های کد در روزهای هفته طی ۴ هفته

<?php
return (new LarapexChart)->heatMapChart()
    ->setTitle("Code Push Activity")
    ->addData([5, 12, 8, 15, 23, 18], "Week 1")
    ->addData([8, 15, 20, 12, 9, 25], "Week 2")
    ->addData([12, 8, 14, 22, 17, 10], "Week 3")
    ->addData([18, 22, 15, 11, 20, 16], "Week 4")
    ->setXAxis(["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]);

Low Activity High

۹. نمودار راداری (Radar Chart)

تحلیل و مقایسه ویژگی‌های مهارتی بازیکن در فصل اول

<?php
return (new LarapexChart)->radarChart()
    ->setTitle("Individual Player Stats.")
    ->setSubtitle("Season 2021.")
    ->addData([70, 93, 78, 97, 50, 90], "First Season")
    ->setXAxis(["Pass", "Dribble", "Shot", "Stamina", "Long shots", "Tactical"])
    ->setMarkers(["#303F9F"], 7, 10);

Stats Overview