PEAR2_Net_RouterOS-1.0.0b2 › PEAR2_Net_RouterOS-1.0.0b2/docs/tutorials/PEAR2_Net_RouterOS/Query.cls

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
<?xml version="1.0"?>
<refentry id="{@id}">
    <refnamediv>
        <refname>Using queries</refname>
        <refpurpose>A brief guide to using queries</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <author>Vasil Rangelov
            <authorblurb>
                {@link mailto:boen.robot@gmail.com boen.robot@gmail.com}
            </authorblurb>
        </author>
    </refsynopsisdiv>
    {@toc}
    <refsect1 id="{@id command-handling-queries}">
        <title>Commands handling queries</title>
        <para>
Queries are a RouterOS API specific construct that allows you to limit the results returned for a request.
        </para>
        <para>
Currently, the "print" command is the only one that handles queries, since version 3.21. PEAR2_Net_RouterOS doesn't check whether the command handles queries, so if future versions of RouterOS have other such commands, you can use queries with them right away.
        </para>
    </refsect1>
    <refsect1 id="{@id setting-query}">
        <title>Setting a query</title>
        <para>
To set a query for a request, you need to use the {@link Request::setQuery()} method. If later in the script you want to remove the query, you can pass NULL to it. The rest of the examples in this tutorial will assume a script similar to the following, where the $query variable is defined separately:
        </para>
        <programlisting role="php">
&lt;?php
namespace PEAR2\Net\RouterOS;
include_once 'PEAR2/Net/RouterOS/autoload.php';
$client = new Client('192.168.0.1', 'admin');

$request = new Request('/ip/arp/print');

//Define $query here

$request->setQuery($query);
$responses = $client->sendSync($request);

foreach($responses as $response) {
    foreach($response->getAllArguments() as $name => $value) {
        echo "{$name}: {$value}\n";
    }
    echo "====\n";
}
?&gt;
        </programlisting>
    </refsect1>
    <refsect1 id="{@id simple-query}">
        <title>A simple query</title>
        <para>
You can create a query by calling the static {@link Query::where()} method, along with the first criteria of the query. For example, if you wanted to limit results to the entry about 192.168.0.100, you can use a query like:
        </para>
        <programlisting role="php">$query = Query::where('address', '192.168.0.100');</programlisting>
        <para>
Using the optional third parameter, you can specify exactly what do you want to do with the value. Possible values are the <emphasis>Query::ACTION_*</emphasis> constants. For example, if you wanted to get all addresses greather than 192.168.0.100, you can use:
        </para>
        <programlisting role="php">$query = Query::where('address', '192.168.0.100', Query::ACTION_GREATHER_THAN);</programlisting>
    </refsect1>
    <refsect1 id="{@id chaining-conditions}">
        <title>Chaining conditions</title>
        <para>
The {@link Query} class uses a "fluent" interface, i.e. it always returns the query object itself, similarly to how {@link http://jquery.com jQuery} and {@link http://framework.zend.com/manual/en/zend.db.select.html Zend_Db_Select} do it. Thanks to that, you can chain conditions right when defining the $query variable (though you can also alter it later). For example, if you wanted to get all addresses greather than or equal to 192.168.0.100, you can do:
        </para>
        <programlisting role="php">$query = Query::where('address', '192.168.0.100', Query::ACTION_GREATHER_THAN)->orWhere('address', '192.168.0.100');</programlisting>
    </refsect1>
    <refsect1 id="{@id limiting-returned-properties}">
        <title>Limiting returned properties</title>

        <para>The query works a little like the "WHERE" clause in an SQL statement - it limits the amount of responses returned (which can be thought of as a "record" in DB terms) - but it doesn't limit the arguments of each response (which can be thought of as "fields" in DB terms, and are often reffered to as "properties" in the RouterOS documentation).</para>

        <para>To do that, you need to set an API specific argument called ".proplist". The value is a comma separated list of arguments to be listed in the responses. For example, if you were only interested in the MAC addresses, you can do:</para>
 
        <programlisting role="php">$request->setArgument('.proplist', 'mac-address');</programlisting>
        <para>or if you wanted MAC addresses and comments</para>
        <programlisting role="php">$request->setArgument('.proplist', 'mac-address,comment');</programlisting>
    </refsect1>
</refentry>
EOF