• Installing/Configuring
  • Installation

  • Installation
  • Installation


    Information for installing this PECL extension may
    be found in the manual chapter titled Installation of PECL extensions. Additional
    information such as new releases, downloads, source files,
    maintainer information, and a CHANGELOG, can be located here:

    The SAM framework and MQTT support can be built and
    used without any other prerequisites. Support for protocols other
    than MQTT is provided via a set of libraries and some client side
    code referred to as XMS.

    If you only intend to use the built-in MQTT support
    then you can build and configure SAM as an extension or simply
    refer to php_sam.php with a
    require or require_once clause in your PHP script. In
    this case you need only install the code without building the
    extension using the pear installer:

    pecl install -B SAM

    Linux installation steps

    The sam extension is supplied as a PECL module,
    which you should be able to download and install in one step as

    pecl install sam

    (Depending on your php environment, you will probably need to be
    root to do this.)

    Make sure that the module is loaded by PHP, by
    adding following line to php.ini:

    If you intend to use the XMS support to access the IBM Messaging
    and Queuing family you must also enable the SAM XMS extension.

    If you cannot use the PEAR installer, you can
    download the extension and build it manually:

    pear download sam          #downloads sam-<version>.tgz
    tar -xzf sam-<version>.tgz
    cd sam-<version>
    make install               #you may need to be root for this step

    To work with the very latest source, you’ll need to
    extract it from SVN and build manually as above.

    Windows installation steps

    You will probably need to build the sam extension
    for Windows as there are only a limited range of pre-built binaries
    available from the SAM website. The extension can be built using
    the standard Windows extension build procedures.

    You will need the PHP source tree for the version
    of PHP you wish to build the SAM extension against which you can
    obtain from This should be unpacked into a working
    directory of your choice.

    You will also need the libraries and headers used
    by PHP extensions available from and this should be unzipped
    so that is in your working directory.

    You should have something like:

                  |              |---ext
                  |              |--- ...

    You will need a compiler such as the free version
    of Visual Studio C++ Express from the Microsoft web site. Also you
    need the Microsoft SDK Microsoft Windows Platform which
    again can be downloaded from the Microsoft web site.

    Obtain the SAM extension source using pear (pecl
    download sam) or by using SVN and copy the files to a new “sam”
    directory under the “ext” directory in your PHP source tree.

    To build the extension open a build environment
    window by going to the start

    programs->microsoft platform SDK for windows->
    open build environment window->windows 200 build
    set windows 2000 build environment (retail)

    This should open a command prompt with all the
    environment variables set up to access the platform SDK etc. You
    then need to set the environment variables for Visual Studio by
    issuing the command vcvars32.bat
    in the window.

    Change directory to your working directory e.g. cd
    c:\php-build. Then make sure the
    win32build tools are accessible by adding them to the PATH environment variable:

    set PATH=..\win32build\bin;%PATH%

    Run the buildconf.bat command. This should rebuild the
    configure.js file.

    Run the cscript
    command with the appropriate options. To build just the SAM
    extension framework and MQTT support use:

    cscript /nologo configure.js --with-sam

    To build the SAM framework and the XMS support use:

    cscript /nologo configure.js --with-sam --with-sam_xms="c:\program files\ibm\xms"

    The additional parameter passed for sam_xms is the
    installation path to the XMS libraries and runtime that were
    installed as described under prerequisites at the top of this

    You can specify whatever other cscript parameters you require to include or
    exclude items from the php build or select options.

    Assuming all has gone well so far you can now
    finally run a make for the SAM framework!

    nmake php_sam.dll

    Also if you are using the XMS support you must make the sam_xms

    nmake php_sam_xms.dll

    If you have used Visual Studio 2005 to build the
    DLLs please see below for additional steps that must be carried out
    before proceeding further.

    The DLLs created (php_sam.dll and optionally php_sam_xms.dll) can now be copied to the
    subdirectory appropriate for your PHP set-up. Make sure that the
    module(s) are loaded by PHP, by adding following line to


    If you intend to use the XMS support to access the IBM Messaging
    and Queuing family you must also enable the SAM XMS extension.


    Additional steps for Visual Studio 2005

    If you build the SAM extension with the Microsoft
    Visual Studio 2005 compiler and tools you need to perform an
    additional step in the build process to ensure the php_sam.dll is able to link with the C runtime
    libraries at runtime. This step includes the dependancy manifest
    into the DLL. Switch to the directory where the php_sam.dll has been generated (usually Release_TS
    or Debug_TS below the php source directory) and issue the following
    magic incantation:

    mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2

    If you are using the XMS capabilities you will need to do the same
    with the SAM XMS DLL:

    mt.exe -manifest php_sam_xms.dll.manifest -outputresource:php_sam_xms.dll;2

    If you build the SAM extension using the compiler
    and libraries from Microsoft Visual Studio 2005 you will also need
    to ensure that the runtime components are installed on the system
    on which you intend to use SAM. This can be accomplished by
    installing Visual Studio 2005 or by using the freely distributable
    » runtime package.