Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide Versin: Kaltura MediaSpace 5
Kaltura Business Headquarters 5 Unin Square West, Suite 602, New Yrk, NY, 10003, USA Tel.: +1 800 871 5224 Cpyright 2013 Kaltura Inc. All Rights Reserved. Designated trademarks and brands are the prperty f their respective wners. Use f this dcument cnstitutes acceptance f the Kaltura Terms f Use and Privacy Plicy.
Cntents Sectin 1 Understanding Kaltura MediaSpace Mdules... 4 KMS Architecture Cre and Mdules... 4 Cre Architecture... 4 Kaltura MediaSpace Mdules... 4 Sectin 2 Kaltura MediaSpace Applicatin Wrkflw... 5 Hw Are Mdules Initiated?... 5 Why Use Class Interfaces?... 6 Sectin 3 Mdule Develpment Guidelines... 7 KMS Mdule Cding Standards... 7 KMS Mdule Naming Cnventin... 7 General D's and Dn'ts... 7 Security Cnsideratins... 8 General Security Guidelines... 8 Specific Security Guidelines... 9 Expected Dcumentatin... 9 Mdule Descriptin... 9 Cde Cmments... 9 Release Ntes... 9 Setup Guide r Manual... 10 Certificatin... 10 Submitting a Mdule fr Certificatin... 10 FAQ... 10 Wh will be perfrming the mdule certificatin prcess?... 10 What des the certificatin prcess include?... 10 What d I d if my mdule failed the certificatin prcess?... 11 Hw d I release new versins r apply bug patches t my KMS mdule?... 11 What may cause my mdule certificatin t fail?... 11 Sectin 4 UI Cnsideratins... 12 Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 3
Understanding Kaltura MediaSpace Mdules SECTION 1 Kaltura MediaSpace (als referred t as KMS) enables cmmunity, cllabratin and scial activities by leveraging the pwer f nline vide by using an ut-f-the-bx vide prtal. KMS is a Kaltura API based applicatin. KMS uses its assciated Kaltura Accunt t stre cntent, metadata and user infrmatin and des nt have a lcal database f its wn. KMS is a highly custmizable applicatin. Administratrs can cnfigure and manage the applicatin thrugh an administratin interface and develpers can extend its functinality and add new features thrugh its mdular architecture f Mdel View Cntrller (MVC) based mdules. KMS Architecture Cre and Mdules This sectin describes the fllwing: Cre Architecture Mdules Cre Architecture KMS is implemented as a Zend-Framewrk applicatin and as such, the main architectural feature t cnsider is the Mdel-View-Cntrller (MVC) based mdules. Kaltura MediaSpace s cre is divided int tw main parts: Applicatin MVC the cre set f mdels, views and cntrllers. The main features f KMS, which are cnsidered cre, are implemented in this part f the system. KMS library a set f classes that the applicatin uses t manage different flws and resurces. The KMS library als implements the generic infrastructure that allws extending MediaSpace via mdules and themes. NOTE: Custm themes are nt cvered in this dcument. Kaltura MediaSpace Mdules Kaltura MediaSpace mdules are cde bundles that are deplyed in a KMS installatin. KMS mdules are used t add new capabilities and features t the cre functinality f KMS, and even affect r change the way KMS was designed t behave. T keep the system s behavir chesive, unified and supprted, mdules are als expected t use the MVC pattern and be implemented accrding t the guidelines described in this dcument. Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 4
SECTION 2 Kaltura MediaSpace Applicatin Wrkflw The fllwing diagram describes the applicatin flw f KMS. Mst f the flw actually represents prcesses that are managed by the Zend Framewrk (such as btstrap and dispatch). The interesting and imprtant part f the diagram is the bttm swim lane cntrlled by the KMS Library. These are the main entry pints where KMS interacts with mdules. Hw Are Mdules Initiated? During different phases KMS reaches ut t all enabled mdules, thrugh different predefined class interfaces, t allw mdules t participate in the applicatin flws. Fr example, during the initializatin f the Access Plugin, KMS lads all the mdules that implement an interface called Kms_Interface_Access and calls the getaccessrules() methd that these Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 5
Kaltura MediaSpace Applicatin Wrkflw mdules are bliged t implement. Any KMS mdule wuld implement the list f interfaces, which define the entry pints that the mdule wuld like t be called upn. Why Use Class Interfaces? The primary reasn fr chsing t use class interfaces t implement the KMS mdularity is t be able t maintain backwards cmpatibility. Interfaces shuld nt change between KMS versins, unless abslutely necessary. During develpment we cautiusly cnsider any changes befre applying a change t an existing interface. The secndary reasn fr chsing t use class interfaces t implement the KMS mdularity is t be able t easily determine which mdule shuld be called fr what entry pint. Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 6
SECTION 3 Mdule Develpment Guidelines Except fr mdules implemented fr private use, there are three distributin channels fr custm KMS mdules: Bundled within the Kaltura MediaSpace dwnlad package (as a default mdule, fr selfhsted KMS installatins) Deplyed n Kaltura s MediaSpace SaaS Envirnment Dwnladable via Kaltura Exchange t be used in self-hsted KMS installatins Yu are encuraged t cnsider the recmmendatins in this sectin fr all distributin channels, including mdules implemented fr private use nly. The gal f these recmmendatins is t ensure high quality sftware t be develped and distributed as a KMS mdule. KMS Mdule Cding Standards KMS fllws Zend Framewrk cding standards Kaltura MediaSpace mdules are required t fllw these standards as well. KMS Mdule Naming Cnventin It is recmmended t prefix the mdule name with the cmpany r service name t avid cnflicts with ther mdules. Refrain frm using the custmer name as a mdule name. Currently, KMS expects the mdule flder name t be all lwercase, and based n Zend Framewrk naming cnventins, class names f the mdule shuld start with a capital letter. Fr example, if yur mdule s name is example, yur mdel class name wuld be Example_Mdel_Example. General D's and Dn'ts Stick t what KMS allws yu t d. Implement the available interfaces (under library/kms/interfaces/). Use the asset-delivery actin fr prviding yur mdules JS/CSS/image (r ther static) files. Remember t build yur URLs via the cdnurl ViewHelper. Avid implementing yur mdule thrugh hacks based n Zend Framewrk behavir and capabilities. NOTE: Keeping these recmmendatins will ensure maximum frward cmpatibility f yur mdule, thus lwering the chances f significant update wrk when upgrading yur mdule t future versins f KMS. Yur mdule shuld NEVER mdify KMS cre r rely n hacks r patches applied t cre files f KMS. Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 7
Mdule Develpment Guidelines NOTE: Failing t cmply with these recmmendatins r mdifying cre cde makes the KMS upgrade prcess mre difficult and cmplex. Write safe cde s errrs r miscnfiguratins in yur mdule will nt crash the entire applicatin. NOTE: Keeping this recmmendatin ensures that even if yur mdule is malfunctining it des nt stp the applicatin frm wrking, thus allwing mre flexibility in supprt. Mdules shuld nt mdify r verride KMC cre/default CSS rules r JavaScript cde. NOTE: Keeping this recmmendatin shuld assist keeping highest frward cmpatibility. It is OK fr yur mdule t prvide CSS fr its wn element, hwever yu are recmmended t use available CSS definitins frm Twitter Btstrap (utilized by KMS). It is OK fr yur mdule t prvide JS fr its wn functinality. Keep yur cde rganized crrectly, accrding t an MVC pattern. Implement lgic and any API (fr example, Kaltura API) calls in the mdel. Call mdel methds frm cntrller-actin and prepare view data. Keep nly simple lp and if lgic in view while rendering HTML. Implement ViewHelper if mre cmplicated (r repeatable) lgic is required within a view. Use KMS cache infrastructure when pssible and relevant. D nt leave calls t Kms_Lg::trace() in yur final cde. Chse smartly when t use available public methds frm existing mdels (fr implementing API calls t Kaltura) r implement yur wn cde fr making API calls. When using existing KMS mdels yu shuld usually get a mdel s instance thrugh Kms_Resurce_Mdels::get{MdelName}(). Fr example: $entrymdel = Kms_Resurce_Mdels::getEntry(); NOTE: Refrain frm instantiating mdel bjects like: $entrymdel = new Applicatin_Mdel_Entry(); If yu d chse t instantiate mdel bjects, be extra careful as ding s can have glbal implicatins n KMS behavir. If yur mdule depends n anther mdule, remember t implement the Kms_Interface_Mdel_Dependency interface. Always set enabled=0 in yur mdule s default.ini file. 3 rd party mdules shuld always be disabled by default. Security Cnsideratins Avid perfrming any actins that yu wuld nt d if yu were t hst the cde n yur wn server. General Security Guidelines Make sure yur cde is safe against OWASP Tp 10 vulnerabilities. Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 8
Mdule Develpment Guidelines Avid implementing file uplads directly t KMS servers. Use Kaltura s API and widgets t uplad cntent t Kaltura. D nt use PHP s eval() functin t run user-input-based cde. Never utput sensitive infrmatin t the brwser (fr example, in case f errrs). Avid using ini_set in yur mdule s cde. D nt use execute shell cmmands (fr example, functins such as: exec, system, r passthru). Specific Security Guidelines If yu implement a frm f yur wn t update data, prtect against CSRF by having yur frm class extend the Applicatin_Frm_Base that handles CSRF prtectin fr yu. If yu perfrm any redirects in yur actins, make sure yu nly allw internal redirects r redirects t URLs that are valid and accepted. In ther wrds sanitize user-input URLs befre redirecting t such. If yur mdule writes ckie with sensitive data, set the httponly flag n yur ckie s it cannt be read by malicius client-side cde. Sanitize any user input t prtect against XSS. Expected Dcumentatin The fllwing dcumentatin is expected fr KMS Mdules. Mdule Descriptin Cde Cmments Release Ntes Setup Guide r Manual Mdule Descriptin KMS mdules are expected t include a file called mdule.inf at the rt f the mdule flder. The mdule.inf file is expected t be in INI frmat. Yu are expected t prvide this file with yur mdule s it will be clear t the KMS Administratrs and ther develpers what yur mdule des. Please use the descriptin prperty in this file and prvide a shrt descriptin f the mdule added functinality. Cde Cmments Prvide meaningful cde cmments in yur mdule, specifically blck-cmments fr classes and methds, s whever des the cde review fr certificatin purpses will be able t easily understand what each and every piece f cde is respnsible fr. Release Ntes Yu are expected t publish release ntes with every versin release f yur mdule, listing any new r mdified features, knwn and reslved issues and imprtant ntes r cnfiguratins if there are such. The release ntes shuld als include cntact infrmatin fr yur sales and supprt, including phne Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 9
Mdule Develpment Guidelines and email. Remember that althugh yur mdule may be bundled with KMS yu are still the wner f the cde fr supprt purpses. The release ntes file will be named CHANGELOG.txt and placed n the rt in yur mdule directry, the frmatting f the file shuld adhere t the Markdwn syntax guidelines. If yu hst a public versin f the release ntes n yur server, custmers will appreciate having a link t a public release ntes in the descriptin field within the mdule.inf file (which will shw in the mdule admin panel). Setup Guide r Manual If enabling yur mdule als requires special cnfiguratins r registratin t 3 rd party services, please prvide a mdule setup guide (r mdule user manual) fr users t be able t setup, manage and use yur mdule. A link t the guide shuld be placed in the descriptin within mdule.inf file. Certificatin Fr all distributin channels, a mdule must g thrugh certificatin prcess and be certified befre made available and recmmended t Kaltura MediaSpace custmers. Submitting a Mdule fr Certificatin Mdules and all fllwing versins f the mdule (n matter hw small f a change) are required t g thrugh the Kaltura cde review certificatin befre being deplyed n Kaltura s SaaS, and/r recmmended fr Kaltura custmers use. When yur mdule is ready fr certificatin, send yur mdule t yur Kaltura pint f cntact and ask fr the mdule t g thrugh the certificatin prcess. T prperly track versins, bug fixes and new additins, and significantly shrten certificatin times we require that each mdule (and new versins f it) submitted fr review, will be n a GitHub.cm repsitry that can be accessed by the Kaltura engineers wh will perfrm the certificatin cde review. FAQ Wh will be perfrming the mdule certificatin prcess? An fficial develper f the Kaltura MediaSpace Engineering team will perfrm the certificatin prcess. What des the certificatin prcess include? The certificatin prcess includes the fllwing: 1. Cde review fr cmpatibility with develper guidelines mentined in this dcument, security review f the cde submitted, and that the mdule perfrms what was stated in its release ntes. 2. Sanity admin and user interfaces and wrkflws QA. 3. Validatin f all dcumentatin required including setup manual, and release ntes file. Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 10
Mdule Develpment Guidelines NOTE: Cde review may als include the use f autmatic cde-analysis tls if Kaltura finds the need fr it. What d I d if my mdule failed the certificatin prcess? Fix the issues reprted by Kaltura and resubmit the mdule fr certificatin. Hw d I release new versins r apply bug patches t my KMS mdule? Regardless f the significance f changes applied t the new versin, it is required that every mdule versin submitted fr deplyment will underg prper certificatin by the Kaltura MediaSpace Engineering team. T make sure that yur certificatin is cmpleted quickly, please make prper use f a GitHub.cm repsitry when develping yur mdule, which allws the cde reviewer t track the changes at the cde level. What may cause my mdule certificatin t fail? The fllwing may cause the certificatin f a mdule t fail (nt rdered by significance): Critical r majr bugs fund during certificatin. Expsing f sensitive infrmatin t user r sending such infrmatin t external systems. Examples fr sensitive infrmatin: Kaltura accunt infrmatin, Kaltura admin secret, and infrmatin abut the webserver. Inability t perfrm QA due t missing dcumentatin. Vilatin f any item frm the Specific Security Guidelines sectin. Vilatin f any item frm the General Security Guidelines sectin, under the discretin f the reviewer. Mdificatin f KMS cre cde fr the mdule t be perable. Expliting Zend Framewrk behavir/capabilities instead f (r in additin t) using dedicated KMS interfaces under the discretin f the reviewer. Trace lgs left in the cde. Nt implementing the dependency interface while using anther mdule s cde r decisins. Any attempt t bscure what yur mdule r parts f its cde are ding. Fr example, if yu want t use a minified JS it is OK but yu must include a nn-minified versin f the JS cde in the mdule as well. Lading static assets nt via cdnurl ViewHelper. Missing Release Ntes n yur CHANGELOG.txt file. Missing critical setup r cnfiguratin ntes required fr successfully enabling yur mdule. Breaking standard user interfaces in MediaSpace. A mdule s certificatin may fail fr additinal reasns nt listed abve. Fr all cases f certificatin failure, the mdule develpers will be ntified abut the reasns fr failure and guidelines t reslve the issues fund. Yu will be given the pprtunity t resubmit the mdule fr certificatin after yu fix/reslve the issues in the mdule. Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 11
SECTION 4 UI Cnsideratins The purpse f yur custm mdule is t prvide an integrated experience that is part f Kaltura MediaSpace and enables additinal functinality while fllwing existing user experience and user flws. If yur custm mdule intrduces a user interface that is vastly different frm Kaltura MediaSpace, yu may be frcing the user t learn a cmpletely new interface which may be difficult fr them t embrace. Be certain that the user interface elements are cnsistent with the Kaltura MediaSpace interface and HTML tags t supprt the CSS file, s yur user interface des nt "stand ut". Kaltura MediaSpace Mdule Develpment Guidelines and Best Practices Develper Guide 12