PEAR2_Net_RouterOS-1.0.0b3PEAR2_Net_RouterOS-1.0.0b3/docs/tutorials/PEAR2_Net_RouterOS/PEAR2_Net_RouterOS.pkg

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
<?xml version="1.0"?>
<refentry id="{@id}">
    <refnamediv>
        <refname>Getting started</refname>
        <refpurpose>First steps in using PEAR2_Net_RouterOS</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <author>Vasil Rangelov
            <authorblurb>
                {@link mailto:boen.robot@gmail.com boen.robot@gmail.com}
            </authorblurb>
        </author>
    </refsynopsisdiv>
    {@toc}
    <refsect1 id="{@id intro}">
        <title>Introduction</title>
        <para>
RouterOS is the flag product of the company {@link http://mikrotik.com/ MikroTik}
and is a powerful router software. One of its many abilities is to allow control over it via an API.
This package provides a client for {@link http://wiki.mikrotik.com/wiki/Manual:API that API}, in turn allowing you to use PHP to control RouterOS hosts.
        </para>
    </refsect1>
    <refsect1 id="{@id requirements}">
        <title>Requirements</title>
        <itemizedlist>
            <listitem>PHP 5.3.0 or later.</listitem>
            <listitem>A host with RouterOS v3 or later.</listitem>
            <listitem>Enabled API service on the RouterOS host.</listitem>
            <listitem>The PCRE extension (bundled and enabled by default in PHP).</listitem>
            <listitem>The iconv extension (optional; bundled and enabled by default in PHP; required only if you want to use automatic charset convertion)</listitem>
            <listitem>PEAR2_Net_Transmitter (bundled with the PEAR2_Net_RouterOS archive; installed automatically by Pyrus)</listitem>
        </itemizedlist>
        <para>
The API service is disabled by default. To enable it, you need to execute
<programlisting role="sh">/ip service set numbers="api" address="0.0.0.0/0" disabled="no"</programlisting>
at a RouterOS terminal. The "address" argument in the command above allows you to limit access to this service only to certain IP addresses. For security's sake, it's better that you limit connections only to the IP address with which PHP will access RouterOS.
        </para>
    </refsect1>
    <refsect1 id="{@id install}">
        <title>Installation</title>
        <refsect2 id="{@id pyrus-install}">
            <title>Installation with {@link http://pear2.php.net Pyrus/PEAR2}</title>

            <para>Assuming you have {@link http://pear.php.net/manual/en/installationpyrus.introduction.php installed Pyrus}, you can install PEAR2_Net_RouterOS from the PEAR2 channel with</para>
            <programlisting role="sh">pyrus install PEAR2_Net_RouterOS-alpha</programlisting>
 
            <para>You might notice that the version number of PEAR2_Net_RouterOS suggests it's a beta, and yet we use "-alpha" in the command above. Well, yes, PEAR2_Net_RouterOS is a beta, but it has a dependency to another package - PEAR2_Net_Transmitter - which is an alpha. To avoid getting errors, you need to use "-alpha" until that package reaches a beta.</para>

            <para>If you've decided to not use the PEAR2 channel, but instead install directly from the archive distributed at the project page, you can use</para>
            <programlisting role="sh">pyrus install /path/to/downloaded/archive.tgz</programlisting>
            <para>If you haven't installed PEAR_Net_Transmitter previously, Pyrus will install the one at the PEAR2 channel (not the bundled version, although the two are equivalent at the time of this writing).</para>
        </refsect2>
        <refsect2 id="{@id pear-install}">
            <title>Installation with PEAR.</title>
            <para>Like most PEAR2 packages, PEAR2_Net_RouterOS is compatible with the PEAR installer. However, you have to first discover the PEAR2 channel with</para>
            <programlisting role="sh">pear channel-discover pear2.php.net</programlisting>
            <para>and only then install PEAR2_Net_RouterOS with</para> 
            <programlisting role="sh">pear install pear2/PEAR2_Net_RouterOS-alpha</programlisting>
        </refsect2>
        <refsect2 id="{@id manual-install}">
            <title>Manual installation.</title>
            <para>The archive includes a version of PEAR2_Net_Transmitter, so if you've downloaded the archive, instead of using the PEAR(2) installer, you can just extract the contents of the "src" folder wherever you like. To emulate the PEAR(2) installer, you can place the files in a folder that's within your include_path.</para>

            <para>If you're installing from the respository, you'll have to also install PEAR2_Net_Transmitter in one way or another before you can use this package.</para>
        </refsect2>
    </refsect1>
    <refsect1 id="{@id usage}">
        <title>Usage.</title>
        <para>
To use this in a PHP file, you could manally include every required class, but to save yourself some hassle, it's a better idea that you just include the file Autoload.php, like:
        </para>
        <programlisting role="php">
&lt;?php
include_once 'PEAR2/Net/RouterOS/Autoload.php';
//Use any Net_RouterOS class
?&gt;
        </programlisting>
        <para>
Net_RouterOS uses namespaces - a feature introduced in PHP 5.3 - for its organization.
Among other things, this means that instead of you having to write long class names, you can just declare at the top that you'll be using this namespace, and then just write shorter class names. The possible approaches are as follows:</para>
        <itemizedlist>
            <listitem>
Using a fully qualified class name
                <programlisting role="php">
&lt;?php
include_once 'PEAR2/Net/RouterOS/Autoload.php';
$client = new PEAR2\Net\RouterOS\Client('example.com', 'admin');
// Use the client here
?&gt;
                </programlisting>
            </listitem>
            <listitem>
Declaring the \PEAR2\Net\RouterOS as your default namespace
                <programlisting role="php">
&lt;?php
namespace PEAR2\Net\RouterOS;
include_once 'PEAR2/Net/RouterOS/Autoload.php';
$client = new Client('example.com', 'admin');
// Use the client here
?&gt;
                </programlisting>
            </listitem>
            <listitem>
Declaring the PEAR2\Net\RouterOS as an aliased namespace
                <programlisting role="php">
&lt;?php
use PEAR2\Net\RouterOS as Ros;
include_once 'PEAR2/Net/RouterOS/Autoload.php';
$client = new Ros\Client('example.com', 'admin');
// Use the client here
?&gt;
                </programlisting>
            </listitem>
            <listitem>
Declaring an alias of each class you intend to use directly.
                <programlisting role="php">
&lt;?php
use PEAR2\Net\RouterOS\Client as Ros;
include_once 'PEAR2/Net/RouterOS/Autoload.php';
$client = new Ros('example.com', 'admin');
// Use the client here
?&gt;
                </programlisting>
            </listitem>
        </itemizedlist>
        <para>
Note that namespace declarations must appear before any includes.
They must in fact be the first thing in a PHP file. The rest of the examples in this documentation will be setting \PEAR2\Net\RouterOS as the default namespace.
        </para>
    </refsect1>
    <refsect1 id="{@id further-info}">
        <title>Further information.</title>
        <para>
Net_RouterOS is flexible in the code patterns it allows you to use, but using the
{@link Client} class with {@link Client::sendSync()} is the reccomended approach for simple scenarios. See {@tutorial Client.cls the tutorial for the Client class} for description of this and other ways to use PEAR2_Net_RouterOS.
        </para>
    </refsect1>
</refentry>
EOF