ext direct

تحويلة مباشرة

مكون أساسي لدمج Sencha Ext JS Ext.direct في تطبيق PHP

مقدمة

توفر هذه المكتبة تطبيقًا من جانب الخادم لـ Sencha Ext.direct، وهو مكون اتصال بنمط RPC يعد جزءًا من Sencha's Ext JS و Sencha Touch .

ext direct عبارة عن بروتوكول استدعاء الإجراء عن بعد (RPC) الذي لا يعرف النظام الأساسي واللغة. يسمح ext direct بالاتصال السلس بين جانب العميل لتطبيق Ext JS وأي نظام أساسي للخادم يتوافق مع المواصفات. يعد ext direct عديم الحالة وخفيف الوزن، ويدعم ميزات مثل اكتشاف واجهة برمجة التطبيقات (API)، وتجميع المكالمات، وأحداث الخادم إلى العميل.

حاليًا، يتم استخدام هذه المكتبة فقط كأساس لـ teqneers/ext-direct-bundle، وهي حزمة Symfony التي تدمج * Ext.direct* في تطبيق يعتمد على Symfony. لم نحاول استخدام المكتبة كمكون مستقل أو في أي سياق آخر غير بيئة Symfony، لذا فإن ما يلي هو فقط كيفية العمل نظريًا بدون الحزمة. نحن نقدر أي مساعدة ومساهمة لجعل المكتبة أكثر فائدة خارج الحزمة.

تثبيت

يمكنك تثبيت هذه المكتبة باستخدام الملحن

 composer require teqneers/ext-direct

أو قم بإضافة الحزمة إلى ملف Composer.json مباشرة.

مثال

تحدد استراتيجية التسمية كيفية ترجمة أسماء فئات PHP ومساحات الأسماء إلى أسماء إجراءات Ext.direct متوافقة مع Javascript. تقوم استراتيجية التسمية الافتراضية بترجمة الفاصل namspapce إلى ملف . . لذلك تتم ترجمة MyNamespaceService إلى My.namespace.Service . يرجى ملاحظة أن التحويل يجب أن يكون قابلاً للعكس ( My.namespace.Service => MyNamespaceService ).

 $ namingStrategy = new TQ  ExtDirect  Service  DefaultNamingStrategy ();

يستخدم سجل الخدمة مصنع بيانات التعريف من مكتبة jms/metadata وبرنامج تشغيل التعليقات التوضيحية المرتبط به (والذي يستخدم بدوره قارئ التعليقات التوضيحية doctrine/annotations ) لقراءة معلومات التعريف حول فئات الخدمة المشروحة المحتملة.

 $ serviceRegistry = new TQ  ExtDirect  Service  DefaultServiceRegistry (
    new Metadata  MetadataFactory (
        new TQ  ExtDirect  Metadata  Driver  AnnotationDriver (
            new Doctrine  Common  Annotations  AnnotationReader ()
        )
    ),
    $ namingStrategy
);

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

يعد مرسل الحدث اختياريًا ولكنه مطلوب لاستخدام ميزات مثل تحويل الوسيطة والتحقق من الصحة، وتحويل النتائج لمستمع التوصيف.

 $ eventDispatcher = new Symfony  Component  EventDispatcher  EventDispatcher ();

يتم استخدام جهاز التوجيه لترجمة طلبات Ext.direct الواردة إلى استدعاءات أسلوب PHP لفئة الخدمة الصحيحة. يدعم ContainerServiceFactory استرداد الخدمات من حاوية حقن تبعيات Symfony أو إنشاء مثيل للخدمات البسيطة التي لا تأخذ أي وسيطات منشئة على الإطلاق. تتجاوز مكالمات الخدمة الثابتة مصنع الخدمة.

 $ router = new TQ  ExtDirect  Router  Router (
    new TQ  ExtDirect  Router  ServiceResolver (
        $ serviceRegistry ,
        new TQ  ExtDirect  Service  ContainerServiceFactory (
            /* a SymfonyComponentDependencyInjectionContainerInterface */
        )
    ),
    $ eventDispatcher
);

كائن نقطة النهاية هو واجهة أمام كافة المكونات من جانب الخادم Ext.direct . باستخدام أسلوب createServiceDescription() يمكن للمرء الحصول على وصف API متوافق مع المعايير بينما يأخذ handleRequest() SymfonyComponentHttpFoundationRequest ويعيد SymfonyComponentHttpFoundationResponse الذي يحتوي على استجابة Ext.direct لاستدعاءات الخدمة تلقى.

 $ endpoint = TQ  ExtDirect  Service Endpoint (
    ' default ' , // endpoint id
    new TQ  ExtDirect  Description  ServiceDescriptionFactory (
        $ serviceRegistry ,
        ' My.api ' ,
        $ router ,
        new TQ  ExtDirect  Router  RequestFactory (),
        ' My.api.REMOTING_API '
    )
);

يعد مدير نقطة النهاية مجرد مجموعة بسيطة من نقاط النهاية التي تسمح بالاسترداد باستخدام معرف نقطة النهاية. وهذا يسمح بالتعرض السهل لواجهات برمجة التطبيقات المستقلة المتعددة.

 $ manager = new TQ  ExtDirect  Service  EndpointManager ();
$ manager -> addEndpoint ( $ endpoint );
$ defaultEndpoint = $ manager -> getEndpoint ( ' default ' );

$ apiResponse = $ defaultEndpoint -> createServiceDescription ( ' /path/to/router ' );
$ apiResponse -> send ();

$ request = Symfony  Component  HttpFoundation Request:: createFromGlobals ();
$ response = $ defaultEndpoint -> handleRequest ( $ request );
$ response -> send ();

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

• تحويل الوسائط قبل استدعاء طريقة الخدمة
• التحقق من صحة الوسائط قبل استدعاء طريقة الخدمة
• تحويل نتيجة استدعاء طريقة الخدمة قبل إعادتها إلى العميل
• تجهيز جهاز التوجيه للحصول على معلومات التوقيت (يستخدم لزيادة المخطط الزمني لملف تعريف Symfony)

تستخدم محولات الوسيطة والنتائج المشحونة مكتبة jms/serializer لتوفير إمكانات تسلسل (إلغاء) موسعة، بينما يستخدم مدقق الوسيطة الافتراضي مكتبة symfony/validator .

 $ eventDispatcher -> addSubscriber (
    new TQ  ExtDirect  Router  EventListener  ArgumentConversionListener (
        new TQ  ExtDirect  Router  ArgumentConverter ( /* a JMSSerializerSerializer */ )
    )
);
$ eventDispatcher -> addSubscriber (
    new TQ  ExtDirect  Router  EventListener  ArgumentValidationListener (
        new TQ  ExtDirect  Router  ArgumentValidator ( /* a SymfonyComponentValidatorValidatorValidatorInterface */ )
    )
);
$ eventDispatcher -> addSubscriber (
    new TQ  ExtDirect  Router  EventListener  ResultConversionListener (
        new TQ  ExtDirect  Router  ResultConverter ( /* a JMSSerializerSerializer */ )
    )
);
$ eventDispatcher -> addSubscriber (
    new TQ  ExtDirect  Router  EventListener  StopwatchListener (
        /* a SymfonyComponentStopwatchStopwatch */
    )
);

شروح الخدمة

يجب أن تكون الخدمات التي سيتم عرضها عبر Ext.direct API مزينة بالمعلومات التعريفية المناسبة. هذا ممكن حاليًا فقط باستخدام التعليقات التوضيحية (مثل تلك المعروفة من Doctrine أو Symfony أو مكتبات PHP الحديثة الأخرى).

يجب أن يتم التعليق على كل فئة خدمة سيتم عرضها كإجراء Ext.direct باستخدام TQExtDirectAnnotationAction . يأخذ التعليق Action بشكل اختياري معلمة معرف الخدمة للخدمات التي ليست ثابتة ولا يمكن إنشاء مثيل لها باستخدام مُنشئ بدون معلمات.

 use TQ  ExtDirect  Annotation as Direct ;

/**
 * @DirectAction()
 */
class Service1
{
    // service will be instantiated using the parameter-less constructor if called method is not static
}

/**
 * @DirectAction("app.direct.service2")
 */
class Service2
{
    // service will be retrieved from the dependency injection container using id "app.direct.service2" if called method is not static
}

بالإضافة إلى ذلك، يجب إضافة تعليق توضيحي لكل طريقة سيتم عرضها في إجراء Ext.direct باستخدام TQExtDirectAnnotationMethod . يأخذ التعليق التوضيحي Method false اختياري إما true لتعيين الطريقة كطريقة Ext.direct عادية (هذا هو الإعداد الافتراضي).

 /**
 * @DirectAction("app.direct.service3")
 */
class Service3
{
    /**
     * @DirectMethod()
     */
    public function methodA ()
    {
        // regular method
    }

    /**
     * @DirectMethod(true)
     */
    public function methodB ()
    {
        // form handler method
    }
}

الميزات الموسعة مثل المعلمات المسماة والمعلمات المسماة الصارمة الموضحة في مواصفات Ext.direct لا يتم عرضها حاليًا من خلال نظام التعليقات التوضيحية.

يمكن أيضًا إضافة تعليقات توضيحية إلى المعلمات التي تدخل في الطريقة التي يتم استدعاؤها عبر طلب Ext.direct لتطبيق التحقق من صحة المعلمة. يتطلب ذلك تسجيل TQExtDirectRouterEventListenerArgumentValidationListener مع مرسل الحدث المناسب.

 use Symfony  Component  Validator  Constraints as Assert ;

/**
 * @DirectAction("app.direct.service4")
 */
class Service4
{
    /**
     * @DirectMethod()
     * @DirectParameter("a", { @AssertNotNull(), @AssertType("int") })
     *
     * @param int $a
     */
    public function methodA ( $ a )
    {
    }
}

إذا كان توقيع الطريقة التي يتم استدعاؤها يكشف عن المعلمة (المعلمات) مع تلميح نوع لـ SymfonyComponentHttpFoundationRequest و/أو TQExtDirectRouterRequest ، فإن طلب Symfony HTTP الوارد و/أو Ext.direct الأولي يتم إدخال الطلب في استدعاء الأسلوب تلقائيًا. يعد هذا مهمًا بشكل خاص لطرق التعامل مع نماذج النماذج لأنه لا توجد طريقة أخرى للوصول إلى معلمات طلب HTTP الواردة (منشور النموذج).

بمجرد تمكين TQExtDirectRouterEventListenerArgumentConversionListener ، يمكن للمرء استخدام معلمات الكائن المكتوبة بدقة في أساليب الخدمة. سيتم إلغاء تسلسل هذه الوسائط تلقائيًا من طلب JSON الوارد وسيتم إدخالها في استدعاء الأسلوب.

وينطبق الشيء نفسه على إرجاع الكائنات من استدعاء أسلوب الخدمة. إذا تم تمكين TQExtDirectRouterEventListenerResultConversionListener ، فسيتم إجراء تسلسل لقيم الإرجاع تلقائيًا إلى JSON حتى لو كانت كائنات غير تافهة.

تعتمد كل من الوسيطة وكذلك تحويل القيمة المرجعة على مكتبة jms/serializer الممتازة التي كتبها يوهانس شميت. راجع الوثائق لمزيد من المعلومات.

مواصفة

يمكن العثور على المواصفات ext direct على موقع وثائق Sencha.

رخصة

رخصة معهد ماساتشوستس للتكنولوجيا (MIT)

حقوق الطبع والنشر (ج) لعام 2015 مملوكة لشركة TEQneers GmbH & Co. KG

يُمنح الإذن مجانًا لأي شخص يحصل على نسخة من هذا البرنامج وملفات الوثائق المرتبطة به ("البرنامج")، للتعامل في البرنامج دون قيود، بما في ذلك، على سبيل المثال لا الحصر، حقوق الاستخدام والنسخ والتعديل والدمج. ونشر و/أو توزيع وترخيص من الباطن و/أو بيع نسخ من البرنامج، والسماح للأشخاص الذين تم توفير البرنامج لهم بالقيام بذلك، وفقًا للشروط التالية:

يجب تضمين إشعار حقوق الطبع والنشر أعلاه وإشعار الإذن هذا في جميع النسخ أو الأجزاء الكبيرة من البرنامج.

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