دستورهای اختصاصی CLI با استفاده از کامپوننت کنسول سمفونی (Symfony) – به زبان ساده

در این مقاله قصد داریم ساخت دستورهای اختصاصی رابط خط فرمان (CLI) در برنامه‌های PHP با استفاده از کامپوننت کنسول سمفونی را بررسی کنیم. پس از نصب کتابخانه‌های لازم، چند مثال برای نمایش مفاهیم کامپوننت‌های کنسول مطرح می‌کنیم. در واقع این کامپوننت از سوی چند فریمورک PHP برای توسعه برنامه‌های CLI مورد استفاده قرار گرفته است و چند فریمورک نیز قبلاً از این کامپوننت به عنوان نقطه شروع خود بهره گرفته‌اند.

منظور از کامپوننت کنسول چیست؟

کامپوننت کنسول سمفونی امکان ساخت دستورهای اختصاصی CLI را در برنامه‌های PHP فراهم ساخته است. اگر تاکنون با لاراول (Laravel) یا سمفونی کار کرده باشید، ممکن است از ابزارهای CLI که برای عملیات‌های روزمره‌ای مانند موارد زیر ارائه می‌کند، آگاه باشید:

• تولید کد داربست (scaffolding)
• پاک‌سازی کش
• نصب، فعال‌سازی و غیر فعال‌سازی سرویس‌های افزونه‌ای
• اجرای عملیات‌های انتقال پایگاه داده
• و موارد دیگر...

برای مثال در لاراول ابزاری به نام artisan وجود دارد که دستورهای کاربردی فراوانی برای تسهیل امور مختلف دارد. ممکن است تعجب کنید، اگر بدانید که می‌توانید دستورهای CLI سفارشی در برنامه‌های PHP بسازید. برای آغاز این کار می‌بایست کامپوننت کنسول را با استفاده از Composer نصب کنید. پس از نصب، چند نمونه برای نمایش منظور خود ارائه می‌کنیم.

نصب و پیکربندی

در این بخش قصد داریم کامپوننت کنسول که برای ساخت دستورهای اختصاصی CLI در برنامه‌های PHP ضروری است را نصب کنیم. فرض می‌کنیم که قبلاً Composer را روی سیستم خود نصب دارید، چون برای نصب کامپوننت کنسول که در Packagist قرار دارد به آن نیاز داریم. زمانی که کامپوزر را نصب کردید، می‌بایست کامپوننت کنسول را با استفاده از دستور زیر نصب کنید:

$composer require symfony/console

بدین ترتیب فایل composer.json که شبیه حالت زیر است ایجاد می‌شود:

{
    "require": {
        "symfony/console": "^4.0"
    }
}

فایل composer.json را طوری تغییر می‌دهیم که شبیه حالت زیر باشد:

{
    "require": {
        "symfony/console": "^4.0"
    },
    "autoload": {
         "psr-4": {
             "Console\\": "src"
         },
         "classmap": ["src"]
     }
}

از آنجا که مدخل جدیدی به صورت clasmap اضافه کرده‌ایم، کار خود را ادامه داده و اتولودر کامپوزر را با اجرای دستور زیر به‌روزرسانی می‌کنیم:

$composer dump -o

اینک می‌توانید از فضای نام Console برای بارگذاری خودکار کلاس‌های موجود در دایرکتوری src استفاده کنید.

نخستین دستور اختصاصی به صورت HelloWorld

ایجاد دستورهای CLI در کامپوننت کنسول یک فرایند دومرحله‌ای است:

• نخست باید یک برنامه کنسول بسازید که وابستگی‌های مورد نیاز را بارگذاری کرده و دستورهای اختصاصی شما را ثبت کند.
• سپس باید فایل‌هایی برای همه دستورهایی که در برنامه کنسول ثبت کرده‌اید، ایجاد کنید.

فیلم آموزش رایگان API نویسی برای فریم ورک سیمفونی Symfony در PHP + گواهینامه در فرادرس

کلیک کنید

ایجاد برنامه کنسول

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

|-- bin
|   `-- console
|-- composer.json
|-- composer.lock
|-- src
|   `-- App
|       `-- Commands
|           |-- ClearcacheCommand.php
|           `-- HelloworldCommand.php
`-- vendor

سپس فایل اصلی برنامه به نام bin/console را با محتوای زیر ایجاد می‌کنیم. لطفاً توجه داشته باشید که این فایل هیچ پسوندی ندارد و همچنین مطمئن شود که این فایل قابل‌اجرا (executable) است، چون باید آن را از خط فرمان اجرا کنیم.

#!/usr/bin/env php
<?php require_once __DIR__ . '/../vendor/autoload.php'; use Symfony\Component\Console\Application; $app = new Application(); $app->run();

خط اول فایل #!/usr/bin/env php برای این است که مطمئن شویم این فایل در محیط PHP قرار دارد. سپس این فایل را اجرا می‌کنیم تا ببینیم کارها چطور پیش می‌رود.

$bin/console
Console Tool
 
Usage:
  command [options] [arguments]
 
Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
Available commands:
  help  Displays help for a command
  list  Lists commands

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

ایجاد فایل دستور Hello World

در ادامه نخستین دستور اختصاصی به صورت HelloworldCommand را می‌سازیم. بدین منظور فایل src/App/Commands/HelloworldCommand.php را با محتوای زیر ایجاد می‌کنیم:

<?php namespace Console\App\Commands; use Symfony\Component\Console\Command\Command; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Output\OutputInterface; use Symfony\Component\Console\Input\InputArgument; class HelloworldCommand extends Command { protected function configure() { $this->setName('hello-world')
            ->setDescription('Prints Hello-World!')
            ->setHelp('Demonstration of custom commands created by Symfony Console component.')
            ->addArgument('username', InputArgument::REQUIRED, 'Pass the username.');
    }
 
    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln(sprintf('Hello World!, %s', $input->getArgument('username')));
    }
}

دو متد اصلی وجود دارند که باید در هنگام ایجاد دستور اختصاصی خود بسازید: configure و execute. همان طور که نام این متدها نشان می‌دهد؛ متد configure امکان پیکربندی دستور را فراهم می‌سازد، به طوری که می‌توانید نام دستور، توضیحی کوتاه، متن help و موارد دیگر را تعیین کنید. همچنین اگر می‌خواهید پارامترهایی را در هنگام اجرای دستور به آن ارسال کنید، می‌توانید آرگومان‌هایی برای دستور خود تعیین کنید.

در مثال فوق نام دستور به صورت hello-world تعیین می‌شود. همچنین می‌خواهیم یک نام کاربری به عنوان آرگومان اول به این دستور ارسال کنیم و از این رو آن را با استفاده از متد addArgument پیکربندی می‌کنیم. از سوی دیگر متد execute شامل منطق برنامه‌ای دستور است. در این مورد ما منطق دستور را با نمایش یک عبارت «Hello World» در خروجی دستور تا حد امکان ساده نگه داشته‌ایم. پیش از آن که به کار خود ادامه دهیم و دستور را به طور عملی اجرا کنیم، باید آن را در برنامه کنسولی که در بخش قبلی ساخته‌ایم، ثبت کنیم. فایل bin/console را به سرعت اصلاح می‌کنیم تا به صورت زیر در بیاید:

#!/usr/bin/env php
<?php require_once __DIR__ . '/../vendor/autoload.php'; use Symfony\Component\Console\Application; use Console\App\Commands\HelloworldCommand; $app = new Application(); $app->add(new HelloworldCommand());
$app->run();

همان طور که می‌بینید ما از متد add برای شیء Application استفاده کرده‌ایم تا دستور HelloworldCommand را به آن اضافه کنیم. همه دستورهای موجود را به سرعت فهرست می‌کنیم:

$bin/console list
Console Tool
 
Usage:
  command [options] [arguments]
 
Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
Available commands:
  hello-world      Prints Hello-World!
  help             Displays help for a command
  list             Lists commands

همان طور که انتظار داریم دستور Hello-world در فهرست دستورهای موجود ظاهر می‌شود. اینک می‌توانیم آن را اجرا کنیم.

$bin/console hello-world tutsplus
Hello World!, tutsplus

کل فرایند ساخت دستورهای اختصاصی در کامپوننت کنسول سمفونی بدین ترتیب بود.

نمونه دنیای واقعی – دستور پاک‌سازی کش

در بخش قبلی یک دستور hello-world را برای نمایش مفاهیم کامپوننت کنسول ساختیم. در این بخش قصد داریم یک نمونه دنیای واقعی بسازیم که به شما نشان می‌دهد چگونه می‌توانید دستوری برای پاک‌سازی حافظه کش در برنامه خود ایجاد کنید.

ایجاد فایل دستور پاک‌سازی حافظه کش

در این بخش فایل src/App/Commands/ClearcacheCommand.php را با محتوای زیر می‌سازیم:

<?php namespace Console\App\Commands; use Symfony\Component\Console\Command\Command; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Output\OutputInterface; use Symfony\Component\Console\Input\InputArgument; use Symfony\Component\Console\Input\InputOption; class ClearcacheCommand extends Command { protected function configure() { $this->setName('clear-cache')
            ->setDescription('Clears the application cache.')
            ->setHelp('Allows you to delete the application cache. Pass the --groups parameter to clear caches of specific groups.')
            ->addOption(
                    'groups',
                    'g',
                    InputOption::VALUE_OPTIONAL,
                    'Pass the comma separated group names if you don\'t want to clear all caches.',
                    ''
                );
    }
 
    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln('Cache is about to cleared...');
 
        if ($input->getOption('groups'))
        {
            $groups = explode(",", $input->getOption('groups'));
 
            if (is_array($groups) && count($groups))
            {
                foreach ($groups as $group)
                {
                    $output->writeln(sprintf('%s cache is cleared', $group));
                }
            }
        }
        else
        {
            $output->writeln('All caches are cleared.');
        }
 
        $output->writeln('Complete.');
    }
}

متد configure دقیقاً همانند دستور قبلی است به جز این که از متد adoption برای افزودن یک گزینه به دستور خود استفاده می‌کنیم. با افزودن این گزینه می‌توانید مقادیر گروهی را با استفاده از پارامتر groups-- به دستور ارسال کنید.

از سوی دیگر متد execute شامل منطق برنامه‌ای دستور ما است. اگر بخواهید حافظه کش گروه‌های خاصی را پاک کنید، باید نام‌های گروه را همراه با پارامتر groups-- به این دستور ارسال کنید. از طرف دیگر می‌توانید در صورتی که بخواهید حافظه کش همه گروه‌ها را پاک کنید، از این پارامتر استفاده نکنید. ممکن است متوجه شده باشید که با تعیین مقدار InputOption::VALUE_OPTIONAL در سومین آرگومان متد adoption این پارامتر را به صورت اختیاری تعیین کردیم.

ثبت و تست در برنامه کنسول

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

#!/usr/bin/env php
<?php require_once __DIR__ . '/../vendor/autoload.php'; use Symfony\Component\Console\Application; use Console\App\Commands\HelloworldCommand; use Console\App\Commands\ClearcacheCommand; $app = new Application(); $app->add(new HelloworldCommand());
$app->add(new ClearcacheCommand());
$app->run();
$app->run();

اینک می‌توانید دستور bin/console clear-cache را برای پاک‌سازی حافظه کش اجرا کنید:

$bin/console clear-cache
Cache is about to cleared...
All caches are cleared.
Complete.

اگر می‌خواهید کش‌های خاصی را پاک کنید؛ می‌توانید دستوری مانند دستور زیر را امتحان کنید:

$bin/console clear-cache --groups=group1,group2
Cache is about to cleared...
group1 cache is cleared
group2 cache is cleared
Complete.

البته می‌توانید از این دستور واقعاً برای پاک‌سازی کش ها استفاده کنید؛ اما برای شروع یادگیری این دستورهای اختصاصی نیز نقطه خوبی محسوب می‌شود.

نتیجه‌گیری

در این نوشته یکی از کامپوننت‌های محبوب ارائه شده از سوی فریمورک سمفونی، یعنی کامپوننت کنسول را بررسی کردیم. این کامپوننت واقعاً مفید است و به وسیله آن می‌توانید برنامه CLI اختصاصی خود را بسازید که به شما کمک می‌کند وظایف روزمره خود را به سهولت انجام دهید. در نیمه نخست این نوشته روش نصب و پیکربندی کامپوننت را آموختیم و در بخش دوم نیز چند مثال برای دستورهای کنسول ساختیم.

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

• مجموعه آموزش های PHP
• آموزش های رایگان PHP
• مجموعه آموزش‌های طراحی و برنامه نویسی وب
• گنجینه برنامه نویسی PHP
• آموزش برنامه نویسی PHP
• آموزش فریمورک لاراول PHP Laravel برای ساخت فروشگاه اینترنتی

==