diff --git a/.gitignore b/.gitignore index ec8dd5b..f9a70cb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ composer.lock -phpunit.xml .phpunit.result.cache -vendor/ src/voipbl.conf src/localbl.db src/voipbl.db +docs/php/build/ +vendor/ diff --git a/README.md b/README.md index fb9b5b5..e9edbe7 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,8 @@ when to use API acknowledgements. ## Library Usage -Instead of using the `voipbl.php` file, you can use the `ExaBGP\VoIPBL` classes independently. +Instead of using the `voipbl.php` file, you can use the `ExaBGP\VoIPBL` classes independently. Check the +[ExaBGP\VoIPBL library documentation](docs/php/README.md) for the list of functions and their arguments. ```php use ExaBGP\VoIPBL\Loader; @@ -57,12 +58,13 @@ $version = $controller->sendCommand('version', true); ## Development & Testing -To verify the integrity of the codebase you can run the PHP linter and unit tests: +To verify the integrity of the codebase you can run the PHP linter, unit tests, and update the library documentation: ``` $ composer install -$ ./vendor/bin/phpunit -$ ./vendor/bin/phpcs --standard=phpcs.xml --extensions=php src/ tests/ +$ composer phpunit +$ composer phpcs +$ composer phpdoc ``` ## Collaboration diff --git a/composer.json b/composer.json index 47660b2..b23c8ea 100644 --- a/composer.json +++ b/composer.json @@ -19,12 +19,20 @@ "php": ">=7.0" }, "require-dev": { + "cvuorinen/phpdoc-markdown-public": ">=0.2", + "jms/serializer": "^1.7", "squizlabs/php_codesniffer": ">=3.0", + "phpdocumentor/phpdocumentor": ">=2.9", "phpunit/phpunit": ">=8.0" }, "autoload": { "psr-4": { "ExaBGP\\": "src/ExaBGP/" } + }, + "scripts": { + "phpcs": "phpcs --standard=phpcs.xml --extensions=php src/ tests/", + "phpdoc": "phpdoc && sed -i \"s/'/'/g\" docs/php/README.md", + "phpunit": "phpunit" } } diff --git a/docs/php/README.md b/docs/php/README.md new file mode 100644 index 0000000..467ffb8 --- /dev/null +++ b/docs/php/README.md @@ -0,0 +1,440 @@ +# ExaBGP\VoIPBL Library Documentation + +## Table of Contents + +* [Controller](#controller) + * [__construct](#__construct) + * [init](#init) + * [loadVersion](#loadversion) + * [sendCommand](#sendcommand) +* [Loader](#loader) + * [__construct](#__construct-1) + * [start](#start) +* [Validator](#validator) + * [isIP](#isip) + * [isCIDR](#iscidr) + * [isPrivateIP](#isprivateip) + * [isReservedIP](#isreservedip) + * [isNotPrivateIP](#isnotprivateip) + * [isNotReservedIP](#isnotreservedip) + * [isURL](#isurl) + * [isRegularExpression](#isregularexpression) + * [makeCIDR](#makecidr) + * [ensureFileIsReadable](#ensurefileisreadable) + * [ensureFileIsWritable](#ensurefileiswritable) + * [ensureRequiredCfg](#ensurerequiredcfg) + +## Controller + +The Controller class. + + + +* Full name: \ExaBGP\VoIPBL\Controller + +**See Also:** + +* https://github.com/GeertHauwaerts/exabgp-voipbl - exabgp-voipbl + +### __construct + +Create a new Controller instance. + +```php +Controller::__construct( ): void +``` + + + + + + + +--- + +### init + +Initialize an ExaBGP connection. + +```php +Controller::init( ): void +``` + + + + + + + +--- + +### loadVersion + +Load the ExaBGP version. + +```php +Controller::loadVersion( ): void +``` + + + + + + + +--- + +### sendCommand + +Send an API command to ExaBGP. + +```php +Controller::sendCommand( string $cmd, boolean $response = false ): boolean|string +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$cmd` | **string** | The command to execute. | +| `$response` | **boolean** | Indicate whether to return the API response. | + + + + +--- + +## Loader + +The Loader class. + + + +* Full name: \ExaBGP\VoIPBL\Loader + +**See Also:** + +* https://github.com/GeertHauwaerts/exabgp-voipbl - exabgp-voipbl + +### __construct + +Create a new Loader instance. + +```php +Loader::__construct( string $path = __DIR__, string $cfg = 'voipbl.conf' ): void +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$path` | **string** | The data path. | +| `$cfg` | **string** | The configuration file name. | + + + + +--- + +### start + +Handover the process to ExaBGP. + +```php +Loader::start( ): void +``` + + + + + + + +--- + +## Validator + +The Validator class. + + + +* Full name: \ExaBGP\VoIPBL\Validator + +**See Also:** + +* https://github.com/GeertHauwaerts/exabgp-voipbl - exabgp-voipbl + +### isIP + +Validate an IP address. + +```php +Validator::isIP( string $ip ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$ip` | **string** | An IP address. | + + + + +--- + +### isCIDR + +Validate an IP/CIDR address. + +```php +Validator::isCIDR( string $ipcidr ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$ipcidr` | **string** | An IP/CIDR address. | + + + + +--- + +### isPrivateIP + +Validate an RFC1918 IP or IP/CIDR address. + +```php +Validator::isPrivateIP( string $ipcidr ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$ipcidr` | **string** | An IP or IP/CIDR address. | + + + + +--- + +### isReservedIP + +Validate an RFC1700 IP or IP/CIDR address. + +```php +Validator::isReservedIP( string $ipcidr ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$ipcidr` | **string** | An IP or IP/CIDR address. | + + + + +--- + +### isNotPrivateIP + +Validate an RFC1918 IP or IP/CIDR address. (negates) + +```php +Validator::isNotPrivateIP( string $ipcidr ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$ipcidr` | **string** | An IP or IP/CIDR address. | + + + + +--- + +### isNotReservedIP + +Validate an RFC1700 IP or IP/CIDR address. (negates) + +```php +Validator::isNotReservedIP( string $ipcidr ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$ipcidr` | **string** | An IP or IP/CIDR address. | + + + + +--- + +### isURL + +Validate a URL. + +```php +Validator::isURL( string $url ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$url` | **string** | A URL. | + + + + +--- + +### isRegularExpression + +Validate a regular expression. + +```php +Validator::isRegularExpression( string $expr ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$expr` | **string** | A regular expression. | + + + + +--- + +### makeCIDR + +Change an IP into an IP/CIDR. + +```php +Validator::makeCIDR( string $ip ): boolean +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$ip` | **string** | An IP address. | + + + + +--- + +### ensureFileIsReadable + +Ensure the given file is readable. + +```php +Validator::ensureFileIsReadable( string $file ): void +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$file` | **string** | The file to read. | + + + + +--- + +### ensureFileIsWritable + +Ensure the given file is writable. + +```php +Validator::ensureFileIsWritable( string $file ): void +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$file` | **string** | The file to write to. | + + + + +--- + +### ensureRequiredCfg + +Ensure the required configuration parameters are present. + +```php +Validator::ensureRequiredCfg( string $cfg ): void +``` + + + + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `$cfg` | **string** | The configuration parameters. | + + + + +--- + + + +-------- +> This document was automatically generated from source code comments on 2019-04-24 using [phpDocumentor](http://www.phpdoc.org/) and [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public) diff --git a/phpdoc.xml b/phpdoc.xml new file mode 100644 index 0000000..17e2992 --- /dev/null +++ b/phpdoc.xml @@ -0,0 +1,17 @@ + + + ExaBGP\VoIPBL Library Documentation + + docs/php/build + + + docs/php + + +