latest PDF

23 Pages·2016·0.13 MB·English

Jaxl Documentation
Release 3.0.1
Abhinav Singh
August13,2016

Contents
1 UsersGuide 3
1.1 GettingStarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 JAXLInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 ./jaxlctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 LoggingInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.5 CronJobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2 XMPPUsersGuide: 11
2.1 XMPPExamples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2 XmlObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3 XMPPExtensions(XEP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3 HTTPUsersGuide: 17
3.1 HTTPExamples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 HTTPExtensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
i
ii
JaxlDocumentation,Release3.0.1
Jaxlv3.xisasuccessorofv2.x(andisNOTbackwardcompatible),carryingalotofcodefromv2.xwhilethrowing
away the ugly parts. A lot of components have been re-written keeping in mind the feedback from the developer
communityoverthelast4years. AlsoJaxlnowsharesafewphilosophiesfrommyexperiencewitherlangandpython
languages.
Jaxl is an asynchronous, non-blocking I/O, event based PHP library for writing custom TCP/IP client and server
implementations. Fromit’spreviousversions,libraryinheritsafullblownstablesupportforXMPPprotocolstack. In
v3.0,supportforHTTPprotocolstackwasalsoadded.
AttheheartofeveryprotocolstacksitsaCorestack. Itcontainsallthebuildingblocksforeverythingthatweaimto
do with Jaxl library. Both XMPP and HTTP protocol stacks are written on top of the Core stack. Infact the source
codeofprotocolimplementationsknowsnothingaboutthestandard(inbuilt)PHPsocketandstreammethods.
Contents 1
JaxlDocumentation,Release3.0.1
2 Contents
1
CHAPTER
Users Guide
1.1 Getting Started
1.1.1 Requirements
Noexternalcomponentorlibraryisrequired. YousimplyneedastandardPHPinstallationtoworkwithJaxl.
Libraryhasbeendevelopedandtestedextensivelyonlinuxoperatingsystems. Butthereisnoreasonwhyitshould
notworkonotherOS.Fileanissueifyoufaceanyglitches.
1.1.2 Download & Install
Downloadastabletaggedv3.xreleasefromhttps://github.com/abhinavsingh/JAXL/tags
Youcanalsocheckoutgitbranchandswitchtoatagofyourchoice:
>>> git clone git://github.com/abhinavsingh/JAXL.git
>>> cd JAXL/
>>> git tag -l
>>> git checkout some-tag-name
To install Jaxl library globally, simply append path of the downloaded JAXL folder to include_path directive
insideyourphp.ini. ThiswillallowustouseJaxllibrarysimplybydoing:
require ’jaxl.php’;
Alternately,ifyoudon’twanttoeditphp.iniorincaseyoudon’thaveaccesstotheinifile,simplyuse:
require ’/full/path/to/JAXL/jaxl.php’;
tostartusingJaxllibrary.
1.1.3 Library Structure
Jaxllibrarycomprisesoffollowingpackages:
• jaxl-core
containsgenericnetworkingandeventingcomponents
• jaxl-xmpp
containsxmpprfcimplementation
3
JaxlDocumentation,Release3.0.1
• jaxl-xmpp-xep
containsvariousxmppxepimplementation
• jaxl-http
containshttprfcimplementation
• jaxl-docs
thisdocumentationcomesfromthispackage
• jaxl-tests
testsuitesforalltheabovepackages
InsideJaxleverythingthatyouwillinteractwithwillbeanobjectwhichwillemiteventsandcallbackswhichwewill
beabletocatchinourapplicationsforcustomprocessingandrouting. Listedbelowareafewmainobjects:
1. CoreStack
• JAXLLoop
mainselectloop
• JAXLClock
timedjob/callbackdispatcher
• JAXLEvent
eventregistryandemitter
• JAXLFsm
genericfinitestatemachine
• JAXLSocketClient
generictcp/udpclient
• JAXLSocketServer
generictcp/udpserver
• JAXLXmlStream
streamingXMLparser
• JAXLXml
customXMLobjectimplementation
• JAXLLogger
loggingfacility
1. XMPPStack
• XMPPStream
basexmpprfcimplementation
• XMPPStanza
provideseasyaccesspatternsoverxmppstanza(wrapsJAXLXml)
• XMPPIq
xmppiqstanzaobject(extendsXMPPStanza)
4 Chapter1. UsersGuide
JaxlDocumentation,Release3.0.1
• XMPPMsg
xmppmsgstanzaobject(extendsXMPPStanza)
• XMPPPres
xmpppresstanzaobject(extendsXMPPStanza)
• XMPPXep
abstractxmppextension(extendedbyXEPimplementations)
• XMPPJid
xmppjidobject
1. HTTPStack
• HTTPServer
httpserverimplementation
• HTTPClient
httpclientimplementation
• HTTPRequest
httprequestobject
• HTTPResponse
httpresponseobject
1.1.4 Questions, Bugs and Issues
Ifyouhaveanyquestionskindlypostthemongooglegroups. Groupsarethequickestwaytogetananswertoyour
questionswhichisactivelymonitoredbycoredevelopers.
Ifyouarefacingabugorissue,pleasereportthatitongithubissuetracker. Youcanevencontributetothelibraryif
youalreadyhavefixedthebug.
1.2 JAXL Instance
JAXL instance configure/manage other sub-packages. It provides an event based callback methodology on various
underlyingobject. WheneverrequiredJAXLinstancewillitselfperformtheconfigureddefaults.
1.2.1 Constructor options
1. jid
2. pass
3. resource
IfnotpassedJaxlwillusearandomresourcevalue
4. auth_type
DIGEST-MD5,PLAIN(default),CRAM-MD5,ANONYMOUS,X-FACEBOOK-PLATFORM
5. host
1.2. JAXLInstance 5
JaxlDocumentation,Release3.0.1
6. port
7. bosh_url
8. log_path
9. log_level
JAXL_ERROR,JAXL_WARNING,JAXL_NOTICE,JAXL_INFO(default),JAXL_DEBUG
10. fb_access_token
requiredwhenusingX-FACEBOOK-PLATFORMauthmechanism
11. fb_app_key
requiredwhenusingX-FACEBOOK-PLATFORMauthmechanism
12. force_tls
13. stream_context
14. priv_dir
Jaxlcreates4directoriesnameslog,tmp,runandsockinsideaprivatedirectorywhichdefaults
toJAXL_CWD.’/.jaxl’. Ifthisoptionispassed,itwilloverwritedefaultprivatedirectory.
Note: Jaxl currently doesn’t check upon the permissions of passed priv_dir. Make sure Jaxl
libraryhavesufficientpermissionstocreateabovementioneddirectories.
1.2.2 Available Event Callbacks
Following$evareavailableonJAXLlifecycleforregisteringcallbacks:
1. on_connect
JAXLinstancehasconnectedsuccessfully
2. on_connect_error
JAXLinstancefailedtoconnect
3. on_stream_start
JAXLinstancehassuccessfullyinitiatedXMPPstreamwiththejabberserver
4. on_stream_features
JAXLinstancehasreceivedsupportedstreamfeatures
5. on_auth_success
authenticationsuccessful
6. on_auth_failure
authenticationfailed
7. on_presence_stanza
JAXLinstancehasreceivedapresencestanza
8. on_{$type}_message
JAXL instance has received a message stanza. $type can be chat, groupchat, headline,
normal,error
6 Chapter1. UsersGuide