php cli

PHP-Cli

PHP-Cli هي مكتبة بسيطة تساعد في إنشاء نصوص سطر الأوامر اللطيفة.

يعتني به

• خيار التحليل
• مساعدة صفحات المساعدة
• ضبط العرض التلقائي
• الإخراج الملون
• توافق PSR3 الاختياري

إنه خفيف الوزن وليس لديه تبعيات طرف ثالث . ملاحظة: هذا للبرامج النصية غير التفاعلية فقط. لا يوجد لديه دعم أو دعم مماثل.

تثبيت

استخدم الملحن:

php composer.phar require splitbrain/php-cli

الاستخدام والأمثلة

مثال أدنى:

 #!/usr/bin/php
<?php
require __DIR__ . ' /../vendor/autoload.php ' ;
use splitbrain  phpcli  CLI ;
use splitbrain  phpcli  Options ;

class Minimal extends CLI
{
    // register options and arguments
    protected function setup ( Options $ options )
    {
        $ options -> setHelp ( ' A very minimal example that does nothing but print a version ' );
        $ options -> registerOption ( ' version ' , ' print version ' , ' v ' );
    }

    // implement your code
    protected function main ( Options $ options )
    {
        if ( $ options -> getOpt ( ' version ' )) {
            $ this -> info ( ' 1.0.0 ' );
        } else {
            echo $ options -> help ();
        }
    }
}
// execute it
$ cli = new Minimal ();
$ cli -> run ();

الاستخدام الأساسي بسيط:

• قم بإنشاء فئة extend splitbrainphpcliCLI
• قم بتنفيذ طريقة setup($options) وتسجيل الخيارات والوسائط والأوامر وضبط نصوص المساعدة
  • $options->setHelp() يضيف وصفًا عامًا
  • $options->registerOption() يضيف خيارًا
  • $options->registerArgument() يضيف وسيطة
  • $options->registerCommand() يضيف أمرًا فرعيًا
• قم بتنفيذ طريقة main($options) والقيام بمنطق عملك هناك
  • $options->getOpts الوصول إلى خيارات تعيين مجموعة
  • $options->getArgs() إرجاع الوسائط المتبقية بعد إزالة الخيارات
  • $options->getCmd() إرجاع الأمر الفرعي الذي استخدمه المستخدم
• قم بتثبيت الفصل الدراسي الخاص بك و Call run() عليه

يمكن العثور على المزيد من الأمثلة في دليل الأمثلة. يرجى الرجوع إلى مستندات API لمزيد من المعلومات.

استثناءات

بشكل افتراضي ، تقوم فئة CLI بتسجيل معالج استثناء وستقوم بطباعة رسالة الاستثناء إلى المستخدم النهائي والخروج من البرنامج برمز خروج غير صفري. يمكنك تعطيل هذا السلوك والتقاط كل الاستثناءات بنفسك عن طريق تمرير خطأ إلى المُنشئ.

يمكنك استخدام splitbrainphpcliException للإشارة إلى أي مشاكل ضمن الكود الرئيسي بنفسك. سيتم استخدام رمز الاستثناء كرمز الخروج بعد ذلك.

سيتم طباعة StackTraces على debug مستوى السجل.

الإخراج الملون

يتم التعامل مع الإخراج الملون من خلال فئة Colors . يحاول اكتشاف ما إذا كانت محطة الألوان متوفرة وبعد ذلك فقط تستخدم الألوان الطرفية. يمكنك دائمًا قمع الإخراج الملون عن طريق المرور --no-colors إلى البرامج النصية الخاصة بك. سيؤدي تعطيل الألوان أيضًا إلى تعطيل بادئات الرموز.

يمكن طباعة رسائل السجل الملونة البسيطة بواسطتك باستخدام success() (أخضر) أو info() (سماوي) أو error() (أحمر) أو fatal() (أحمر). هذا الأخير سوف يخرج أيضًا من البرنامج برمز خروج غير صفري.

للحصول على تلوين أكثر تعقيدًا ، يمكنك الوصول إلى فئة الألوان من خلال $this->colors في البرنامج النصي الخاص بك. ربما تكون طريقة wrap() هي ما تريد استخدامه.

يسمح تنسيق الجدول بتلوين الأعمدة الكاملة. لاستخدام هذه الآلية تمر مجموعة من الألوان كمعلمة ثالثة إلى طريقة format() . يرجى ملاحظة أنه لا يمكنك تمرير نصوص ملونة في المعلمات الثانية (حساب طول النص ولف التفاف ، وكسر النصوص الخاصة بك).

جدول التنسيق

تتيح لك فئة TableFormatter محاذاة النصوص في أعمدة متعددة. يحاول معرفة العرض الطرفي المتاح من تلقاء نفسه. يمكن الكتابة فوقها عن طريق تعيين متغير بيئة COLUMNS .

يتم استخدام formatter من خلال طريقة format() التي تتوقع صفيفتين على الأقل: الأول يحدد عرض العمود ، والثاني يحتوي على النصوص لملء الأعمدة. بين كل عمود ، تتم طباعة الحدود (مساحة واحدة بشكل افتراضي).

انظر example/table.php لاستخدام العينة.

يمكن إعطاء عرض الأعمدة بثلاثة أشكال:

• عرض ثابت في الأحرف من خلال توفير عدد صحيح (على سبيل المثال 15 )
• قبلات من خلال تقديم عدد صحيح وعلامة في المئة (على سبيل المثال 25% )
• عمود "REST" السائل واحد مميزة بعلامة النجمة (على سبيل المثال * )

عند خلط العروض الثابتة والنسبة المئوية ، تشير النسب المئوية إلى المساحة المتبقية بعد تعيين جميع الأعمدة الثابتة.

يتم حساب مساحة الحدود تلقائيًا. من المستحسن أن يكون لديك دائمًا بعض نسبة (النسبة المئوية) أو عمود السوائل لضبط عروض الطرفية المختلفة.

يتم استخدام تنسيق الجدول لشاشة المساعدة التلقائية التي يمكن الوصول إليها عند الاتصال بالبرنامج النصي باستخدام -h أو --help .

تسجيل PSR-3

فئة CLI عبارة عن مسجل متوافق تمامًا مع PSR-3 (طباعة بيانات السجل الملونة إلى Stdout و Stderr). يكون هذا مفيدًا عند استدعاء رمز الواجهة الخلفية من CLI الخاص بك والذي يتوقع مثيل لوجبر لإنتاج أي إخراج حالة معقول أثناء التشغيل.

إذا كنت بحاجة إلى تمرير فئة تنفذ PsrLogLoggerInterface فيمكنك القيام بذلك عن طريق الوراثة من أحد الفئتين المقدمة التي تنفذ هذه الواجهة بدلاً من splitbrainphpcliCLI .

• استخدم splitbrainphpcliPSR3CLI إذا كنت تستخدم الإصدار 2 من PSR3 (php <8.0)
• استخدم splitbrainphpcliPSR3CLIv3 إذا كنت تستخدم الإصدار 3 من PSR3 (php> = 8.0)

ثم يمكن تمرير الكائن الناتج كمثيل المسجل. الفرق بين الاثنين هو في توقيعات الطريقة المعدلة (مع التلميح من النوع المناسب) فقط. تأكد من تثبيت حزمة الملحن psr/log المقترحة عند استخدام هذه الفئات.

ملاحظة: إذا كان رمز الواجهة الخلفية لديك يتصل بمسجل PSR-3 ولكنه لا يكتب في الواقع التحقق من الواجهة (ويعرف أيضًا باسم LoggerAware فقط) ، فيمكنك أيضًا تمرير مثيل لـ splitbrainphpcliCLI .

مستويات السجل

يمكنك ضبط فعل أداة CLI الخاصة بك باستخدام المعلمة --loglevel . مستويات التسجيل المدعومة هي Loglevels PSR-3 ومستوى success :

• تصحيح
• معلومات
• يلاحظ
• النجاح (لم يتم تعريف هذا في PSR-3)
• تحذير
• خطأ
• شديد الأهمية
• يُحذًِر
• طارئ

تتوفر طرق الراحة لجميع مستويات السجل. يتوفر الاستيفاء النائب كما هو موضح في PSR-3 أيضًا. تتم طباعة الرسائل من مستوى warning فصاعدًا إلى STDERR جميعها STDOUT .

يمكن تعيين مستوى السجل الافتراضي للبرنامج النصي الخاص بك عن طريق الكتابة فوق عضو $logdefault .

انظر example/logging.php للحصول على مثال.