Add documentation

Greg Heitz · Greg Heitz · commit b5f8e3654953 · 2016-07-17T12:23:29.000+01:00
diff --git a/README.md b/README.md
@@ -10,12 +10,14 @@
 
 The [Codeception](http://codeception.com/) module for [BrowserMob Proxy](http://bmp.lightbody.net/)
 
-:bangbang: **THIS MODULE IS UNDER DEVELOPMENT**
+## Roadmap
+- [x] **0.1**: Initial version based on library [PHPBrowserMobProxy by chartjes](https://github.com/chartjes/PHPBrowserMobProxy/) with imited support of BrowserMob Proxy legacy API and no Littleproxy support
+- [ ] 0.2: New PHP BrowserMob Proxy with full REST API support (Jetty and Littleproxy) and [proxy auto-configuration](https://en.wikipedia.org/wiki/Proxy_auto-config) feature.
 
 ## Minimum Requirements
 - Codeception 2.2
 - PHP 5.5
-- BrowserMob Proxy
+- BrowserMob Proxy 2.0
 
 ## Installation
 The module can be installed using [Composer](https://getcomposer.org)
@@ -34,4 +36,61 @@ Enabling **BrowserMob** is done in your configuration file `.yml`.
 module:
     enabled:
         - Codeception\Extension\BrowserMob
+            host: 'localhost'
+            port: 8080
 ```
+
+### Parameters
+**BrowserMob** support following configuration parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `host` | **string** | BrowserMob Proxy host |
+| `port` | **integer** | BrowserMob Proxy port |
+| `autostart` | **boolean** | Start a new proxy instance automatically [*default = false*] |
+| `whitelist` | **array** | <p>URLs whitelisting</p><p>`code`: HTTP status code for URLs that do not match patterns</p><p>`patterns`: array of whitelisted URLs patterns<p> |
+| `blacklist` | **array** | <p>URLs blacklisting</p><p>`code`: HTTP status code for URLs that match patterns</p><p>`patterns`: array of blacklisted URLs patterns<p> |
+| `limits` | **array** | Bandwidth limits through the proxy (see [BrowserMob Proxy REST API](https://github.com/lightbody/browsermob-proxy#rest-api))|
+| `timeouts` | **array** | Proxy timeouts (see [BrowserMob Proxy REST API](https://github.com/lightbody/browsermob-proxy#rest-api)) |
+| `basicAuth` | **array** | <p>Sets automatic basic authentication a list of domains</p><p>`domain`: domain name</p><p>`options`:HTTP authentication parameters using format *`name: value`* (see [BrowserMob Proxy REST API](https://github.com/lightbody/browsermob-proxy#rest-api))</p> |
+| `dns` | **array** | <p>Internal proxy DNS using pairs of domain/IP to map</p><p>`domain`: domain name</p><p>`ip`: matching IP</p>  |
+| `retry` | **integer** | Number of times a method will be retried [*default = 0*] |
+
+***Example***
+```yaml
+modules:
+    config:
+        Codeception\Extension\BrowserMob:
+            host: 'localhost'
+            port: 9090
+            autostart: true
+            whitelist:
+                code: 404
+                patterns:
+                    - 'http://codeception.com/'
+            limits:
+                downstreamKbps: 12
+                upstreamKbps: 12
+                latency: 1
+            timeouts:
+                request: 10
+                read: 10
+                connection: 10
+                dns: 10
+            basicAuth:
+                - domain: example.local
+                  options:
+                      username: myUsername
+                      password: myPassword
+            dns:
+                - domain: example.local
+                  ip: 127.0.0.1
+                - domain: wikipedia.org
+                  ip: 192.168.1.1
+            retry: 3
+```
+
+## Documentation
+The module documentation is available in the [wiki](https://github.com/edno/codeception-browsermob/wiki/Codeception-BrowserMob-Proxy-extension-Documentation).
+
+For more information on how to use BrowserMob proxy, refer to [BrowserMob Proxy REST API documentation](https://github.com/lightbody/browsermob-proxy#rest-api).
diff --git a/composer.json b/composer.json
@@ -17,7 +17,8 @@
     },
     "require-dev": {
         "satooshi/php-coveralls": "^1.0",
-        "victorjonsson/markdowndocs": "dev-master"
+        "phpdocumentor/phpdocumentor": "^2.0",
+        "cvuorinen/phpdoc-markdown-public": "*"
     },
     "autoload": {
         "psr-4": {
@@ -45,8 +46,10 @@
             "docker rmi codecept/browsermob"
         ],
         "phpdoc-md": [
-            "mkdir -p docs",
-            "vendor/victorjonsson/markdowndocs/bin/phpdoc-md generate src > docs/extension.md"
+            "rm -rf docs",
+            "git clone https://github.com/edno/codeception-browsermob.wiki.git docs",
+            "./vendor/bin/phpdoc --quiet",
+            "mv docs/README.md docs/Codeception-BrowserMob-Proxy-extension-Documentation.md"
         ]
     }
 }
diff --git a/docs b/docs
@@ -1 +1 @@
-Subproject commit 7bc48687231c101860cf64bf233a9b7fc0cea7f4
+Subproject commit a83d179f05830c127f26806b01543df2de6d8a89
diff --git a/phpdoc.xml b/phpdoc.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdoc>
+    <title>Codeception BrowserMob Proxy extension Documentation</title>
+    <parser>
+        <target>docs/build</target>
+    </parser>
+    <transformer>
+        <target>docs</target>
+    </transformer>
+    <transformations>
+        <template name="vendor/cvuorinen/phpdoc-markdown-public/data/templates/markdown-public" />
+    </transformations>
+    <files>
+        <directory>src</directory>
+        <ignore>tests/*</ignore>
+        <ignore>vendor/*</ignore>
+    </files>
+</phpdoc>
diff --git a/src/BrowserMob.php b/src/BrowserMob.php
@@ -9,33 +9,45 @@
 use \RuntimeException;
 
 /**
- * @method void _open()
- * @method void _close()
- * @method string _newHar(string $label='')
- * @method string _newPage(string $label='')
- * @method string _blacklist(string $regexp, integer $status_code)
- * @method string _whitelist(string $regexp, integer $status_code)
- * @method string _basicAuth(string $domain, string[] $options)
- * @method string _headers(string[] $options)
- * @method string _responseInterceptor(string $js)
- * @method string _requestInterceptor(string $js)
- * @method Requests_Response _limits(string[] $options)
- * @method Requests_Response _timeouts(string[] $options)
- * @method string _remapHosts(string $address, string $ip_address)
- * @method string _waitForTrafficToStop(integer $quiet_period, integer $timeout)
- * @method string _clearDnsCache()
- * @method string _rewriteUrl(string $match, string $replace)
- * @method string _retry(integer $retry_count)
+ * @method void _open() Open a new proxy using the PHPBrowserMobProxy_Client method
+ * @method void _close() Close current proxy using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _newHar(string $label='') Start new HAR using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _newPage(string $label='') Start new HAR page using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _blacklist(string $regexp, integer $status_code) Blacklist URLs using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _whitelist(string $regexp, integer $status_code) Whitelist URLs using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _basicAuth(string $domain, string[] $options) Set HTTP authentication headers using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _headers(string[] $options) Override requests HTTP headers using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _responseInterceptor(string $js) Intercept HTTP responses using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _requestInterceptor(string $js) Intercept HTTP requests using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _limits(string[] $options) Set proxy limits using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _timeouts(string[] $options) Set proxy timeouts using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _remapHosts(string $address, string $ip_address) Map hosts to IP using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _waitForTrafficToStop(integer $quiet_period, integer $timeout) Wait for traffic before stopping proxy using the PHPBrowserMobProxy_Client method
+ * @method string _clearDnsCache() Flux proxy DNS cache using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _rewriteUrl(string $match, string $replace) Rewrite URLs using the PHPBrowserMobProxy_Client method
+ * @method \Requests_Response _retry(integer $retry_count) Set proxy retries using the PHPBrowserMobProxy_Client method
  */
 class BrowserMob extends Module
 {
 
+    /**
+     * @var string[] $config
+     */
     protected $config = ['host', 'port', 'autostart', 'blacklist', 'whitelist', 'limits', 'timeouts', 'dns', 'retry', 'basicAuth', 'littleproxy'];
 
-    protected $requiredFields = ['host'];
+    /**
+     * @var string[] $requiredFields
+     */
+    protected $requiredFields = ['host', 'port'];
 
+    /**
+     * @var Requests $response
+     */
     protected $response;
 
+    /**
+     * @var PHPBrowserMobProxy_Client $bmp
+     */
     private $bmp;
 
     /**
@@ -44,10 +56,7 @@ class BrowserMob extends Module
      */
     public function _initialize()
     {
-        $host = $this->config['host'];
-        if (isset($this->config['port'])) {
-            $host = $host.':'.$this->config['port'];
-        }
+        $host = $this->config['host'].':'.$this->config['port'];
 
         // test if proxy is available
         if (static::__pingProxy($host)) {
@@ -64,7 +73,14 @@ public function _initialize()
         }
     }
 
-    protected static function __pingProxy($url)
+    /**
+     * Verify if the BrowserMobProxy is reachable
+     *
+     * @param string $host BrowserMob Proxy host, format host:port
+     *
+     * @return boolean Returns true if proxy available, else false
+     */
+    protected static function __pingProxy($host)
     {
         try {
             $response = Requests::get('http://'.$url.'/proxy/');
@@ -75,6 +91,21 @@ protected static function __pingProxy($url)
         return $response->success;
     }
 
+    /**
+     * Set proxy capabilitites: blacklist, whitelist, limits, timeouts, dns, retry, basicAuth
+     *
+     * @uses BrowserMob::_blacklist
+     * @uses BrowserMob::_whitelist
+     * @uses BrowserMob::_limits
+     * @uses BrowserMob::_timeouts
+     * @uses BrowserMob::_remapHosts
+     * @uses BrowserMob::_retry
+     * @uses BrowserMob::_basicAuth
+     *
+     * @param mixed[] $options Array of options (see extension configuration)
+     *
+     * @return void
+     */
     protected function __setProxyCapabilities($options)
     {
         foreach ($options as $config => $data) {
@@ -115,11 +146,29 @@ protected function __setProxyCapabilities($options)
         }
     }
 
+    /**
+     * Return current proxy port opened on BrowserMobProxy
+     *
+     * @return integer Proxy port
+     */
     public function getProxyPort()
     {
         return $this->bmp->port;
     }
 
+    /**
+     * Open a new proxy on BrowserMobProxy
+     *
+     * @see BrowserMob::__setProxyCapabilities
+     *
+     * @uses BrowserMob::_open
+     * @uses BrowserMob::__setProxyCapabilities
+     * @uses BrowserMob::getProxyPort
+     *
+     * @param mixed[]|null $capabilities Array of capabilities. Use extension configuration if null
+     *
+     * @return integer Proxy port
+     */
     public function openProxy($capabilities = null)
     {
         $this->_open();
@@ -130,53 +179,121 @@ public function openProxy($capabilities = null)
         return $this->getProxyPort();
     }
 
+    /**
+     * Close the current proxy opened BrowserMobProxy
+     * Not supported by library chartjes/php-browsermob-proxy
+     *
+     * @uses BrowserMob::_close
+     *
+     * @return void
+     */
     public function closeProxy()
     {
         $this->_close();
     }
 
+    /**
+     * Start to capture the HTTP archive
+     *
+     * @uses BrowserMob::_newHar
+     *
+     * @param string|null $label Title of first HAR page
+     *
+     * @return boolean Command status
+     */
     public function startHar($label = '')
     {
         $this->_newHar($label);
         return $this->response->success;
     }
 
+    /**
+     * Add a new page to the HTTP archive
+     *
+     * @uses BrowserMob::_newPage
+     *
+     * @param string|null $label Title of new HAR page
+     *
+     * @return boolean Command status
+     */
     public function addPage($label = '')
     {
         $this->_newPage($label);
         return $this->response->success;
     }
 
+    /**
+     * Get the HTTP archive captured
+     *
+     * @return mixed[] HTTP archive
+     */
     public function getHar()
     {
         return $this->bmp->har;
     }
 
+    /**
+     * Override HTTP request headers
+     *
+     * @uses BrowserMob::_headers
+     *
+     * @param string[] $headers Array of HTTP headers
+     *
+     * @return boolean Command status
+     */
     public function setHeaders($headers)
     {
         $this->_headers($headers);
         return $this->response->success;
     }
 
+    /**
+     * Rewrite URLs with regex
+     *
+     * @uses BrowserMob::_rewriteUrl
+     *
+     * @param string $match Matching URL regular expression
+     * @param string $replace Replacement URL
+     *
+     * @return boolean Command status
+     */
     public function redirectUrl($match, $replace)
     {
         $this->_rewriteUrl($match, $replace);
         return $this->response->success;
     }
 
+    /**
+     * Run Javascript against requests before sending them
+     *
+     * @param string $script Javascript code
+     *
+     * @return boolean Command status
+     */
     public function filterRequest($script)
     {
         $this->_requestInterceptor($script);
         return $this->response->success;
     }
 
+    /**
+     * Run Javascript against responses received
+     *
+     * @param string $script Javascript code
+     *
+     * @return boolean Command status
+     */
     public function filterResponse($script)
     {
         $this->_responseInterceptor($script);
         return $this->response->success;
     }
 
-    // magic function that exposes BrowserMobProxy API pulic methods
+    /**
+     * Magic function that exposes BrowserMobProxy API pulic methods
+     *
+     * @ignore Exclude from documentation
+     */
     public function __call($name, $args)
     {
         // check if is a command call

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Subproject commit 7bc48687231c101860cf64bf233a9b7fc0cea7f4`
	`1`	`+Subproject commit a83d179f05830c127f26806b01543df2de6d8a89`