ridgraphcore

DevelopersGuideReferencefordevelopersandcommunitymembersMantisBTDevelopmentTeamDevelopersGuide:Referencefordevelopersandcommunitymem-bersbyMantisBTDevelopmentTeamAbstractThisbookistargetedatMantisBTdevelopers,contributorsandpluginauthors.
ItdocumentsthedevelopmentprocessandprovidesreferenceinformationregardingtheMantisBTcore,includingthedatabaseschemaaswellasthepluginsystemincludinganeventsreference.
Copyright2016MantisBTteam.
ThismaterialmayonlybedistributedsubjecttothetermsandconditionssetforthintheGNUFreeDocumen-tationLicense(GFDL),V1.
2orlater(thelatestversionispresentlyavailableathttp://www.
gnu.
org/licenses/fdl.
txt).
TableofContents1.
ContributingtoMantisBT1InitialSetup1CloningtheRepository1DeterminingtheCloneURL1InitializingtheClone2Addingremotes2Checkingoutbranches2MaintainingTrackingBranches3PreparingFeatureBranches4PrivateBranches4PublicBranches4RunningPHPUnittests5RunningtheSOAPtests5SubmittingChanges5Beforeyousubmit6SubmissionViaGithubPullRequests6SubmissionViaFormattedPatches7SubmissionViaPublicRepository72.
DatabaseSchemaManagement9TheMantisBTschema9SchemaDefinition9Installation/UpgradeProcess93.
EventSystem10GeneralConcepts10APIUsage10EventTypes114.
PluginSystem13GeneralConcepts13BuildingaPlugin13PluginStructure13Properties15PagesandFiles16Events18Configuration20LanguageandLocalization21Layout23ExamplePluginsourcecode24APIUsage245.
EventsReference25Introduction25SystemEvents25OutputModifierEvents27StringDisplay27MenuItems29PageLayout33BugFilterEvents34CustomFiltersandColumns34BugandBugnoteEvents35BugView35BugActions35BugnoteView39iiiDevelopersGuideBugnoteActions39NotificationEvents41RecipientSelection41UserAccountEvents42AccountPreferences42ManagementEvents43ProjectsandVersions436.
MantisBTRESTAPI47Postman47ExportingPostmanCollection477.
MantisBTSOAPAPI48Javaintegration48PrebuiltSOAPstubsusingAxis48UsageinOSGienvironments48Compatibilitybetweenreleases48Support488.
Appendix49GitReferences49A.
RevisionHistory50ivListofFigures2.
1.
MantisBTEntity-RelationshipDiagram9vChapter1.
ContributingtoMantisBTMantisBTsourcecodeismanagedwithGit[https://git-scm.
com/].
Ifyouarenewtothisversioncontrolsystem,youcanfindsomegoodresourcesforlearningandinstallingitinthesectioncalled"GitRefer-ences".
InitialSetupThereareafewstepstheMantisBTteamrequiresofcontributorsanddeveloperswhenacceptingcodesubmissions.
TheuserneedstoconfigureGittoknowtheirfullname(notascreenname)andanemailaddresstheycanbecontactedat(notathrowawayaddress).
TosetupyournameandemailaddresswithGit,runthefollowingcommands,substitutingyourownrealnameandemailaddress:gitconfig--globaluser.
name"JohnSmith"gitconfig--globaluser.
email"jsmith@mantisbt.
org"Optionally,youmaywanttoconfigureGittouseterminalcolorswhendisplayingfilediffsandotherinformation,andalsoaliascertainGitactionstoshorterphrasestoreducetyping:gitconfig--globalcolor.
diff"auto"gitconfig--globalcolor.
status"auto"gitconfig--globalcolor.
branch"auto"gitconfig--globalalias.
st"status"gitconfig--globalalias.
di"diff"gitconfig--globalalias.
co"checkout"gitconfig--globalalias.
ci"commit"CloningtheRepositoryTheofficialMantisBTsourcecoderepositoryishostedatGitHub[https://github.
com/mantisbt/mantisbt].
ThisdocumentassumesthatyouhavealreadysignedupforandsetupaGitHubaccount.
DeterminingtheCloneURLWhichURLyouwillusetoclonetherepositorybeforeyoustartdevelopingdependsonyoursituation.
MantisBTCoreTeamDevelopersMantisBTdevelopershavepushaccesstotheofficialrepository.
BenefitingfromthisaccessrequiresaspecialURLthatusesyourSSHkeytohandleaccesspermis-sions:git@github.
com:mantisbt/mantisbt.
git.
Al-ternatively,anHTTPSlinkcanbeusedaswell,inwhichcaseyouwillhavetoprovideyourGitHubUserIDandpasswordwhenGitrequestsit:https://github.
com/mantisbt/mantisbt.
git.
1ContributingtoMantisBTNotePusheswillfailifyoudonothaveaccessoryourpublicSSHkeyisnotsetupcorrectlyinyourGitHubprofile.
ContributorsForotherpeople,theMantisBTrepositoryandtherelatedcloneURLsgit@github.
com:mantisbt/mantisbt.
git(SSH).
orhttps://github.
com/mantisbt/mantisbt.
git(HTTPS)willalwaysberead-only.
Itisthereforestronglyadvisedtocreateyourownfork[https://github.
com/mantisbt/mantisbt/fork]ofMantis-BTwhereyouwillbeabletopushyourchanges,andthenusethefork'sURLinsteadtoclone,whichwilllooklikethis:git@github.
com:MyGithubId/mantisbt.
git.
orhttps://github.
com/MyGithubId/mantisbt.
gitInitializingtheCloneToclonetherepository,executethefollowingcommandfromyourtargetworkspace:gitcloneYourCloneURLAfterperformingthecloningoperation,youshouldendupwithanewdirectoryinyourworkspace,man-tisbt/,containingtheMantisBTrepositorywitharemotenamedoriginpointingtoyourCloneURL.
MantisBTusesComposer[https://getcomposer.
org]topulllibrariesandcomponentsfromPackagist[https://packagist.
org]andGithub[https://github.
com].
InstallComposer[https://getcomposer.
org/down-load/]andrunthefollowingcommand:composerinstallWarningFailuretoexecutethesubmoduleinitializationcommandswillresultincriticalcomponentsbeingmissingfrom/vendorfolder,whichwillthencauseerrorswhenrunningMantisBT.
AddingremotesIfyouareplanningtouseyourownforktopushandmaintainyourchanges,thenwerecommendsettingupanupstreamremoteforMantisBT'sofficialrepository,whichwillmakeiteasiertokeepyourrepositoryup-to-date.
gitremoteadd--tagsupstreamgit://github.
com/mantisbt/mantisbt.
gitCheckingoutbranchesBydefault,thenewclonewillonlytrackcodefromtheprimaryremotebranch,master,whichisthelatestdevelopmentversionofMantisBT.
Ifyouareplanningtoworkwithstablereleaseorotherdevelopmentbranches,youwillneedtosetuplocaltrackingbranchesinyourrepository.
2ContributingtoMantisBTThefollowingcommandwillsetupatrackingbranchforthecurrentstablebranch,master-1.
3.
x.
gitcheckout-bmaster-1.
3.
xorigin/master-1.
3.
xNoteWiththeintroductionofsubmodulesforsomeofthethird-partylibraries,youmayencounterissueswhenswitchingtoanolderbranchwhichstillhascodefromthoselibrariesinasubdirectoryof/libraryratherthanasubmodule:$gitcheckoutold_brancherror:Thefollowinguntrackedworkingtreefileswouldbeoverwrittenbychecko(listoffiles)AbortingToresolvethis,youfirsthavetogetridofthesubmodulesdirectoriesbeforeyoucancheckoutthebranch.
Thecommandbelowwillmoveallsubmodulesto/tmp:sed-rn"s/^.
*path\s*=\s*(.
*)$/\1/p".
gitmodules|xargs-I{}mv-v{}/tmpgitcheckoutold_branchAlernatively,ifyoudon'tcareaboutkeepingthechangesinthesubmodulesdirectories,youcansimplyexecutegitcheckout-fold_branchgitclean-dfWhenswitchingbackfromtheolderbranch,thesubmodulesdirectorieswillbeempty.
AtthatpointyoucaneitherUpdatethesubmodulestoreclonethemgitsubmoduleupdateRestorethedirectoriespreviouslymovedto/tmpbackintotheemptydirectories,e.
g.
sed-rn"s/^.
*path\s*=\s*(.
*)$/\1/p".
gitmodules|xargs-n1basename|xargs-Forfurtherreference:ProGitbook[https://git-scm.
com/book/en/Git-Tools-Submodules#Is-sues-with-Submodules]MaintainingTrackingBranchesInordertokeepyourlocalrepositoryup-to-datewiththeofficialone,thereareafewsimplecommandsneededforanytrackingbranchesthatyoumayhave,includingmasterandmaster-1.
3.
x.
First,you'llneedtogetthelatestinformationfromtheremoterepository:gitfetchorigin3ContributingtoMantisBTNoteIfyouclonedfromyourpersonalGitHubforkinsteadoftheofficialMantisBTrepositoryasexplainedinthesectioncalled"Addingremotes",thenyoushouldinsteadexecute:gitfetchupstreamThenforeachtrackingbranchyouhave,enterthefollowingcommands:gitcheckoutBranchNamegitrebaseAlternatively,youmaycombinethefetchandrebaseoperationsdescribedaboveintoasinglepullcom-mand(foreachremotetrackingbranch):gitcheckoutmastergitpull--rebasePreparingFeatureBranchesForeachlocalorsharedfeaturebranchthatyouareworkingon,youwillneedtokeepituptodatewiththeappropriatemasterbranch.
Therearemultiplemethodsfordoingthis,eachbettersuitedtoadifferenttypeoffeaturebranch.
Bothmethodsassumethatyouhavealreadyperformedthepreviousstep,toupdateyourlocaltrackingbranches(seethesectioncalled"MaintainingTrackingBranches").
PrivateBranchesIfthetopicbranchinquestionisalocal,privatebranch,thatyouarenotsharingwithotherdevelopers,thesimplestandeasiestmethodtostayuptodatewithmasteristousetherebasecommand.
Thiswillappendallofyourfeaturebranchcommitsintoalinearhistoryafterthelastcommitonthemasterbranch.
gitrebasemasterfeatureNoteRebasingchangestheIDforeachcommitinyourfeaturebranch,whichwillcausetroubleforanyonesharingand/orfollowingyourbranch.
Theresultingconflictcanbefixedbyrebasingtheircopyofyourbranchontoyourbranch:gitcheckoutfeaturegitfetchremote/featuregitrebaseremote/featurePublicBranchesForanypublicly-sharedbranches,whereotherusersmaybewatchingyourfeaturebranches,orcloningthemlocallyfordevelopmentwork,you'llneedtotakeadifferentapproachtokeepingituptodatewithmaster.
4ContributingtoMantisBTTobringpublicbranchuptodate,you'llneedtomergethecurrentmasterbranch,whichwillcreateaspecial"mergecommit"inthebranchhistory,causingalogical"split"incommithistorywhereyourbranchstartedandjoiningatthemerge.
Thesemergecommitsaregenerallydisliked,becausetheycancrowdcommithistory,andbecausethehistoryisnolongerlinear.
Theywillbedealtwithduringthesubmissionprocess(seethesectioncalled"RunningPHPUnittests").
gitcheckoutfeaturegitmergemasterAtthispoint,youcanpushthebranchtoyourpublicrepository,andanyonefollowingthebranchcanthenpullthechangesdirectlyintotheirlocalbranch,eitherwithanothermerge,orwitharebase,asnecessitatedbythepublicorprivatestatusoftheirownchanges.
RunningPHPUnittestsMantisBThasasuiteofPHPUnittestsfoundinthetestsdirectory.
Youareencouragedtoaddyourowntestsforthepatchesyouaresubmitting,butpleaserememberthatyourchangesmustnotbreakexistingtests.
Inordertorunthetests,youwillneedtohavethePHPSoapextension,PHPUnit3.
4ornewer[http://www.
phpunit.
de]andPhing2.
4ornewer[http://phing.
info]installed.
Thetestsareconfiguredusingabootstrap.
phpfile.
Theboostrap.
php.
samplefilecontainsthesettingsyouwillneedtoadjusttorunallthetests.
Runningtheunittestsisdonefromrootdirectoryusingthefollowingcommand:phingtestRunningtheSOAPtestsMantisBTshipswithasuiteofSOAPtestswhichrequireaninitialsetuptobeexecuted.
Therequiredstepsare:InstallMantisBTlocallyandconfigureaprojectandacategory.
Adjustthebootstrap.
phpfiletopointtoyourlocalinstallation.
Customizetheconfig_inc.
phptoenableallthefeaturestestedusingtheSOAPtests.
Thesimplestwaytodothatistorunallthetestsonceandadjustitbasedontheskippedtests.
SubmittingChangesThissectiondescribeswhatyoushoulddotosubmitasetofchangestoMantisBT,allowingtheprojectdeveloperstoreviewandtest,yourcode,andultimatelycommitittotheMantisBTrepository.
Theactualsubmissioncanbedoneusingseveralmethods,describedlaterinthissection:Recommended:GithubPullRequests(seethesectioncalled"SubmissionViaGithubPullRequests")OtherpublicGitrepositoryPullRequests(seethesectioncalled"SubmissionViaPublicRepository")GitFormattedpatches(seethesectioncalled"SubmissionViaFormattedPatches")5ContributingtoMantisBTBeforeyousubmitBeforesubmittingyourcontribution,youshouldmakesurethat1.
YourcodefollowstheMantisBTcodingguidelines[https://mantisbt.
org/wiki/doku.
php/mantisbt:cod-ing_guidelines]2.
Youhavetestedyourchangeslocally(seethesectioncalled"RunningPHPUnittests")3.
YourlocalbranchhasbeenrebasedontopofthecurrentMasterbranch,asdescribedinthesectioncalled"PrivateBranches".
SubmissionViaGithubPullRequestsSincetheofficialMantisBTrepository[https://github.
com/mantisbt/mantisbt]ishostedthere,usingGitHub[https://github.
com]istherecommended(andeasiest)waytosubmityourcontributions.
Withthismethod,youcankeepyourchangesetsup-to-datewiththeofficialdevelopmentrepository,andlikewiseletanyonestayuptodatewithyourrepository,withoutneedingtoconstantlyuploadanddown-loadnewformattedpatcheswheneveryouchangeanything.
TheprocessbelowdescribesasimpleworkflowthatcanhelpyoumakeyoursubmissionifyouarenotfamiliarwithGit;notethatitisbynomeanstheonlywaytodothis.
NoteWe'llassumethatyouhavealreadyforkedMantisBT[https://github.
com/mantisbt/mantis-bt/fork],cloneditlocallyasdescribedinthesectioncalled"CloningtheRepository"(remoteupstreambeingtheofficialMantisBTrepositoryandoriginyourpersonalfork),andcreatedanewfeaturebranch(seethesectioncalled"PreparingFeatureBranches")foryourcontribution,whichwe'llcallMyBranch.
1.
MakesurethattheMyBranchfeaturebranchisup-to-datewiththemasterbranchbyrebasingit,re-solvinganyconflictsifnecessary.
gitfetchupstreamgitrebaseupstream/masterMyBranch2.
PushthebranchtoyourGithubforkgitpushoriginMyBranch3.
GotoyourForkonGithub(https://github.
com/MyGithubId/mantisbt)4.
InitiateaPullRequest[https://github.
com/MyGithubId/mantisbt/compare/MyBranch]fromyourfea-turebranch,followingtheguidelinesprovidedinGithubHelp[https://help.
github.
com/articles/us-ing-pull-requests].
Pleasemakesureyouprovideadetaileddescriptionofthechangesyouaresubmitting,includingthereasonforitandifpossibleareference(link)toanexistingissueonourbugtracker[https://mantis-bt.
org/bugs/].
Theteamwillusuallyreviewyourchangesandprovidefeedbackwithin7days(butyourmileagemayvary).
6ContributingtoMantisBTSubmissionViaFormattedPatchesFormattedpatchesareverysimilartofilediffsgeneratedbyothertoolsorsourcecontrolsystems,butcontainfarmoreinformation,includingyournameandemailaddress,andforeverycommitintheset,thecommit'stimestamp,message,author,andmore.
TheyallowanyonetoimporttheenclosedchangesetsdirectlyintoGit,whereallofthecommitinformationispreserved.
Assumingthatyouhaveanexistinglocalthatyou'vekeptuptodatewithmasterasdescribedinthesectioncalled"PreparingFeatureBranches"currentlycheckedout,generatingaformattedpatchsetshouldberelativelystraightforward,usinganappropriatefilenameasthetargetofthepatchset:gitformat-patch--binary--stdoutorigin/master.
.
HEAD>feature_branch.
patchOnceyou'vegeneratedtheformattedpatchfile,youcaneasilyattachittoabugreport,orevenusethepatchfileasanemailtosendtothedevelopermailinglist.
Developers,orotherusers,canthenimportthispatchsetintotheirlocalrepositoriesusingthefollowingcommand,againsubstitutingtheappropriatefilename:gitam--signofffeature_branch.
patchSubmissionViaPublicRepositoryIfyouarenotableornotwillingtomakeuseofaforkoftheofficialGitHub[https://github.
com]repositorybuthaveanotherpubliclyavailableonetohostyourchanges,forexampleonafreehostingforpublicrepositorysuchasBitbucket[https://bitbucket.
org]GitLab[https://gitlab.
com]youcanstilluseittosubmitapatchinasimilarfashiontotheGithubmethoddescribedabove,althoughtheprocessisslightlymorecomplicated.
We'llassumeyou'vealreadysetupapubliclyaccessiblerepositoryatURLgit@githost-ing.
com:contrib.
git,keptitup-to-datewithMantisBT'sofficialrepository,andthatyouhavepushedyourfeaturebranchMyBranchtoit.
1.
GeneratethePullRequestThiswilllistinformationaboutyourchangesandhowtoaccessthem.
Theprocesswillattempttoverifythatyou'vepushedthecorrectdatatothepublicrepository,andwillgenerateasummaryofchanges.
gitrequest-pullorigin/mastergit@githosting.
com:contrib.
gitMyBranch2.
Pastetheoutputoftheabovecommandintoabugreportoranemailtothedevelopermailinglist[mailto:mantisbt-dev@lists.
sourceforge.
net]Onceyourpullrequesthasbeenposted,developersandotheruserscanaddyourpublicrepositoryasaremote,andtrackyourfeaturebranchintheirownworkingrepositoryusingthefollowingcommands,replacingtheremotenameandlocalbranchnameasappropriate:gitremoteaddfeaturegit@githosting.
com:contrib.
git7ContributingtoMantisBTgitcheckout-bMyBranchfeature/MyBranchIfthefeatureisapprovedforentryintoMantisBTcore,thenthebranchshouldfirstberebasedontothelatestHEADsothatGitcanremoveanyunnecessarymergecommits,andcreatealinearhistory.
Oncethat'scompleted,thefeaturebranchcanbemergedintomaster:gitrebasemasterfeaturegitcheckoutmastergitmerge--no-fffeature8Chapter2.
DatabaseSchemaManagementTheMantisBTschemaTheMantisBTdatabaseschema(excludingplugins)isdescribedintheEntity-Relationshipdiagram(ERD)below.
ThereisalsoaPDFversionavailablefordownload[https://mantisbt.
org/docs/erd/].
Figure2.
1.
MantisBTEntity-RelationshipDiagram[images/erd.
png]SchemaDefinitionTODO:DiscusstheADODBdatadictformatsandtheformatMantisBTexpectsforschemadefinitions.
Installation/UpgradeProcessTODO:DiscusshowMantisBThandlesadatabaseinstallation/upgrade,includingtheuseoftheconfigsystemandschemadefinitions.
9Chapter3.
EventSystemGeneralConceptsTheeventsysteminMantisBTusestheconceptofsignalsandhookedeventstodrivedynamicactions.
Functions,orpluginmethods,canbehookedduringruntimetovariousdefinedevents,whichcanbesignalledatanypointtoinitiateexecutionofhookedfunctions.
Eventsaredefinedatruntimebynameandeventtype(coveredinthenextsection).
Dependingontheeventtype,signalparametersandreturnvaluesfromhookedfunctionswillbehandledindifferentwaystomakecertaintypesofcommoncommunicationsimplified.
APIUsageThisisageneraloverviewoftheeventAPI.
Formoredetailedanalysis,youmayreferencethefilecore/event_api.
phpinthecodebase.
DeclaringEventsWhendeclaringevents,theonlyinformationneededistheeventnameandeventtype.
Eventscanbedeclaredaloneusingtheform:event_declare($name,$type=EVENT_TYPE_DEFAULT);ortheycanbedeclaredingroupsusingkey/valuepairsofname=>typerelations,storedinasinglearray,suchas:$events=array($name_1=>$type_1,$name_2=>$type_2,.
.
.
);event_declare_many($events);HookingEventsHookingeventsrequiresknowingthenameofanalready-declaredevent,andthenameofthecallbackfunction(andpossiblyassociatedplugin)thatwillbehookedtotheevent.
Ifhookingonlyafunction,itmustbedeclaredintheglobalnamespace.
event_hook($event_name,$callback,[$plugin]);Inordertohookmanyfunctionsatonce,usingkey/valuepairsofname=>callbackrelations,inasinglearray:$events=array($event_1=>$callback_1,$event_2=>$callback_2,.
.
.
10EventSystem);event_hook($events,[$plugin]);SignallingEventsWhensignallingevents,theeventtypeofthetargeteventmustbekeptinmindwhenhandlingeventparametersandreturnvalues.
Thegeneralformatforsignallinganeventusesthefollowingstructure:$value=event_signal($event_name,[array($param,array($static_Eachtypeofevent(andindividualeventsthemselves)willusedifferentcombinationsofparametersandreturnvalues,soperusingChapter5,EventsReferenceisrecommendedfordeterminingtheuniqueneedsofeacheventwhensignallingandhookingthem.
EventTypesTherearefivestandardeventtypescurrentlydefinedinMantisBT.
Eachtypeisageneralizationofacertain"class"ofsolutiontotheproblemsthattheeventsystemisdesignedtosolve.
Eachtypeallowsforsimplifyingadifferentsetofcommunicationneedsbetweeneventsignalsandhookedcallbackfunctions.
Eachtypeofevent(andindividualeventsthemselves)willusedifferentcombinationsofparametersandreturnvalues,soperusingChapter5,EventsReferenceisrecommendedfordeterminingtheuniqueneedsofeacheventwhensignallingandhookingthem.
EVENT_TYPE_EXECUTEThisisthesimplesteventtype,meantforinitiatingbasichookexecutionwithoutneedingtocommunicatemorethanasetofimmutableparameterstotheevent,andexpectingnoreturnofdata.
Theseeventsonlyusethefirstparameterarray,andreturnvaluesfromhookedfunctionsareignored.
Exampleusage:event_signal($event_name,[array($param,EVENT_TYPE_OUTPUTThiseventtypeallowsforsimpleoutputandexecutionfromhookedevents.
Asinglesetofimmutableparametersaresenttoeachcallback,andthereturnvalueisinlinedasoutput.
Thiseventisgenerallyusedforaneventwithaspecificpurposeofaddingcontentormarkuptothepage.
Theseeventsonlyusethefirstparameterarray,andreturnvaluesfromhookedfunctionsareimmediatelysenttotheoutputbuffervia'echo'.
Anotherparameter$formatcanbeusedtomodelhowtheresultsareprinted.
Thisparametercanbeeither:null,oromitted:Thereturnedvaluesareprintedwithoutfurtherprocessing:Astringtobeusedasseparatorforprintedvalues:Anarrayof(prefix,separator,postfix)tobeusedfortheprintedvaluesExampleusage:11EventSystemevent_signal($event_name,[array($param,format]);EVENT_TYPE_CHAINThiseventtypeisdesignedtoallowpluginstosuccessivelyaltertheparametersgiventothem,suchthattheendresultreturnedtothecallerisamutatedversionoftheoriginalparameters.
Thisisveryusefulforsuchthingsasoutputmarkupparsers.
Thefirstsetofparameterstotheeventaresenttothefirsthookedcallback,whichisthenexpectedtoaltertheparametersandreturnthenewvalues,whicharethensenttothenextcallbacktomodify,andthiscontinuesforallcallbacks.
Thereturnvaluefromthelastcallbackisthenreturnedtotheeventsignaller.
Thistypeallowseventstooptionallymakeuseofthesecondparameterset,whicharesenttoeverycallbackintheseries,butshouldnotbereturnedbyeachcallback.
Thisallowsthesignallingfunctiontosendextra,immutableinformationtoeverycallbackinthechain.
Exampleusage:$value=event_signal($event_name,$param,[array($static_param,EVENT_TYPE_FIRSTThedesignofthiseventtypeallowsformultiplehookedcallbacksto'compete'fortheeventsignal,basedonpriorityandexecutionorder.
Thefirstcallbackthatcansatisfytheneedsofthesignalisthelastcallbackexecutedfortheevent,anditsreturnvalueistheonlyonesenttotheeventcaller.
Thisisveryusefulfortopicslikeuserauthentication.
Theseeventsonlyusethefirstparameterarray,andthefirstnon-nullreturnvaluefromahookfunctionisreturnedtothecaller.
Subsequentcallbacksareneverexecuted.
Ex-ampleusage:$value=event_signal($event_name,[array($param,EVENT_TYPE_DEFAULTThisisthefallbackeventtype,inwhichthereturnvaluesfromallhookedcallbacksarestoredinaspecialarraystructure.
Thisallowstheeventcallertogatherdataseparatelyfromallevents.
Theseeventsonlyusethefirstparameterarray,andreturnvaluesfromhookedfunctionsarereturnedinamulti-dimensionalarraykeyedbypluginnameandhookedfunctionname.
Exampleusage:$values=event_signal($event_name,[array($param,12Chapter4.
PluginSystemGeneralConceptsThepluginsystemforMantisBTisdesignedasalightweightextensiontothestandardMantisBTAPI,allowingforsimpleandflexibleadditionofnewfeaturesandcustomizationofcoreoperations.
IttakesadvantageofthenewEventSystem(seeChapter3,EventSystem)toofferdevelopersrapidcreationandtestingofextensions,withouttheneedtomodifycorefiles.
Pluginsaredefinedasimplementations,orsubclasses,oftheMantisPluginclassasdefinedincore/classes/MantisPlugin.
php.
Eachpluginmaydefineinformationaboutitself,aswellasalistofconflictsanddependenciesuponotherplugins.
TherearemanymethodsdefinedintheMantisPluginclassthatmaybeusedasconvenientplacestodefineextrabehaviors,suchasconfigurationoptions,eventdeclarations,eventhooks,errors,anddatabaseschemas.
Outsideaplugin'scoreclass,thereisastandardmethodofhandlinglanguagestrings,contentpages,andfiles.
Atpageload,thecoreMantisBTAPIwillfindandprocessanyconformingplugins.
Pluginswillbecheckedforminimalinformation,suchasitsname,version,anddependencies.
Pluginsthatmeetrequirementswillthenbeinitialized.
Atthispoint,MantisBTwillinteractwiththepluginswhenappropriate.
ThepluginsystemincludesaspecialsetofAPIfunctionsthatprovideconveniencewrappersaroundthemoreusefulMantisBTAPIcalls,includingconfiguration,languagestrings,andlinkgeneration.
ThisAPIallowspluginstousecoreAPI'sin"sandboxed"fashionstoaidinteroperationwithotherplugins,andsimplificationofcommonfunctionality.
BuildingaPluginThissectionwillactasatutorialtobuildanewplugin,fromthebarebasicsallthewayuptoadvancedtopics.
AgeneralunderstandingofHTML,PHPandtheconceptscoveredinthelastsectionisassumed,aswellasknowledgeofhowtheeventsystemworks.
LatertopicsinthissectionwillrequireknowledgeofdatabaseschemasandhowtheyareusedwithMantisBT.
Thiswalk-throughwillbeworkingtowardsbuildingasingleendresult:theExamplePlugin.
Youmayrefertothefinalcodealongtheway(seethesectioncalled"ExamplePluginsourcecode"),althougheverypartofitwillbebuiltupinstepsthroughoutthissection.
PluginStructureThissectionwillintroducethegeneralconceptsofpluginstructure,andhowtogetabare-bonespluginworkingwithMantisBT.
Notmuchwillbementionedyetonthetopicofaddingfunctionalitytoplugins,justhowtogetthedevelopmentprocessrolling.
ThebackboneofeverypluginiswhatMantisBTcallsthebasename,asuccinct,andmostimportantly,uniquenamethatidentifiestheplugin.
ItmaynotcontainanyspacingorspecialcharactersbeyondtheASCIIupper-andlowercasealphabet,numerals,andunderscore.
Thisisusedtoidentifythepluginevery-whereexceptforwhattheend-usersees.
Forour"Example"plugin,thebasenamewewilluseshouldbeobviousenough:Example.
Everypluginmustbecontainedinasingledirectory,namedtomatchtheplugin'sbasename,aswellascontainatleastasinglePHPfile,alsonamedtomatchthebasename,assuch:13PluginSystemNotethatforpluginsthatrequireadatabaseschematooperate,thebasenameisalsousedtobuildthetablenames,usingtheMantisBTtableprefixesandsuffix(pleaserefertotheAdminGuide'sConfigura-tionsectionforfurtherinformation).
IfourExamplepluginweretocreateatablenamed'foo',assumingdefaultvaluesforprefixesandsuffixinMantisBTconfiguration,thephysicaltablenamewouldbeman-tis_plugin_Example_foo_table.
Example/Example.
phpWarningDependingoncasesensitivityoftheunderlyingfilesystem,thesenamesmustexactlymatchtheplugin'sbasename,i.
e.
examplewillnotwork.
Thistop-levelPHPfilemustthencontainaconcreteclassderivingfromtheMantisPluginclass,whichmustbenamedintheformof%Basename%Plugin,whichforourpurposebecomesExamplePlu-gin.
BecauseofhowMantisPlugindeclarestheregister()methodasabstract,ourpluginmustimplementthatmethodbeforePHPwillfinditsemanticallyvalid.
Thismethodismeantforonesimplepurpose,andshouldneverbeusedforanyothertask:settingtheplugin'sinformationpropertiesincludingtheplugin'sname,description,version,andmore.
Pleaserefertothesectioncalled"Properties"belowfordetailsaboutavailableproperties.
Onceyourplugindefinesitsclass,implementstheregister()method,andsetsatleastthenameandversionproperties,itisthenconsidereda"complete"plugin,andcanbeloadedandinstalledwithinMantisBT'spluginmanager.
Atthisstage,ourExampleplugin,withallthepossiblepluginpropertiessetatregistration,lookslikethis:Example/Example.
phpname='ExamplePlugin';#Propernameofplugin$this->description='ExamplePluginfromMantisBTDevelopersGuide';#Shortdescriptionoftheplugin$this->page='';#Defaultpluginpage$this->version='2.
0';#Pluginversionstring$this->requires=array(#Plugindependencies'MantisCore'=>'2.
0',#Shouldalwaysdependonanappropria#versionofMantisBT);$this->author='MantisBTTeam';#Author/teamname$this->contact='mantisbt-dev@lists.
sourceforge.
net';#Author/teame-mailaddress$this->url='https://mantisbt.
org';#Supportwebpage}}ThisalonewillallowourExampleplugintobeinstalledwithMantisBT,andisthefoundationofanyplugin.
Moreoftheplugindevelopmentprocesswillbecontinuedinthenextsections.
14PluginSystemPropertiesThissectiondescribesthepropertiesthatcanbedefinedwhenregisteringtheplugin.
nameYourplugin'sfullname.
Requiredvalue.
descriptionAfulldescriptionofyourplugin.
pageThenameofapluginpageforfurtherinformationandadministrationoftheplugin;thisisusuallythePlugin'sconfigurationpage.
MantisBTwillcreatealinktothespecifiedpageontheManagePluginspage.
versionYourplugin'sversionstring.
Requiredvalue.
WerecommendfollowingtheSemanticVersioning[https://semver.
org/]specification,butyouarefreetouseanyversioningschemethatcanbehandledbyPHP'sversion_compare()[https://www.
php.
net/man-ual/en/function.
version-compare.
php]function.
requiresAnarrayofkey/valuepairsofbasename/versionplugindependencies.
NoteThespecial,reservedMantisCorebasenamecanbeusedtospecifythemin-imumrequirementforMantisBTcore.
Theversionstringcanbedefinedas:Minimumrequirement:thepluginspecifiedbythegivenbasenamemustbeinstalled,anditsversionmustbeequalorhigherthantheindicatedone.
Maximumrequirement:prefixingaversionnumberwith'requires=array('MantisCore'=>'1.
3.
1');15PluginSystemThepluginiscompatiblewithMantisBT>=1.
3.
1andrequires=array('MantisCore'=>'2.
0');ThepluginiscompatiblewithMantisBT>=2.
0andrequires=array('MantisCore'=>'requires=array('MantisCore'=>'1.
3,=1.
3andHereisalinkto">pagefoo.
Ourcustomstylesheetpaintsthistextred.
NoteWhileplugin_page()expectsonlythepage'snamewithouttheextension,plug-in_file()ontheotherhandrequirestheentirefilename,sothatitcandistinguishe.
g.
betweenfoo.
cssandapotentialimagefilecalledfoo.
png.
Theplugin'sfilesystemstructureatthispointlookslikethis:Example/Example.
phppages/foo.
phpfiles/17PluginSystemfoo.
cssEventsPluginshaveanintegratedmethodforbothdeclaringandhookingevents,withoutneedingtodirectlycalltheeventAPIfunctions.
Thesetaketheformofclassmethodsonyourplugin.
Todeclareanewevent,orasetofeventsthatyourpluginwilltrigger,overridetheevents()methodofyourpluginclass,andreturnanassociativearraywitheventnamesasthekey,andtheeventtypeasthevalue.
Let'saddtoourExampleplugin,aneweventfoothatdoesnotexpectareturnvalue(an"execute"eventtype),andanothereventbarexpectingasinglevaluethatgetsmodifiedbyeachhookedfunction(a"chain"eventtype):Example/Example.
phpEVENT_TYPE_EXECUTE,'EVENT_EXAMPLE_BAR'=>EVENT_TYPE_CHAIN,);}}WhentheExamplepluginisloaded,theeventsysteminMantisBTwilladdthesetwoitemstoitslistofevents,andwillthenallowotherpluginsorfunctionstohookthem.
NoteNamingtheevents"EVENT_PLUGINBASENAME_EVENTNAME"isnotrequired,butiscon-sideredbestpracticetoavoidconflictsbetweenplugins.
Hookingevents,whethertheyareyourownplugin'sordefinedelsewhere,isalmostidenticaltodeclaringthem.
Insteadofpassinganeventtypeasthevalue,yourpluginmustgivethenameofaclassmethodthatwillbecalledwhentheeventistriggered.
ForourExampleplugin,we'llcreateafoo()andabar()methodsinourpluginclass,thenhookthemtotheeventswedeclaredearlier.
We'llalsohookthestandardEVENT_MENU_MAINevent,tolinkthecustompagewecreatedinthesectioncalled"PagesandFiles".
Example/Example.
php'menu',18PluginSystem'EVENT_EXAMPLE_FOO'=>'foo','EVENT_EXAMPLE_BAR'=>'bar',);}}Functionsignaturesvarydependingonthehookedevent'stype(seethesectioncalled"EventTypes").
Theygenerallyshouldacceptthe$p_eventparameter,whichcontainstheeventnametriggeringthemethod(allowingasinglemethodtorespondtomultipleevents).
Thebar()methodalsoacceptsandreturnsasecondparameter,inordertomatchtheexpectationsofchainedevents.
Nowthatwehaveourplugin'seventsdeclaredandhooked,let'sdefinethehookmethodsandmodifyourearlierpagesoittriggersthenewevents:Example/Example.
php$this->name,'url'=>plugin_page('foo'),'access_level'=>ANYBODY,'icon'=>'fa-smile-o');return$t_menu;}functionfoo($p_event){echo'Inmethodfoo().
';}functionbar($p_event,$p_chained_param){returnstr_replace('foo','bar',$p_chained_param);}}Example/pages/foo.
php.
.
.
Customeventhooks:Whenthefirstevent"foo"issignaled,theExampleplugin'sfoo()methodwillexecuteandechoastring.
Afterthat,thesecondevent"bar"issignaled,andthepagepassesastringparameter;theplugin'sbar()19PluginSystemgetsthestringandreplacesanyinstanceof"foo"with"bar",andreturnstheresultingstring.
Ifanyotherpluginhadhookedtheevent,thatplugincouldhavefurthermodifiedthenewstringfromtheExampleplugin,orviceversa,dependingontheloadingorderofplugins.
Thepagethenechosthemodifiedstringthatwasreturnedfromtheevent.
ConfigurationSimilartoevents,pluginshaveasimplifiedmethodfordeclaringconfigurationoptions,aswellasAPIfunctionsforretrievingorsettingthosevaluesatruntime.
Declaringanewconfigurationoptionisachievedjustlikedeclaringevents.
Byoverridingtheconfig()methodonyourpluginclass,yourplugincanreturnanassociativearrayofconfigurationoptions,withtheoptionnameasthekey,andthedefaultoptionasthearrayvalue.
OurExamplepluginwilldeclareanoption"foo_or_bar",withadefaultvalueof"foo":Example/Example.
php'foo',);}}Retrievingthecurrentvalueofaplugin'sconfigurationoptionisachievedbyusingthepluginAPI'splu-gin_config_get()function,andcanbesettoamodifiedvalueinthedatabaseusingplugin_con-fig_set().
Withthesefunctions,theconfigoptionisprefixedwiththeplugin'sname,inanattempttoautomaticallyavoidconflictsinnaming.
OurExamplepluginwilldemonstratethisbyaddingasecureformtoanewconfigurationpagewe'llcallconfig.
php,andhandlingtheformonaseparateconfig_update.
phppagethatwillmodifythevalueinthedatabase,andredirectbacktotheconfigpage,justlikeanyotherformandactionpageinMantisBT:NoteThiscodesampleisabare-bonesimplementation,focusingonfunctionalityandmeantforillus-trationpurposes.
Pleaserefertothesectioncalled"Layout"foramorerealisticexample,includ-inglayoutandstyling.
Example/pages/config.
php"method="post">FooorBar20PluginSystemResetExample/pages/config_update.
phppage='config';#DefaultpluginpageLanguageandLocalizationMantisBThasaveryadvancedsetoflocalizationtools,whichallowallpartsofoftheapplicationtobelocalizedtotheuser'spreferredlanguage.
Thisfeaturehasbeenextendedforusebypluginsaswell,sothataplugincanbelocalizedinmuchthesamemethodasusedforthecoresystem.
Localizingaplugin21PluginSysteminvolvescreatingalanguagefileforeachlocalizationavailable,andusingaspecialAPIcalltoretrievetheappropriatestringfortheuser'slanguage.
AlllanguagefilesforpluginsfollowthesameformatusedinthecoreofMantisBT,shouldbeplacedintheplugin'slang/directory,andnamedthesameasthecorelanguagefiles.
Stringsspecifictothepluginshouldbe"namespaced"inawaythatwillminimizeanyriskofcollision.
TranslatingtheplugintootherlanguagesalreadysupportedbyMantisBTisthenassimpleascreatinganewstringsfilewiththelocalizedcontent;theMantisBTcorewillfindandusethenewlanguagestringsautomatically.
We'llusethepagesfromthepreviousexamples,anddressthemupwithlocalizedlanguagestrings.
FirstweneedtocreatealanguagefileforEnglish,MantisBT'sdefaultlanguagewhichisalsousedasfallbackincasesomestringshavenotbeenlocalizedtotheuser'slanguage:Example/lang/strings_english.
txtdescription=plugin_lang_get('title');Example/pages/foo.
php.
.
.
Example/pages/config.
php"method="post">22PluginSystemLayoutTofinalizeourplugin,we'lladdsomemarkupandflourishestomaketheconfigpagelooklikeastandardMantisBTpage.
NoteAlternatingcolorsareappliedautomaticallytothetable'srowswithCSS,itisnolongernecessarytorelyonthenow-deprecatedhelper_alternate_rows()APIfunction.
Example/pages/config.
php