diff --git a/README b/README index 95ac40b..020eec4 100644 --- a/README +++ b/README @@ -1,2 +1,2 @@ RouterOS API client implementation. -This package allows you to read and write information from a RouterOS host using MikroTik's RouterOS API. \ No newline at end of file +RouterOS is the flag product of the company 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 that API, in turn allowing you to use PHP to control RouterOS hosts. \ No newline at end of file diff --git a/docs/tutorials/PEAR2_Net_RouterOS/PEAR2_Net_RouterOS.pkg b/docs/tutorials/PEAR2_Net_RouterOS/PEAR2_Net_RouterOS.pkg index 475599e..fdbb132 100644 --- a/docs/tutorials/PEAR2_Net_RouterOS/PEAR2_Net_RouterOS.pkg +++ b/docs/tutorials/PEAR2_Net_RouterOS/PEAR2_Net_RouterOS.pkg @@ -17,7 +17,7 @@ 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 that API, in turn allowing you to use PHP to control RouterOS hosts. +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. @@ -26,39 +26,42 @@ This package provides a client for that API, in turn allowing you to use PHP to PHP 5.3.0 or later. A host with RouterOS v3 or later. Enabled API service on the RouterOS host. + The PCRE extension (bundled and enabled by default in PHP). + The iconv extension (optional; bundled and enabled by default in PHP; required only if you want to use automatic charset convertion) + PEAR2_Net_Transmitter (bundled with the PEAR2_Net_RouterOS archive; installed automatically by Pyrus) -There are no dependencies from extensions that are not bundled with PHP. -The only dependency is the PCRE (Pearl Compatible Regular Expressions) extension, which is bundled and enabled by default in PHP. - - The API service is disabled by default. To enable it, you need to execute -/ip service set numbers="api" address="0.0.0.0/0" disabled="no" +/ip service set numbers="api" address="0.0.0.0/0" disabled="no" 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. Installation + + Installation with {@link http://pear2.php.net Pyrus/PEAR2} + + 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 + pyrus install PEAR2_Net_RouterOS-alpha + + 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. + + 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 + pyrus install /path/to/downloaded/archive.tgz + 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). + - Installation with the PEAR installer. - -If you don't already have the pear installer, see the -{@link http://pear.php.net/manual/en/installation.php installation instructions in the PEAR manual}. The version of the PEAR installer that is bundled with PHP 5.3.0 should be sufficient. - - -To use the PEAR installer, you must have the TGZ version of the file. -Installation is as easy as opening up a command prompt, going to the pear installer's folder and typing - pear install "%tgz%" -Replacing %tgz% with the location of the archive. - + Installation with PEAR. + Like most PEAR2 packages, PEAR2_Net_RouterOS is compatible with the PEAR installer. However, you have to first discover the PEAR2 channel with + pear channel-discover pear2.php.net + and only then install PEAR2_Net_RouterOS with + pear install pear2/PEAR2_Net_RouterOS-alpha Manual installation. - -Instead of using the PEAR installer, you can also just extract the files into any directory in your include_path. -To emulate the PEAR installer, you can simply extract the contents of the folder "src" in that folder. -Note that the examples in the rest of the documentation assume installation with the PEAR installer. - + 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. + + 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. diff --git a/docs/tutorials/PEAR2_Net_RouterOS/Query.cls b/docs/tutorials/PEAR2_Net_RouterOS/Query.cls index 385124e..9e2190a 100644 --- a/docs/tutorials/PEAR2_Net_RouterOS/Query.cls +++ b/docs/tutorials/PEAR2_Net_RouterOS/Query.cls @@ -66,4 +66,15 @@ The {@link Query} class uses a "fluent" interface, i.e. it always returns the qu $query = Query::where('address', '192.168.0.100', Query::ACTION_GREATHER_THAN)->orWhere('address', '192.168.0.100'); + + Limiting returned properties + + 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). + + 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: + + $request->setArgument('.proplist', 'mac-address'); + or if you wanted MAC addresses and comments + $request->setArgument('.proplist', 'mac-address,comment'); + \ No newline at end of file diff --git a/extrasetup.php b/extrasetup.php index 81f8968..9c57881 100644 --- a/extrasetup.php +++ b/extrasetup.php @@ -3,10 +3,17 @@ $transmitterPackage = new \PEAR2\Pyrus\Package( __DIR__ . DIRECTORY_SEPARATOR - . '../../PEAR2_Net_Transmitter.git/package.xml' + . '../PEAR2_Net_Transmitter.git/package.xml' ); unset($transmitterPackage->files['docs/docblox.xml']); unset($transmitterPackage->files['docs/doxygen.ini']); -unset($transmitterPackage->files['tests/configuration.xml']); + +unset($transmitterPackage->files['tests/ClientTest.php']); +unset($transmitterPackage->files['tests/ServerTest.php']); +unset($transmitterPackage->files['tests/UnconnectedTest.php']); unset($transmitterPackage->files['tests/bootstrap.php']); +unset($transmitterPackage->files['tests/phpunit.xml']); +unset($transmitterPackage->files['tests/secondaryPeer.xml']); +unset($transmitterPackage->files['tests/secondaryPeer.bat']); + $extrafiles = array($transmitterPackage); \ No newline at end of file diff --git a/package.xml b/package.xml index 8aeea20..a5188e0 100644 --- a/package.xml +++ b/package.xml @@ -129,7 +129,7 @@ - + @@ -164,6 +164,7 @@ PEAR2_Net_Transmitter pear2.php.net + 1.0.0a2 PCRE @@ -259,8 +260,8 @@ as="PseudoServer.php" />