مدیریت پکیج در لاراول — به زبان ساده

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

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

برای نمایش این مفهوم یک صفحه نمونه در لاراول می‌سازیم تا تصاویر را به کلود Amazon S3 آپلود کنیم. به این منظور به جای پیگیری گردش کار معمول آن را به صورت یک پکیج بسته‌بندی می‌کنیم که می‌تواند به سادگی توزیع یافته و نگهداری شود.

پیش از ادامه کار فرض ما بر این است که شما از قبل با فریمورک لاراول آشنا هستید، چون در این نوشته قرار است به بررسی جزییات مبانی مفاهیم لاراول بپردازیم.

ضمناً باید یک حساب معتبر AWS داشته باشید و از رمز عبور این حساب برای دسترسی به API آمازون استفاده کنید و به این ترتیب بتوانید مراحل این مقاله را عملاً پیگیری کنید. بنابراین ابتدا مطمئن شوید که این موضوع را تنظیم کرده‌اید. زمانی که همه چیز آماده شد، می‌توانیم به مراحل توسعه عملی بپردازیم.

راه‌اندازی فایل‌های پکیج

در ادامه فهرست خلاصه‌ای از فایل‌هایی را که در طی این دوره آموزشی پیاده‌سازی خواهیم کرد مشاهده می‌کنید.

فیلم آموزش مقدماتی فریم ورک لاراول Laravel برای توسعه برنامه های تحت وب در فرادرس

کلیک کنید

• composer.json – این نگاشت کلاس را باید به پکیج خود در فایل composer.json در ریشه پکیج اضافه کنیم.
• config/app.php – این یک فایل از قبل موجود است که از آن برای افزودن مدخل ارائه‌دهنده سرویس سفارشی خودمان استفاده می‌کنیم و به این ترتیب می‌توانیم انواع «نما» (View) و «مسیر» (Route) را با استفاده از آن فایل بارگذاری کنیم.
• composer.json – این فایل composer.json مختص پکیج است و برای پکیجی که می‌خواهید با دیگران به اشتراک بگذارید استفاده می‌شود.
• packages/envato/aws/src/Providers/AwsServiceProvider.php – این فایل ارائه‌دهنده سرویس معمولی لاراول است که کامپوننت‌های دیگر پکیج را بارگذاری خواهد کرد.
• packages/envato/aws/src/routes/web.php – این فایل مسیرهای سفارشی پکیج ما را بارگذاری می‌کند.
• packages/envato/aws/src/Controllers/AwsController.php – این فایل کنترلر است که منطق اپلیکیشن پکیج ما را مدیریت می‌کند.
• packages/envato/aws/src/views/upload.blade.php – فایل view است که اقدام به مدیریت منطق رندر می‌کند.

اگر از خواندن فهرست فوق چیز زیادی دستگیرتان نشد، نگران نباشید، چون در ادامه همه این موارد را به تفصیل بررسی خواهیم کرد.

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

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

شما به عنوان یک توسعه‌دهنده لاراول باید با Flysystem که یک لایه انتزاع زیبا برای تعامل با فایل‌سیستم ارائه می‌کند، آشنا باشید. این پکیج درایورهای با کاربری آسان ارائه می‌کند که به وسیله آن‌ها می‌توانید به راحتی با فایل‌سیستمهای مختلف کار کنید و مهم نیست که فایل‌سیستم روی یک دیسک محلی است و یا سیستم کلود S3 آمازون است.

برای فعال‌سازی پشتیبانی از فایل‌سیستم کلود S3 آمازون در Flysystem، شما باید پکیج کامپوزر آداپتر متناظر را نصب کنید. به این منظور دستور کامپوزر زیر را از ریشه پروژه اجرا کنید تا پکیج flysystem-aws-s3-v3 نصب شود:

$composer require league/flysystem-aws-s3-v3

به محض اجرای موفق این دستور، می‌توانید از Flysystem برای تعامل با فایل‌سیستم کلود S3 آمازون به همان روش که برای فایل‌سیستم لوکال استفاده می‌کردید، بهره بگیرید.

اکنون می‌توانید فایل config/filesystems.php را به سرعت pull کرده و تنظیمات ارائه شده برای فایل‌سیستم S3 آمازون را مشاهده کنید.

1...
2...
3'disks' => [
4    'local' => [
5        'driver' => 'local',
6        'root' => storage_path('app'),
7    ],
8 
9    'public' => [
10        'driver' => 'local',
11        'root' => storage_path('app/public'),
12        'url' => env('APP_URL').'/storage',
13        'visibility' => 'public',
14    ],
15 
16    's3' => [
17        'driver' => 's3',
18        'key' => env('AWS_KEY'),
19        'secret' => env('AWS_SECRET'),
20        'region' => env('AWS_REGION'),
21        'bucket' => env('AWS_BUCKET'),
22    ],
23],
24...
25...

چنان که می‌بینید، پیکربندی از قبل برای S3 آمازون تنظیم شده است و صرفاً کافی است که متغیرهای ENV مناسب را در فایل env. تنظیم کنیم. پا را فراتر گذارده و متغیرهای زیر را در فایل env. اضافه کنید.

AWS_KEY={AWS_KEY_VALUE}
AWS_SECRET={AWS_SECRET_VALUE}
AWS_REGION={AWS_REGION_VALUE}
AWS_BUCKET={AWS_BUCKET_VALUE}
AWS_CDN_URL={AWS_CDN_URL_VALUE}

البته باید مقادیر placeholder را با مقادیر واقعی‌شان پر کنید. اکنون آماده هستید که از آداپتر Flysystem AWS S3 در اپلیکیشن لاراول خود استفاده کنید.

بررسی فایل‌های پکیج

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

فیلم آموزش لاراول Laravel برای توسعه برنامه‌ های تحت وب – تکمیلی در فرادرس

کلیک کنید

در ادامه دایرکتوری Packages را در ریشه اپلیکیشن ایجاد می‌کنیم. با توجه به این که قصد داریم پکیج را با دیگران به اشتراک بگذاریم، ساختار ترجیحی پکیج باید به صورت {vendor_name}/{package_name} باشد.

با پیروی از همین قرارداد، می‌توانیم یک دایرکتوری envato/aws زیر دایرکتوری packages ایجاد کنیم. چنان که احتمالاً حدس می‌زنید، envato نام ارائه‌ دهنده است و aws اشاره به خود نام پکیج دارد. در نهایت یک دایرکتوری packages/envato/aws/src ایجاد می‌کنیم که فایل‌های منبع پکیج را نگهداری می‌کند.

اکنون باید وجود پکیج جدید خود را به لاراول اطلاع دهیم. به این منظور فایل composer.json را در ریشه اپلیکیشن لاراول باز می‌کنیم و مدخل "Envato\\Aws\\": "packages/envato/aws/src" را در بخش autoload به صورت زیر اضافه می‌کنیم:

1...
2...
3"autoload": {
4    "classmap": [
5        "database"
6    ],
7    "psr-4": {
8        "App\\": "app/",
9        "Envato\\Aws\\": "packages/envato/aws/src"
10    }
11},
12...
13...

چنان که می‌بینید، فضای نام Envato\Aws\ به دایرکتوری packages/envato/aws/src نگاشت شده است. اکنون باید دستور dump-autoload را اجرا کرده و نگاشت‌های کامپوزر را باز تولید کنیم.

$composer dump-autoload

در این مرحله می‌توانیم با استفاده از فضای نام Envato\Aws\ در اپلیکیشن، فایل‌ها را از مکان صحیحشان انتخاب کنیم.

فایل کامپوزر پکیج

در این مرحله یک فایل composer.json خاص پکیج اضافه می‌کنیم که می‌توان به وسیله آن پکیج را روی ریپازیتوری packagist توزیع کنیم. به این منظور به دایرکتوری packages/envato/aws بروید و دستور زیر را برای تولید فایل composer.json برای پکیج خود اجرا کنید:

$composer init

در این مرحله برخی سؤالات معمولی از شما پرسیده می‌شود که باید به آن‌ها پاسخ دهید تا یک فایل composer.json ایجاد کنید. در کمترین حالت این فایل باید چیزی مانند زیر باشد:

1{
2    "name": "envato/aws",
3    "description": "Example of File Upload to AWS S3 Cloud",
4    "minimum-stability": "dev",
5    "require": {}
6}

مسیر

در این پکیج یک صفحه نمونه می‌سازیم که وضعیت فایل آپلود شده را نمایش خواهد داد. بنابراین باید یک مسیر ایجاد کنیم که با آن صفحه متناظر باشد. در ادامه فایل مسیر را در آدرس packages/envato/aws/src/routes/web.php به صورت زیر ایجاد می‌کنیم:

1<?php
2Route::get('aws/s3/upload', 'Envato\Aws\Controllers\AwsController@upload');

این فایل به توضیح چندانی نیاز ندارد. گام بدیهی بعدی نیز این است که فایل کنترلر مربوطه را ایجاد کنیم.

کنترلر

در این زمان یک فایل کنترلر در مسیر packages/envato/aws/src/Controllers/AwsController.php با محتوای زیر ایجاد می‌کنیم:

1<?php
2namespace Envato\Aws\Controllers;
3 
4use App\Http\Controllers\Controller;
5 
6class AwsController extends Controller
7{
8  public function upload(\Illuminate\Contracts\Filesystem\Factory $storage)
9  {
10    // load s3 storage
11    $awsS3Storage = $storage->disk('s3');
12     
13    // load local storage
14    $localStorage = $storage->disk('local');
15 
16    // default path of local storage "storage/app"
17    $sourceFileContents = $localStorage->get('test.jpg');
18     
19    // destination filepath in S3 cloud
20    $destFilePath = 'test_new.jpg';
21     
22    // init vars
23    $imageUrl = '';
24    $errorMsg = '';
25 
26    // upload file to AWS S3
27    if ($awsS3Storage->put($destFilePath, $sourceFileContents, 'public'))
28    {
29      $imageUrl = env('AWS_CDN_URL') . env('AWS_BUCKET') . '/' . $destFilePath;
30    }
31    else
32    {
33      $errorMsg = 'Oops! Something went wrong :(';
34    }
35 
36    // call view
37    return view('aws::upload', ['imageUrl' => $imageUrl, 'errorMsg' => $errorMsg]);
38  }
39}

در ادامه جزییات فایل فوق را به تفصیل بررسی می‌کنیم تا با کارکرد هر یک از خطوط کد آشنا شویم.

در آغاز یک فضای نام برای کنترلر به صورت فضای نام Envato\Aws\Controllers تنظیم می‌کنیم. به خاطر داشته باشید که باید در ریشه composer.json یک نگاشت از Envato\Aws به packages/envato/aws/src اضافه کنید تا بتواند فایل‌های پکیج را پیدا کند.

سپس متد upload را تعریف می‌کنیم که برای همگام‌سازی فایل‌های محلی با کلود S3 آمازون یک متد ضروری محسوب می‌شود. این نکته مهم را نیز به خاطر داشته باشید که آرگومان نخست متد upload نیازمند وابستگی \Illuminate\Contracts\Filesystem\Factory است. در طی اجرای این متد، قرارداد لاراول مناسب تزریق خواهد شد.

اکنون می‌توانیم از وهله‌ای از filesystem factory برای ایجاد وهله‌های دیسک بسته به نیاز استفاده کنیم. وهله دیسک در لاراول، درایوری است که امکان دسترسی آسان به فایل‌سیستم‌های زیرین مانند دیسک محلی، کلود S3 آمازون و موارد مشابه را فراهم می‌سازد.

1// load s3 storage
2$awsS3Storage = $storage->disk('s3');
3     
4// load local storage
5$localStorage = $storage->disk('local');

برای سادگی موضوع، فایل تصویر استاتیک را که از قبل در فضای ذخیره‌سازی محلی پیش‌فرض لاراول موجود و مسیر آن به صورت storage/app/test.jpg است را انتقال می‌دهیم. به عنوان نخستین گام محتوای فایل منبع را انتخاب می‌کنیم.

1// default path of local storage "storage/app"
2$sourceFileContents = $localStorage->get('test.jpg');

زمانی که همه چیز مطابق انتظار راه‌اندازی شد، می‌توانید فایل‌ها را با استفاده از متد زیر با S3 آمازون همگام‌سازی کنید.

1// upload file to AWS S3
2if ($awsS3Storage->put($destFilePath, $sourceFileContents, 'public'))
3{
4  $imageUrl = env('AWS_CDN_URL') . env('AWS_BUCKET') . '/' . $destFilePath;
5}
6else
7{
8  $errorMsg = 'Oops! Something went wrong :(';
9}

در صورتی که موردی به درستی کار نکرد، باید مطمئن شوید که متغیرهای محیطی AWS به درستی تنظیم شده‌اند.

و آخرین کاری که باید انجام داد این است که یک فایل view را فراخوانی کنید تا تصویر همگام‌سازی شده و پیام مناسبی را نمایش دهد.

1// call view
2return view('aws::upload', ['imageUrl' => $imageUrl, 'errorMsg' => $errorMsg]);

البته ما هنوز این فایل view را ایجاد نکرده‌ایم و این همان کاری است که دقیقاً در بخش بعدی قرار است اجرا کنیم.

View

در این بخش یک فایل ویو در مسیر packages/envato/aws/src/views/upload.blade.php و با محتوای زیر می‌سازیم:

1<!DOCTYPE html>
2<html lang="{{ config('app.locale') }}">
3    <head>
4        <meta charset="utf-8">
5        <meta http-equiv="X-UA-Compatible" content="IE=edge">
6        <meta name="viewport" content="width=device-width, initial-scale=1">
7 
8        <title>Laravel</title>
9 
10        <!-- Fonts -->
11        <link href="https://fonts.googleapis.com/css?family=Raleway:100,600" rel="stylesheet" type="text/css">
12 
13        <!-- Styles -->
14        <style>
15            html, body {
16                background-color: #fff;
17                color: #636b6f;
18                font-family: 'Raleway', sans-serif;
19                font-weight: 100;
20                height: 100vh;
21                margin: 0;
22            }
23 
24            .full-height {
25                height: 100vh;
26            }
27 
28            .flex-center {
29                align-items: center;
30                display: flex;
31                justify-content: center;
32            }
33 
34            .position-ref {
35                position: relative;
36            }
37 
38            .top-right {
39                position: absolute;
40                right: 10px;
41                top: 18px;
42            }
43 
44            .content {
45                text-align: center;
46            }
47 
48            .title {
49                font-size: 84px;
50            }
51 
52            .links > a {
53                color: #636b6f;
54                padding: 0 25px;
55                font-size: 12px;
56                font-weight: 600;
57                letter-spacing: .1rem;
58                text-decoration: none;
59                text-transform: uppercase;
60            }
61 
62            .m-b-md {
63                margin-bottom: 30px;
64            }
65        </style>
66    </head>
67    <body>
68        <div class="flex-center position-ref full-height">
69            @if (Route::has('login'))
70                <div class="top-right links">
71                    @if (Auth::check())
72                        <a href="{{ url('/home') }}">Home</a>
73                    @else
74                        <a href="{{ url('/login') }}">Login</a>
75                        <a href="{{ url('/register') }}">Register</a>
76                    @endif
77                </div>
78            @endif
79 
80            <div class="content">
81                <div class="title m-b-md">
82                    File upload to S3 Cloud
83                </div>
84 
85                <div>
86                  @if ($imageUrl)
87                      <img src="{{ $imageUrl }}" width="100"/>
88                  @else
89                      <span class="error">{{ $errorMsg }}</span>
90                  @endif
91                </div>
92            </div>
93        </div>
94    </body>
95</html>

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

ارائه‌دهنده سرویس

ما کار خود را با پکیج تقریباً به پایان برده‌ایم، چون همه فایل‌های لازم را با موفقیت ایجاد کرده‌ایم. گام بعدی این است که یک ارائه‌دهنده سرویس بسازیم به طوری که بتوانیم مسیرها و ویوهای پکیج خود را بسازیم. در ادامه یک فایل ارائه‌دهنده سرویس در مسیر packages/envato/aws/src/Providers/AwsServiceProvider.php و با محتوای زیر ایجاد می‌کنیم:

1<?php
2 
3namespace Envato\Aws\Providers;
4 
5use Illuminate\Support\ServiceProvider;
6 
7class AwsServiceProvider extends ServiceProvider
8{
9  /**
10   * Bootstrap the application services.
11   *
12   * @return void
13   */
14  public function boot()
15  {
16      // load routes
17      $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
18 
19      // load view files
20      $this->loadViewsFrom(__DIR__.'/../views', 'aws');
21       
22      // publish files
23      $this->publishes([
24      __DIR__.'/../views' => resource_path('views/vendor/aws'),
25    ]);
26  }
27 
28  /**
29   * Register the application services.
30   *
31   * @return void
32   */
33  public function register()
34  {
35  }
36}

بدیهی است که می‌توانستیم فایل ارائه‌دهنده سرویس را با استفاده از دستور آرتیزان نیز بسازیم. اما این کار نیازمند گام‌های اضافی انتقال فایل از app/Providers به پکیج بود.

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

1// load routes
2$this->loadRoutesFrom(__DIR__.'/../routes/web.php');
3 
4// load view files
5$this->loadViewsFrom(__DIR__.'/../views', 'aws');

سپس پشتیبانی از انتشار ویوهای پکیج را ارائه می‌کنیم به طوری که توسعه‌دهندگانی که می‌خواهند ویوها را override کنند بتوانند این کار را انجام دهند. دفعه بعد که دستور php artisan vendor:publish اجرا شود، لاراول ویوها را از packages/envato/aws/src/views/ به resources/views/vendor/aws کپی می‌کند.

اکنون توسعه‌دهندگان دیگر می‌توانند ویوها را زیر دایرکتوری resources/views/vendor/aws تغییر دهند و این فایل‌ها به جای ویوهای زیر دایرکتوری packages/envato/aws/src/views/ به صورت خودکار از سوی لاراول انتخاب می‌شوند. در واقع، این روش صحیح ایجاد تغییر در ویوهای پکیج شخص ثالث به جای تغییر دادن مستقیم ویوهای پکیج محسوب می‌شود.

بدین ترتیب کار ما با فایل ارائه‌دهنده سرویس به پایان می‌رسد. چنان که انتظار دارید باید مدخل ارائه‌دهنده سرویس را در config/app.php اضافه کنیم. مدخل زیر را در آرایه providers وارد کنید.

1...
2...
3/*
4 * Application Service Providers...
5 */
6App\Providers\AppServiceProvider::class,
7App\Providers\AuthServiceProvider::class,
8App\Providers\BroadcastServiceProvider::class,
9App\Providers\EventServiceProvider::class,
10App\Providers\RouteServiceProvider::class,
11Envato\Aws\Providers\AwsServiceProvider::class, // Our package service provider
12...
13...

بدین ترتیب کار ما به پایان می‌رسد. اینک همه چیز نظم خود را یافته است و از این رو می‌توانیم در ادامه به تست پکیج خود بپردازیم.

در ادامه URL به صورت http://your-laravel-application/aws/s3/upload را در مرورگر خود وارد کنید. اگر همه چیز به درستی پیش برود باید تصویری را که از کلود S3 آمازون بارگذاری می‌شود ببینید. بدین ترتیب راهنمای ما نیز به پایان می‌رسد.

سخن پایانی

در این مقاله به بررسی یکی از مهم‌ترین قابلیت‌های فریمورک لاراول یعنی مدیریت پکیج پرداختیم. در فرایند راه‌اندازی پکیج سفارشی لاراول یک مثال عملی را بررسی کردیم که روش آپلود تصویر روی کلود S3 آمازون را نمایش می‌داد.

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

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

• مجموعه آموزش‌‌های برنامه‌نویسی PHP
• گنجینه برنامه‌نویسی PHP
• مجموعه آموزش‌های برنامه‌‌نویسی
• زمانبندی وظایف در لاراول (Laravel) — راهنمای مقدماتی
• انتشار لاراول (Laravel Broadcasting) چگونه کار می‌ کند؟ — راهنمای کاربردی

==