From 6b6935fca37a3b4231ce0177d7de045ed165d202 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:00:33 +0100 Subject: [PATCH 01/12] Initial Sphinx docs implementation --- docs/.gitignore | 2 + docs/Makefile | 225 ++++++++++++++++++++++++++++++ docs/client.rst | 248 +++++++++++++++++++++++++++++++++ docs/conf.py | 346 ++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 27 ++++ docs/make.bat | 281 +++++++++++++++++++++++++++++++++++++ docs/overview.rst | 56 ++++++++ 7 files changed, 1185 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/client.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/overview.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..d4e11e5 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +_build + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4552eb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,225 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Mosquitto-PHP.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Mosquitto-PHP.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Mosquitto-PHP" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Mosquitto-PHP" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/docs/client.rst b/docs/client.rst new file mode 100644 index 0000000..74f54ae --- /dev/null +++ b/docs/client.rst @@ -0,0 +1,248 @@ +================= +Mosquitto\\Client +================= + +.. php:namespace:: Mosquitto + +.. php:class:: Client + + This is the main Mosquitto client. + + .. php:method:: __construct([$id = null, $cleanSession = true]) + + Construct a new Client instance. + + :param string $id: The client ID. If omitted or ``null``, one will be generated at random. + :param boolean $cleanSession: Set to ``true`` to instruct the broker to clean all messages and subscriptions on disconnect. Must be true if the ``$id`` parameter is ``null``. + + + .. php:method:: setCredentials($username, $password) + + Set the username and password to use on connecting to the broker. Must be called before ``connect()``. + + :param string $username: Username to supply to the broker + :param string $password: Password to supply to the broker + + .. php:method:: setTlsCertificates($caPath, $certFile, $keyFile, $password) + + Configure the client for certificate based SSL/TLS support. Must be called before connect(). Cannot be used in conjunction with setTlsPSK(). + + Define the Certificate Authority certificates to be trusted (ie. the server certificate must be signed with one of these certificates) using cafile. If the server you are connecting to requires clients to provide a certificate, define certfile and keyfile with your client certificate and private key. If your private key is encrypted, provide the password as the fourth parameter, or you will have to enter the password at the command line. + + :param string $username: Path to the PEM encoded trusted CA certificate files, or to a directory containing them. + :param string $certFile: Path to the PEM encoded certificate file for this client. Optional. + :param string $keyFile: Path to a file containing the PEM encoded private key for this client. Required if certfile is set. + :param string $password: The password for the keyfile, if it is encrypted. If null, the password will be asked for on the command line. + + .. php:method:: setTlsInsecure($value) + + Configure verification of the server hostname in the server certificate. If value is set to true, it is impossible to guarantee that the host you are connecting to is not impersonating your server. Do not use this function in a real system. Must be called before connect(). + + :param boolean $value: If set to false, the default, certificate hostname checking is performed. If set to true, no hostname checking is performed and the connection is insecure. + + .. php:method:: setTlsOptions($certReqs, $tlsVersion, $ciphers) + + Set advanced SSL/TLS options. Must be called before ``connect()``. + + :param int $certReqs: Whether or not to verify the server. Can be ``Mosquitto\\Client::SSL_VERIFY_NONE``, to disable certificate verification, or ``Mosquitto\Client::SSL_VERIFY_PEER`` (the default), to verify the server certificate. + :param string $tlsVersion: The TLS version to use. If ``null``, a default is used. The default value depends on the version of OpenSSL the library was compiled against. Available options on OpenSSL >= 1.0.1 are 'tlsv1.2', 'tlsv1.1' and 'tlsv1'. + :param string $cipers: A string describing the ciphers available for use. See the ``openssl ciphers`` tool for more information. If ``null``, the default set will be used. + + .. php:method:: setTlsPSK() + + Configure the client for pre-shared-key based TLS support. Must be called before connect(). Cannot be used in conjunction with setTlsCertificates. + + :param string $psk: The pre-shared key in hex format with no leading "0x". + :param string $identity: The identity of this client. May be used as the username depending on server settings. + :param string $cipers: Optional. A string describing the ciphers available for use. See the ``openssl ciphers`` tool for more information. If ``null``, the default set will be used. + + .. php:method:: setWill() + + Set the client "last will and testament", which will be sent on an unclean disconnection from the broker. Must be called before connect(). + + :param string $topic: The topic on which to publish the will. + :param string $payload: The data to send. + :param int $qos: Optional. Default 0. Integer 0, 1, or 2 indicating the Quality of Service to be used. + :param boolean $retain: Optional. Default false. If true, the message will be retained. + + .. php:method:: clearWill() + + Remove a previously-set will. No parameters. + + .. php:method:: setReconnectDelay() + + Control the behaviour of the client when it has unexpectedly disconnected in loopForever. The default behaviour if this method is not used is to repeatedly attempt to reconnect with a delay of 1 second until the connection succeeds. + + :param int $reconnect_delay: Set delay between successive reconnection attempts. + :param int $reconnect_delay: Set max delay between successive reconnection attempts when exponential backoff is enabled + :param bool $exponential_backoff: Enable exponential backoff + + .. php:method:: connect() + + Connect to an MQTT broker. + + :param string $host: Hostname to connect to + :param int $port: Optional. Port number to connect to. Defaults to 1883. + :param int $keepalive: Optional. Number of sections after which the broker should PING the client if no messages have been recieved. + :param string $interface: Optional. The address or hostname of a local interface to bind to for this connection. + + .. php:method:: disconnect() + + Disconnect from the broker. No parameters. + + .. php:method:: onConnect() + + Set the connect callback. This is called when the broker sends a CONNACK message in response to a connection. + + :param callback $callback: The callback + + The callback should take parameters of the form: + + :param int $rc: Response code from the broker. + :param string $message: String description of the response code. + + Response codes are as follows: + + ===== ==== + Code Meaning + ----- ---- + 0 Success + 1 Connection refused (unacceptable protocol version) + 2 Connection refused (identifier rejected) + 3 Connection refused (broker unavailable ) + 4-255 Reserved for future use + ===== ==== + + .. php:method:: onDisconnect() + + Set the disconnect callback. This is called when the broker has received the DISCONNECT command and has disconnected the client. + + :param callback $callback: The callback + + The callback should take parameters of the form: + + :param int $rc: Reason for the disconnection. 0 means the client requested it. Any other value indicates an unexpected disconnection. + + .. php:method:: onLog() + + Set the logging callback. + + :param callback $callback: The callback + + The callback should take parameters of the form: + + :param int $level: The log message level from the values below + :param string $str: The message string. + + The level can be one of: + + * ``Mosquitto\Client::LOG_DEBUG`` + * ``Mosquitto\Client::LOG_INFO`` + * ``Mosquitto\Client::LOG_NOTICE`` + * ``Mosquitto\Client::LOG_WARNING`` + * ``Mosquitto\Client::LOG_ERR`` + + .. php:method:: onSubscribe() + + Set the subscribe callback. This is called when the broker responds to a subscription request. + + :param callback $callback: The callback + + The callback should take parameters of the form: + + :param int $mid: Message ID of the subscribe message + :param int $qos_count: Number of granted subscriptions + + This function needs to return the granted QoS for each subscription, but currently cannot. + + .. php:method:: onUnsubscribe() + + Set the unsubscribe callback. This is called when the broker responds to a unsubscribe request. + + :param callback $callback: The callback + + The callback should take parameters of the form: + + :param int $mid: Message ID of the unsubscribe message + + .. php:method:: onMessage() + + Set the message callback. This is called when a message is received from the broker. + + :param callback $callback: The callback + + The callback should take parameters of the form: + + :param Mosquitto\Message $message: A Message object containing the message data + + .. php:method:: onPublish() + + Set the publish callback. This is called when a message is published by the client itself. + + **Warning**: this may be called before the method ``Mosquitto\Client::publish()`` returns the message id, so, you need to create a queue to deal with the MID list. + + :param callback $callback: The callback + + The callback should take parameters of the form: + + :param int $mid: the message id returned by ``Mosquitto\Client::publish()`` + + .. php:method:: setMaxInFlightMessages() + + Set the number of QoS 1 and 2 messages that can be “in flight” at one time. An in flight message is part way through its delivery flow. Attempts to send further messages with publish() will result in the messages being queued until the number of in flight messages reduces. + + Set to 0 for no maximum. + + :param int $maxInFlightMessages: The maximum + + .. php:method:: setMessageRetry($messageRetryPeriod) + + Set the number of seconds to wait before retrying messages. This applies to publish messages with QoS>0. May be called at any time. + + :param int $messageRetryPeriod: The retry period + + .. php:method:: publish($topic, $payload, $qos = 0, $retain = false) + + Publish a message on a given topic. + + :param string $topic: The topic to publish on + :param string $payload: The message payload + :param int $qos: Integer value 0, 1 or 2 indicating the QoS for this message + :param boolean $retain: If true, make this message retained + :returntype: int + :returns: The message ID returned by the broker. **Warning**: the message ID is not unique. + + .. php:method:: subscribe() + + Subscribe to a topic. + + :param string $topic: The topic. + :param int $qos: The QoS to request for this subscription + + Returns the message ID of the subscription message, so this can be matched up in the onSubscribe callback. + + .. php:method:: unsubscribe() + + Unsubscribe from a topic. + + :param string $topic: The topic. + :param int $qos: The QoS to request for this subscription + + Returns the message ID of the subscription message, so this can be matched up in the onUnsubscribe callback. + + .. php:method:: loop() + + The main network loop for the client. You must call this frequently in order to keep communications between the client and broker working. If incoming data is present it will then be processed. Outgoing commands, from e.g. publish(), are normally sent immediately that their function is called, but this is not always possible. loop() will also attempt to send any remaining outgoing messages, which also includes commands that are part of the flow for messages with QoS>0. + + :param int $timeout: Optional. Number of milliseconds to wait for network activity. Pass 0 for instant timeout. Defaults to 1000. + :param int $max_packets: Currently unused. + + .. php:method:: loopForever() + + Call loop() in an infinite blocking loop. Callbacks will be called as required. This will handle reconnecting if the connection is lost. Call disconnect() in a callback to return from the loop. + + Note: exceptions thrown in callbacks do not currently cause the loop to exit. To work around this, use loop() and wrap your own loop structure around it such as a while(). + + :param int $timeout: Optional. Number of milliseconds to wait for network activity. Pass 0 for instant timeout. Defaults to 1000. + :param int $max_packets: Currently unused. + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..3cfe402 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,346 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Mosquitto-PHP documentation build configuration file, created by +# sphinx-quickstart on Mon Sep 5 20:57:18 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# Set up PHP syntax highlights +from sphinx.highlighting import lexers +from pygments.lexers.web import PhpLexer +lexers["php"] = PhpLexer(startinline=True, linenos=1) +lexers["php-annotations"] = PhpLexer(startinline=True, linenos=1) +primary_domain = "php" + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ["sphinxcontrib.phpdomain"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Mosquitto-PHP' +copyright = '2016, Michael Maclean' +author = 'Michael Maclean' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.4' +# The full version, including alpha/beta/rc tags. +release = '0.4.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# +# today = '' +# +# Else, today_fmt is used as the format for a strftime call. +# +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# +# html_title = 'Mosquitto-PHP v0.4.0' + +# A shorter title for the navigation bar. Default is the same as html_title. +# +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# +# html_additional_pages = {} + +# If false, no module index is generated. +# +# html_domain_indices = True + +# If false, no index is generated. +# +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Mosquitto-PHPdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Mosquitto-PHP.tex', 'Mosquitto-PHP Documentation', + 'Michael Maclean', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# +# latex_use_parts = False + +# If true, show page references after internal links. +# +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + +# If false, no module index is generated. +# +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'mosquitto-php', 'Mosquitto-PHP Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +# +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Mosquitto-PHP', 'Mosquitto-PHP Documentation', + author, 'Mosquitto-PHP', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# +# texinfo_appendices = [] + +# If false, no module index is generated. +# +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..16a819b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,27 @@ +.. Mosquitto-PHP documentation master file, created by + sphinx-quickstart on Mon Sep 5 20:57:18 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +============= +Mosquitto-PHP +============= + +Contents +======== + +.. toctree:: + :maxdepth: 2 + + overview + client + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..4179452 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,281 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. epub3 to make an epub3 + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + echo. coverage to run coverage check of the documentation if enabled + echo. dummy to check syntax errors of document sources + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 1>NUL 2>NUL +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Mosquitto-PHP.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Mosquitto-PHP.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "epub3" ( + %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3 + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub3 file is in %BUILDDIR%/epub3. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +if "%1" == "dummy" ( + %SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. Dummy builder generates no files. + goto end +) + +:end diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..3c1c482 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,56 @@ +======== +Overview +======== + +Requirements +============ + +* PHP 5.3 or newer +* libmosquitto 1.2.x or later + +Installation +============ + +If you've used a pre-built package to install Mosquitto, you need to make sure you have the development headers installed. On Red Hat-derived systems, this is probably called ``libmosquitto-devel``, and on Debian-based systems it will be ``libmosquitto-dev``. + +You may obtain this package using `PECL `_:: + + pecl install Mosquitto-alpha + +Alternatively, you can use the normal extension build process:: + + phpize + ./configure --with-mosquitto=/path/to/libmosquitto + make + make install + +Then add ``extension=mosquitto.so`` to your ``php.ini``. + +The ``--with-mosquitto`` argument is optional, and only required if your +libmosquitto install cannot be found. + +General Operation +================= + +The underlying library is based on callbacks and event-driven operation. As such, you have to call the ``loop()`` method of the ``Client`` frequently to permit the library to handle the messages in its queues. You can use ``loopForever()`` to ensure that the client handles this itself. Also, you should use the callback functions to ensure that you only attempt to publish after the client has connected, etc. For example, here is how you would correctly publish a QoS=2 message: + +.. code-block:: php + + onConnect(function() use ($c) { + $c->publish('mgdm/test', 'Hello', 2); + $c->disconnect(); + }); + + $c->connect('test.mosquitto.org'); + + // Loop around to permit the library to do its work + // This function will call the callback defined in `onConnect()` + // and disconnect cleanly when the message has been sent + $c->loopForever(); + + echo "Finished\n"; + + From aae11f621a13bc43ab9b2661ac404ac01fa266d8 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:13:04 +0100 Subject: [PATCH 02/12] Try and include PHP domain extension --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/requirements.txt diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..1c4b874 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +sphinxcontrib-phpdomain==0.2.0 From 55906648c3f002c676376fbbd85eb7bb51a5b685 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:16:04 +0100 Subject: [PATCH 03/12] Use RTD theme and add Github widget --- docs/conf.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 3cfe402..bca4787 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -127,7 +127,16 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +#html_theme = 'alabaster' + +html_context = { + "display_github": True, + "github_user": "mgdm", + "github_repo": project, + "github_version": "master", + "conf_py_path": "/docs/", + "source_suffix": source_suffix, +} # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the From c5bcca55bc0938de61a12de3d8bedfd233ec3d46 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:34:20 +0100 Subject: [PATCH 04/12] Remove docs from README --- README.md | 408 +----------------------------------------------------- 1 file changed, 2 insertions(+), 406 deletions(-) diff --git a/README.md b/README.md index e0c75aa..f2a0e02 100644 --- a/README.md +++ b/README.md @@ -61,413 +61,9 @@ for ($i = 0; $i < 100; $i++) { echo "Finished\n"; ``` -## API Documentation +## Documentation -The classes in this extension are namespaced. - -### Class Mosquitto\Client - -This is the actual Mosquitto client. - -1. [__construct](#__construct) - create a new client -1. [setCredentials](#setcredentials) - set the credentials to use on connection -1. [setTlsCertificates](#settlscertificates) - set the TLS certificate sources -1. [setTlsInsecure](#settlsinsecure) - Set verification of the server hostname - in TLS certificates -1. [setTlsOptions](#settlsoptions) - Set advanced TLS options -1. [setTlsPSK](#settlspsk) - Configure the client for pre-shared-key based TLS - support. -1. [setWill](#setwill) - set the client will, to be delivered if disconnected - uncleanly -1. [clearWill](#clearwill) - clear a previously-set will -1. [setReconnectDelay](#setreconnectdelay) - set the behaviour if disconnected - uncleanly -1. [connect](#connect) - connect to an MQTT broker -1. [disconnect](#disconnect) - disconnect from an MQTT broker -1. [onConnect](#onconnect) - set the connect callback -1. [onDisconnect](#ondisconnect) - set the disconnect callback -1. [onLog](#onlog) - set the logging callback -1. [onSubscribe](#onsubscribe) - set the subscribe callback -1. [onMessage](#onmessage) - set the callback fired when a message is received -1. [onPublish](#onpublish) - set the callback fired when a message is published -1. [setMaxInFlightMessages](#setmaxinflightmessages) - set the number of QoS - 1 and 2 messages that can be "in flight" at once -1. [setMessageRetry](#setmessageretry) - set the number of seconds to wait - before retrying messages -1. [publish](#publish) - publish a message to a broker -1. [subscribe](#subscribe) - subscribe to a topic -1. [unsubscribe](#unsubscribe) - unsubscribe from a topic -1. [loop](#loop) - The main network loop -1. [loopForever](#loopforever) - run loop() in an infinite blocking loop - -#### __construct - -Creates a new Client instance. - -| Parameter | Type | Description | -| --- | --- | ---- | -| id | string | Client ID. Optional. If not supplied or NULL, one will be generated at random. | -| clean_session | boolean | Set to true to instruct the broker to clean all messages and subscriptions on disconnect. | - -#### setCredentials - -Set the username and password to use on connecting to the broker. Must be -called before connect(). - -| Parameter | Type | Description | -| --- | --- | ---- | -| Username | string | Username to supply to the broker | -| Password | string | Password to supply to the broker | - -#### setTlsCertificates - -Configure the client for certificate based SSL/TLS support. Must be called -before connect(). Cannot be used in conjunction with setTlsPSK(). - -Define the Certificate Authority certificates to be trusted (ie. the server -certificate must be signed with one of these certificates) using cafile. -If the server you are connecting to requires clients to provide a certificate, -define certfile and keyfile with your client certificate and private key. If -your private key is encrypted, provide the password as the fourth parameter, or -you will have to enter the password at the command line. - -| Parameter | Type | Description | -| --- | --- | ---- | -| capath | string | Path to the PEM encoded trusted CA certificate files, or to a directory containing them | -| certfile | string | Path to the PEM encoded certificate file for this client. Optional. | -| keyfile | string | Path to a file containing the PEM encoded private key for this client. Required if certfile is set. | -| password | string | The password for the keyfile, if it is encrypted. If null, the password will be asked for on the command line. | - -#### setTlsInsecure - -Configure verification of the server hostname in the server certificate. If -value is set to true, it is impossible to guarantee that the host you are -connecting to is not impersonating your server. Do not use this function in -a real system. Must be called before connect(). - -| Parameter | Type | Description | -| --- | --- | ---- | -| value | boolean | If set to false, the default, certificate hostname checking is performed. If set to true, no hostname checking is performed and the connection is insecure. | - -#### setTlsOptions - -Set advanced SSL/TLS options. Must be called before connect(). - -| Parameter | Type | Description | -| --- | --- | ---- | -| certReqs | int | Whether or not to verify the server. Can be Mosquitto\Client::SSL_VERIFY_NONE, to disable certificate verification, or Mosquitto\Client::SSL_VERIFY_PEER (the default), to verify the server certificate. | -| tlsVersion | string | The TLS version to use. If NULL, a default is used. The default value depends on the version of OpenSSL the library was compiled against. Available options on OpenSSL >= 1.0.1 are 'tlsv1.2', 'tlsv1.1' and 'tlsv1'. | -| cipers | string | A string describing the ciphers available for use. See the `openssl ciphers` tool for more information. If NULL, the default set will be used. | - -#### setTlsPSK - -Configure the client for pre-shared-key based TLS support. Must be called before connect(). Cannot be used in conjunction with setTlsCertificates. - -| Parameter | Type | Description | -| --- | --- | ---- | -| psk | string | The pre-shared key in hex format with no leading "0x". -| identity | string | The identity of this client. May be used as the username depending on server settings. | -| cipers | string | Optional. A string describing the ciphers available for use. See the `openssl ciphers` tool for more information. If NULL, the default set will be used. | - -#### setWill - -Set the client "last will and testament", which will be sent on an unclean -disconnection from the broker. Must be called before connect(). - -| Parameter | Type | Description | -| --- | --- | ---- | -| topic | string | The topic on which to publish the will. | -| payload | string | The data to send. | -| qos | int | Optional. Default 0. Integer 0, 1, or 2 indicating the Quality of Service to be used. | -| retain | boolean | Optional. Default false. If true, the message will be retained. | - -#### clearWill - -Remove a previously-set will. No parameters. - -#### setReconnectDelay - -Control the behaviour of the client when it has unexpectedly disconnected in -loopForever. The default behaviour if this method is not used is to -repeatedly attempt to reconnect with a delay of 1 second until the connection -succeeds. - -| Parameter | Type | Description | -| --- | --- | ---- | -| reconnect_delay | int | Set delay between successive reconnection attempts. | -| reconnect_delay | int | Set max delay between successive reconnection attempts when exponential backoff is enabled | -| exponential_backoff | bool | Enable exponential backoff | - -#### connect - -Connect to an MQTT broker. - -| Parameter | Type | Description | -| --- | --- | ---- | -| host | string | Hostname to connect to | -| port | int | Optional. Port number to connect to. Defaults to 1883. | -| keepalive | int | Optional. Number of sections after which the broker should PING the client if no messages have been recieved. | -| interface | string | Optional. The address or hostname of a local interface to bind to for this connection. | - -#### disconnect - -Disconnect from the broker. No parameters. - -#### onConnect - -Set the connect callback. This is called when the broker sends a CONNACK message in response to a connection. - -| Parameter | Type | Description | -| --- | --- | ---- | -| callback | callback | The callback | - -The callback should take parameters of the form: - -| Parameter | Type | Description | -| --- | --- | ---- | -| rc | int | Response code from the broker. | -| message | string | String description of the response code. | - -Response codes are as follows: - -| Code | Meaning | -| --- | --- | -| 0 | Success | -| 1 | Connection refused (unacceptable protocol version) | -| 2 | Connection refused (identifier rejected) | -| 3 | Connection refused (broker unavailable ) | -| 4-255 | Reserved for future use | - -#### onDisconnect - -Set the disconnect callback. This is called when the broker has received the -DISCONNECT command and has disconnected the client. - -| Parameter | Type | Description | -| --- | --- | ---- | -| callback | callback | The callback | - -The callback should take parameters of the form: - -| Parameter | Type | Description | -| --- | --- | ---- | -| rc | int | Reason for the disconnection. 0 means the client requested it. Any other value indicates an unexpected disconnection. | - -#### onLog - -Set the logging callback. - -| Parameter | Type | Description | -| --- | --- | ---- | -| callback | callback | The callback | - -The callback should take parameters of the form: - -| Parameter | Type | Description | -| --- | --- | ---- | -| level | int | The log message level from the values below | -| str | string | The message string. - -The level can be one of: - -* Mosquitto\Client::LOG_DEBUG -* Mosquitto\Client::LOG_INFO -* Mosquitto\Client::LOG_NOTICE -* Mosquitto\Client::LOG_WARNING -* Mosquitto\Client::LOG_ERR - -#### onSubscribe - -Set the subscribe callback. This is called when the broker responds to -a subscription request. - -| Parameter | Type | Description | -| --- | --- | ---- | -| callback | callback | The callback | - -The callback should take parameters of the form: - -| Parameter | Type | Description | -| --- | --- | ---- | -| mid | int | Message ID of the subscribe message | -| qos_count | int | Number of granted subscriptions | - -This function needs to return the granted QoS for each subscription, but -currently cannot. - -#### onUnsubscribe - -Set the unsubscribe callback. This is called when the broker responds to -a unsubscribe request. - -| Parameter | Type | Description | -| --- | --- | ---- | -| callback | callback | The callback | - -The callback should take parameters of the form: - -| Parameter | Type | Description | -| --- | --- | ---- | -| mid | int | Message ID of the unsubscribe message | - -#### onMessage - -Set the message callback. This is called when a message is received from the broker. - -| Parameter | Type | Description | -| --- | --- | ---- | -| callback | callback | The callback | - -The callback should take parameters of the form: - -| Parameter | Type | Description | -| --- | --- | ---- | -| message | Mosquitto\Message | A Message object containing the message data | - - -#### onPublish - -Set the publish callback, This is called when a message is publish by the client itself. - -**Warning**: this may be called before the method `Mosquitto\Client::publish` return the -message id, so, you need to create a queue to deal with the mid list - -| Parameter | Type | Description | -| --- | --- | --- | -| callback | callback | The callback | - -The callback should take parameters of the form: - -| Parameter | Type | Description | -| --- | --- | --- | -| mid | int | the message id returned by `Mosquitto\Client::publish` | - - -#### setMaxInFlightMessages - -Set the number of QoS 1 and 2 messages that can be “in flight” at one time. An -in flight message is part way through its delivery flow. Attempts to send -further messages with publish() will result in the messages being queued until -the number of in flight messages reduces. - -Set to 0 for no maximum. - -| Parameter | Type | Description | -| --- | --- | ---- | -| max_inflight_messages | int | The maximum | - -#### setMessageRetry - -Set the number of seconds to wait before retrying messages. This applies to -publish messages with QoS>0. May be called at any time. - -| Parameter | Type | Description | -| --- | --- | ---- | -| message_retry | int | The retry period | - -#### publish - -Publish a message on a given topic. - -| Parameter | Type | Description | -| --- | --- | ---- | -| topic | string | The topic to publish on | -| payload | string | The message payload | -| qos | int | Integer value 0, 1 or 2 indicating the QoS for this message | -| retain | boolean | If true, make this message retained | - -return `int` the message id in broker system -**Warning** the message id is not unique - -#### subscribe - -Subscribe to a topic. - -| Parameter | Type | Description | -| --- | --- | ---- | -| topic | string | The topic. | -| qos | The QoS to request for this subscription | - -Returns the message ID of the subscription message, so this can be matched up -in the onSubscribe callback. - -#### unsubscribe - -Unsubscribe from a topic. - -| Parameter | Type | Description | -| --- | --- | ---- | -| topic | string | The topic. | -| qos | The QoS to request for this subscription | - -Returns the message ID of the subscription message, so this can be matched up -in the onUnsubscribe callback. - -#### loop - -The main network loop for the client. You must call this frequently in order -to keep communications between the client and broker working. If incoming data -is present it will then be processed. Outgoing commands, from e.g. publish(), -are normally sent immediately that their function is called, but this is not -always possible. loop() will also attempt to send any remaining outgoing -messages, which also includes commands that are part of the flow for messages -with QoS>0. - -| Parameter | Type | Description | -| --- | --- | ---- | -| timeout | int | Optional. Number of milliseconds to wait for network activity. Pass 0 for instant timeout. Defaults to 1000. | -| max_packets | int | Currently unused. | - -#### loopForever - -Call loop() in an infinite blocking loop. Callbacks will be called as required. -This will handle reconnecting if the connection is lost. Call disconnect() in -a callback to return from the loop. - -Note: exceptions thrown in callbacks do not currently cause the loop to exit. To work around this, use loop() and wrap your own loop structure around it such as a while(). - -| Parameter | Type | Description | -| --- | --- | ---- | -| timeout | int | Optional. Number of milliseconds to wait for network activity. Pass 0 for instant timeout. Defaults to 1000. | -| max_packets | int | Currently unused. | - -### Class Mosquitto\Message - -Represents a message received from a broker. All data is represented as -properties. - -| Property | Type | Description | -| --- | --- | --- | -| topic | string | The topic this message was delivered to. | -| payload | string | The payload of this message. | -| mid | int | The ID of this message. | -| qos | int | The QoS value applied to this message. | -| retain | bool | Whether this is a retained message or not. | - -This class has two static methods. - -#### topicMatchesSub - -Returns true if the supplied topic matches the supplied description, and -otherwise false. - -| Parameter | Type | Description | -| --- | --- | ---- | -| topic | string | The topic to match | -| subscription | string | The subscription to match | - -#### tokeniseTopic - -Tokenise a topic or subscription string into an array of strings representing the topic hierarchy. - -| Parameter | Type | Description | -| --- | --- | ---- | -| topic | string | The topic to tokenise | - -### Class Mosquitto\Exception - -This is an exception that may be thrown by many of the operations in the Client -object. +Full documentation is [available on ReadTheDocs](http://mosquitto-php.readthedocs.io/). ## To do From 5ef12f23a0fca8f5e6ec210242a780ad04ed42d1 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:34:39 +0100 Subject: [PATCH 05/12] Add Message and Exception documentation --- docs/exception.rst | 6 ++++++ docs/index.rst | 2 ++ docs/message.rst | 44 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 52 insertions(+) create mode 100644 docs/exception.rst create mode 100644 docs/message.rst diff --git a/docs/exception.rst b/docs/exception.rst new file mode 100644 index 0000000..d4fceb3 --- /dev/null +++ b/docs/exception.rst @@ -0,0 +1,6 @@ +==================== +Mosquitto\\Exception +==================== + +This is an exception that may be thrown by many of the operations in the Client object. It does not add any features to the standard PHP `Exception` class. + diff --git a/docs/index.rst b/docs/index.rst index 16a819b..c439a30 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,8 @@ Contents overview client + message + exception diff --git a/docs/message.rst b/docs/message.rst new file mode 100644 index 0000000..ab30499 --- /dev/null +++ b/docs/message.rst @@ -0,0 +1,44 @@ +================== +Mosquitto\\Message +================== + +.. php:namespace:: Mosquitto + +.. php:class:: Message + + Represents a message received from a broker. All data is represented as properties. + + .. php:attr:: $topic + + (*string*) The topic this message was delivered to. + + .. php:attr:: $payload + + (*string*) The payload of this message. + + .. php:attr:: $mid + + (*int*) The ID of this message. + + .. php:attr:: $qos + + (*int*) The QoS value applied to this message. + + .. php:attr:: $retain + + (*boolean*) Whether this is a retained message or not. + + This class has two static methods. + + .. php:staticmethod:: topicMatchesSub() + + Returns true if the supplied topic matches the supplied description, and otherwise false. + + :param string $topic: The topic to match + :param string $subscription: The subscription to match + + .. php:staticmethod:: tokeniseTopic() + + Tokenise a topic or subscription string into an array of strings representing the topic hierarchy. + + :param string $topic: The topic to tokenise From 191ab85a83cc06aed6fbfc3af875be256d8562e2 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:35:17 +0100 Subject: [PATCH 06/12] Update Exception docs --- docs/exception.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/exception.rst b/docs/exception.rst index d4fceb3..f90def6 100644 --- a/docs/exception.rst +++ b/docs/exception.rst @@ -2,5 +2,9 @@ Mosquitto\\Exception ==================== -This is an exception that may be thrown by many of the operations in the Client object. It does not add any features to the standard PHP `Exception` class. +.. php:namespace:: Mosquitto + +.. php:class:: Exception + +This is an exception that may be thrown by many of the operations in the ``Client`` object. It does not add any features to the standard PHP ``Exception`` class. From 9c84e055f9289877356aaeda1caa6b8f6db61c7a Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:41:03 +0100 Subject: [PATCH 07/12] Remove obsolete TODO section --- README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.md b/README.md index f2a0e02..2199083 100644 --- a/README.md +++ b/README.md @@ -65,9 +65,3 @@ echo "Finished\n"; Full documentation is [available on ReadTheDocs](http://mosquitto-php.readthedocs.io/). -## To do - -* Arginfo -* Logging callbacks -* TLS support -* Tests From 7c99326270f41d98ab0ccfbcadc9b56a512b9545 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:41:21 +0100 Subject: [PATCH 08/12] Add a quick one-liner intro --- docs/index.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index c439a30..234cb44 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,10 @@ Mosquitto-PHP ============= +This is an extension to allow using the `Eclipse Mosquitto™ MQTT client library `_ with PHP. + +See the ``examples`` directory for usage. + Contents ======== From afe16577e05731378ff72cd188beaf7b34232d59 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:43:05 +0100 Subject: [PATCH 09/12] We're on PHP 7 --- docs/overview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.rst b/docs/overview.rst index 3c1c482..ee93db4 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -5,7 +5,7 @@ Overview Requirements ============ -* PHP 5.3 or newer +* PHP 5.3 or newer, including PHP 7+ * libmosquitto 1.2.x or later Installation From c8e3b9b971c095ce6c09377fb7bc35e727419cb4 Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Mon, 5 Sep 2016 23:44:51 +0100 Subject: [PATCH 10/12] Update CREDITS --- CREDITS | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CREDITS b/CREDITS index 28c0986..f1f69f2 100644 --- a/CREDITS +++ b/CREDITS @@ -1,4 +1,6 @@ -libmosquitto PHP binding -Michael Maclean +# Mosquitto-PHP + +Original implementation by Michael Maclean onPublish callback from Github user @acrazing +PHP 7 support by Sara Golemon From 77cef107e3ed28f6ae31dc6c0af22de6afbf2aba Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Tue, 6 Sep 2016 20:56:29 +0100 Subject: [PATCH 11/12] Add cross-references --- docs/client.rst | 113 ++++++++++++++++++++++++------------------------ 1 file changed, 57 insertions(+), 56 deletions(-) diff --git a/docs/client.rst b/docs/client.rst index 74f54ae..9894521 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -13,71 +13,71 @@ Mosquitto\\Client Construct a new Client instance. :param string $id: The client ID. If omitted or ``null``, one will be generated at random. - :param boolean $cleanSession: Set to ``true`` to instruct the broker to clean all messages and subscriptions on disconnect. Must be true if the ``$id`` parameter is ``null``. + :param boolean $cleanSession: Set to ``true`` to instruct the broker to clean all messages and subscriptions on disconnect. Must be ``true`` if the ``$id`` parameter is ``null``. .. php:method:: setCredentials($username, $password) - Set the username and password to use on connecting to the broker. Must be called before ``connect()``. + Set the username and password to use on connecting to the broker. Must be called before :php:meth:`~Client::connect`. :param string $username: Username to supply to the broker :param string $password: Password to supply to the broker - .. php:method:: setTlsCertificates($caPath, $certFile, $keyFile, $password) + .. php:method:: setTlsCertificates($caPath[, $certFile, $keyFile, $password]) - Configure the client for certificate based SSL/TLS support. Must be called before connect(). Cannot be used in conjunction with setTlsPSK(). + Configure the client for certificate based SSL/TLS support. Must be called before :php:meth:`~Client::connect`. Cannot be used in conjunction with :php:meth:`~Client::setTlsPSK`. - Define the Certificate Authority certificates to be trusted (ie. the server certificate must be signed with one of these certificates) using cafile. If the server you are connecting to requires clients to provide a certificate, define certfile and keyfile with your client certificate and private key. If your private key is encrypted, provide the password as the fourth parameter, or you will have to enter the password at the command line. + Define the Certificate Authority certificates to be trusted (ie. the server certificate must be signed with one of these certificates) using ``$caFile``. If the server you are connecting to requires clients to provide a certificate, define ``$certFile`` and ``$keyFile`` with your client certificate and private key. If your private key is encrypted, provide the password as the fourth parameter. - :param string $username: Path to the PEM encoded trusted CA certificate files, or to a directory containing them. + :param string $caPath: Path to the PEM encoded trusted CA certificate files, or to a directory containing them. :param string $certFile: Path to the PEM encoded certificate file for this client. Optional. :param string $keyFile: Path to a file containing the PEM encoded private key for this client. Required if certfile is set. :param string $password: The password for the keyfile, if it is encrypted. If null, the password will be asked for on the command line. .. php:method:: setTlsInsecure($value) - Configure verification of the server hostname in the server certificate. If value is set to true, it is impossible to guarantee that the host you are connecting to is not impersonating your server. Do not use this function in a real system. Must be called before connect(). + Configure verification of the server hostname in the server certificate. If ``$value`` is ``true``, it is impossible to guarantee that the host you are connecting to is not impersonating your server. Do not use this function in a real system. Must be called before :php:meth:`~Client::connect`. - :param boolean $value: If set to false, the default, certificate hostname checking is performed. If set to true, no hostname checking is performed and the connection is insecure. + :param boolean $value: If set to false, the default, certificate hostname checking is performed. If set to ``true``, no hostname checking is performed and the connection is insecure. .. php:method:: setTlsOptions($certReqs, $tlsVersion, $ciphers) - Set advanced SSL/TLS options. Must be called before ``connect()``. + Set advanced SSL/TLS options. Must be called before :php:meth:`~Client::connect`. :param int $certReqs: Whether or not to verify the server. Can be ``Mosquitto\\Client::SSL_VERIFY_NONE``, to disable certificate verification, or ``Mosquitto\Client::SSL_VERIFY_PEER`` (the default), to verify the server certificate. - :param string $tlsVersion: The TLS version to use. If ``null``, a default is used. The default value depends on the version of OpenSSL the library was compiled against. Available options on OpenSSL >= 1.0.1 are 'tlsv1.2', 'tlsv1.1' and 'tlsv1'. + :param string $tlsVersion: The TLS version to use. If ``null``, a default is used. The default value depends on the version of OpenSSL the library was compiled against. Available options on OpenSSL >= 1.0.1 are ``tlsv1.2``, ``tlsv1.1`` and ``tlsv1``. :param string $cipers: A string describing the ciphers available for use. See the ``openssl ciphers`` tool for more information. If ``null``, the default set will be used. - .. php:method:: setTlsPSK() + .. php:method:: setTlsPSK($psk, $identity[, $ciphers]) - Configure the client for pre-shared-key based TLS support. Must be called before connect(). Cannot be used in conjunction with setTlsCertificates. + Configure the client for pre-shared-key based TLS support. Must be called before :php:meth:`~Client::connect`. Cannot be used in conjunction with setTlsCertificates. :param string $psk: The pre-shared key in hex format with no leading "0x". :param string $identity: The identity of this client. May be used as the username depending on server settings. :param string $cipers: Optional. A string describing the ciphers available for use. See the ``openssl ciphers`` tool for more information. If ``null``, the default set will be used. - .. php:method:: setWill() + .. php:method:: setWill($topic, $payload[, $qos = 0, $retain = false]) - Set the client "last will and testament", which will be sent on an unclean disconnection from the broker. Must be called before connect(). + Set the client "last will and testament", which will be sent on an unclean disconnection from the broker. Must be called before :php:meth:`~Client::connect`. :param string $topic: The topic on which to publish the will. :param string $payload: The data to send. :param int $qos: Optional. Default 0. Integer 0, 1, or 2 indicating the Quality of Service to be used. - :param boolean $retain: Optional. Default false. If true, the message will be retained. + :param boolean $retain: Optional. Default false. If ``true``, the message will be retained. .. php:method:: clearWill() Remove a previously-set will. No parameters. - .. php:method:: setReconnectDelay() + .. php:method:: setReconnectDelay($reconnectDelay, $exponentialDelay, $exponentialBackoff = false) - Control the behaviour of the client when it has unexpectedly disconnected in loopForever. The default behaviour if this method is not used is to repeatedly attempt to reconnect with a delay of 1 second until the connection succeeds. + Control the behaviour of the client when it has unexpectedly disconnected in :php:meth:`Client::loopForever`. The default behaviour if this method is not used is to repeatedly attempt to reconnect with a delay of 1 second until the connection succeeds. - :param int $reconnect_delay: Set delay between successive reconnection attempts. - :param int $reconnect_delay: Set max delay between successive reconnection attempts when exponential backoff is enabled - :param bool $exponential_backoff: Enable exponential backoff + :param int $reconnectDelay: Set delay between successive reconnection attempts. + :param int $exponentialDelay: Set max delay between successive reconnection attempts when exponential backoff is enabled + :param bool $exponentialBackoff: Pass ``true`` to enable exponential backoff - .. php:method:: connect() + .. php:method:: connect($host[, $port = 1883, $keepalive = 60, $interface = null]) Connect to an MQTT broker. @@ -90,11 +90,11 @@ Mosquitto\\Client Disconnect from the broker. No parameters. - .. php:method:: onConnect() + .. php:method:: onConnect($callback) Set the connect callback. This is called when the broker sends a CONNACK message in response to a connection. - :param callback $callback: The callback + :param callable $callback: The callback The callback should take parameters of the form: @@ -113,21 +113,21 @@ Mosquitto\\Client 4-255 Reserved for future use ===== ==== - .. php:method:: onDisconnect() + .. php:method:: onDisconnect($callback) Set the disconnect callback. This is called when the broker has received the DISCONNECT command and has disconnected the client. - :param callback $callback: The callback + :param callable $callback: The callback The callback should take parameters of the form: :param int $rc: Reason for the disconnection. 0 means the client requested it. Any other value indicates an unexpected disconnection. - .. php:method:: onLog() + .. php:method:: onLog($callback) Set the logging callback. - :param callback $callback: The callback + :param callable $callback: The callback The callback should take parameters of the form: @@ -142,54 +142,54 @@ Mosquitto\\Client * ``Mosquitto\Client::LOG_WARNING`` * ``Mosquitto\Client::LOG_ERR`` - .. php:method:: onSubscribe() + .. php:method:: onSubscribe($callback) Set the subscribe callback. This is called when the broker responds to a subscription request. - :param callback $callback: The callback + :param callable $callback: The callback The callback should take parameters of the form: :param int $mid: Message ID of the subscribe message - :param int $qos_count: Number of granted subscriptions + :param int $qosCount: Number of granted subscriptions This function needs to return the granted QoS for each subscription, but currently cannot. - .. php:method:: onUnsubscribe() + .. php:method:: onUnsubscribe($callback) Set the unsubscribe callback. This is called when the broker responds to a unsubscribe request. - :param callback $callback: The callback + :param callable $callback: The callback The callback should take parameters of the form: :param int $mid: Message ID of the unsubscribe message - .. php:method:: onMessage() + .. php:method:: onMessage($callback) Set the message callback. This is called when a message is received from the broker. - :param callback $callback: The callback + :param callable $callback: The callback The callback should take parameters of the form: - :param Mosquitto\Message $message: A Message object containing the message data + :param :php:class:`Message` $message: A :php:class:`Message` object containing the message data - .. php:method:: onPublish() + .. php:method:: onPublish($callback) Set the publish callback. This is called when a message is published by the client itself. - **Warning**: this may be called before the method ``Mosquitto\Client::publish()`` returns the message id, so, you need to create a queue to deal with the MID list. + **Warning**: this may be called before the method :php:meth:`~Client::publish` returns the message id, so, you need to create a queue to deal with the MID list. - :param callback $callback: The callback + :param callable $callback: The callback The callback should take parameters of the form: - :param int $mid: the message id returned by ``Mosquitto\Client::publish()`` + :param int $mid: the message id returned by :php:meth:`~Client::publish` - .. php:method:: setMaxInFlightMessages() + .. php:method:: setMaxInFlightMessages($maxInFlightMessages) - Set the number of QoS 1 and 2 messages that can be “in flight” at one time. An in flight message is part way through its delivery flow. Attempts to send further messages with publish() will result in the messages being queued until the number of in flight messages reduces. + Set the number of QoS 1 and 2 messages that can be “in flight” at one time. An in flight message is part way through its delivery flow. Attempts to send further messages with :php:meth:`~Client::publish` will result in the messages being queued until the number of in flight messages reduces. Set to 0 for no maximum. @@ -197,29 +197,30 @@ Mosquitto\\Client .. php:method:: setMessageRetry($messageRetryPeriod) - Set the number of seconds to wait before retrying messages. This applies to publish messages with QoS>0. May be called at any time. + Set the number of seconds to wait before retrying messages. This applies to publishing messages with QoS>0. May be called at any time. :param int $messageRetryPeriod: The retry period - .. php:method:: publish($topic, $payload, $qos = 0, $retain = false) + .. php:method:: publish($topic, $payload[, $qos = 0, $retain = false]) Publish a message on a given topic. :param string $topic: The topic to publish on :param string $payload: The message payload :param int $qos: Integer value 0, 1 or 2 indicating the QoS for this message - :param boolean $retain: If true, make this message retained - :returntype: int + :param boolean $retain: If ``true``, retain this message :returns: The message ID returned by the broker. **Warning**: the message ID is not unique. + :returntype: int - .. php:method:: subscribe() + .. php:method:: subscribe($topic, $qos) Subscribe to a topic. :param string $topic: The topic. :param int $qos: The QoS to request for this subscription - Returns the message ID of the subscription message, so this can be matched up in the onSubscribe callback. + :returns: The message ID of the subscription message, so this can be matched up in the :php:meth:`~Client::onSubscribe` callback. + :returntype: int .. php:method:: unsubscribe() @@ -228,21 +229,21 @@ Mosquitto\\Client :param string $topic: The topic. :param int $qos: The QoS to request for this subscription - Returns the message ID of the subscription message, so this can be matched up in the onUnsubscribe callback. + :returns: the message ID of the subscription message, so this can be matched up in the :php:meth:`~Client::onUnsubscribe` callback. + :returntype: int - .. php:method:: loop() + .. php:method:: loop([$timeout = 1000]) - The main network loop for the client. You must call this frequently in order to keep communications between the client and broker working. If incoming data is present it will then be processed. Outgoing commands, from e.g. publish(), are normally sent immediately that their function is called, but this is not always possible. loop() will also attempt to send any remaining outgoing messages, which also includes commands that are part of the flow for messages with QoS>0. + The main network loop for the client. You must call this frequently in order to keep communications between the client and broker working. If incoming data is present it will then be processed. Outgoing commands, from e.g. :php:meth:`~Client::publish`, are normally sent immediately that their function is called, but this is not always possible. :php:meth:`~Client::loop` will also attempt to send any remaining outgoing messages, which also includes commands that are part of the flow for messages with QoS>0. :param int $timeout: Optional. Number of milliseconds to wait for network activity. Pass 0 for instant timeout. Defaults to 1000. - :param int $max_packets: Currently unused. - - .. php:method:: loopForever() - Call loop() in an infinite blocking loop. Callbacks will be called as required. This will handle reconnecting if the connection is lost. Call disconnect() in a callback to return from the loop. + .. php:method:: loopForever([$timeout = 1000]) - Note: exceptions thrown in callbacks do not currently cause the loop to exit. To work around this, use loop() and wrap your own loop structure around it such as a while(). + Call loop() in an infinite blocking loop. Callbacks will be called as required. This will handle reconnecting if the connection is lost. Call :php:meth:`~Client::disconnect` in a callback to disconnect and return from the loop. Alternatively, call :php:meth:`~Client::exitLoop` to exit the loop without disconnecting. You will need to re-enter the loop again afterwards to maintain the connection. :param int $timeout: Optional. Number of milliseconds to wait for network activity. Pass 0 for instant timeout. Defaults to 1000. - :param int $max_packets: Currently unused. + .. php:method:: exitLoop() + + Exit the :php:meth:`~Client::loopForever` event loop without disconnecting. You will need to re-enter the loop afterwards in order to maintain the connection. From 18c5cb6156fe03eb17c4705063d5f1d698cd797c Mon Sep 17 00:00:00 2001 From: Michael Maclean Date: Tue, 6 Sep 2016 21:12:07 +0100 Subject: [PATCH 12/12] Document constants --- docs/client.rst | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/docs/client.rst b/docs/client.rst index 9894521..ead299b 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -8,6 +8,34 @@ Mosquitto\\Client This is the main Mosquitto client. + .. php:const:: LOG_DEBUG + + Identifies a debug-level log message + + .. php:const:: LOG_INFO + + Identifies an info-level log message + + .. php:const:: LOG_NOTICE + + Identifies a notice-level log message + + .. php:const:: LOG_WARNING + + Identifies a warning-level log message + + .. php:const:: LOG_ERR + + Identifies an error-level log message + + .. php:const:: SSL_VERIFY_NONE + + Used with :php:meth:`~Client::setTlsInsecure`. Do not verify the identity of the server, thus making the connection insecure. + + .. php:const:: SSL_VERIFY_PEER + + Used with :php:meth:`~Client::setTlsInsecure`. Verify the identity of the server. + .. php:method:: __construct([$id = null, $cleanSession = true]) Construct a new Client instance. @@ -69,7 +97,7 @@ Mosquitto\\Client Remove a previously-set will. No parameters. - .. php:method:: setReconnectDelay($reconnectDelay, $exponentialDelay, $exponentialBackoff = false) + .. php:method:: setReconnectDelay($reconnectDelay, $exponentialDelay, $exponentialBackoff) Control the behaviour of the client when it has unexpectedly disconnected in :php:meth:`Client::loopForever`. The default behaviour if this method is not used is to repeatedly attempt to reconnect with a delay of 1 second until the connection succeeds. @@ -136,11 +164,11 @@ Mosquitto\\Client The level can be one of: - * ``Mosquitto\Client::LOG_DEBUG`` - * ``Mosquitto\Client::LOG_INFO`` - * ``Mosquitto\Client::LOG_NOTICE`` - * ``Mosquitto\Client::LOG_WARNING`` - * ``Mosquitto\Client::LOG_ERR`` + * :php:const:`Client::LOG_DEBUG` + * :php:const:`Client::LOG_INFO` + * :php:const:`Client::LOG_NOTICE` + * :php:const:`Client::LOG_WARNING` + * :php:const:`Client::LOG_ERR` .. php:method:: onSubscribe($callback)