Merge branch 'hotfix/4'

Close #4

.gitignore

@@ -6,10 +6,12 @@
 .*.sw*
 .*.un~
 nbproject
+doc/html/
 tmp/
+vendor/
+zf-mkdoc-theme/
 
 clover.xml
 composer.lock
 coveralls-upload.json
 phpunit.xml
-vendor

.travis.yml

@@ -10,6 +10,16 @@ branches:
 cache:
   directories:
     - $HOME/.composer/cache
+    - $HOME/.local
+    - zf-mkdoc-theme
+
+env:
+  global:
+    - SITE_URL: https://zendframework.github.io/zend-uri
+    - GH_USER_NAME: "Matthew Weier O'Phinney"
+    - GH_USER_EMAIL: matthew@weierophinney.net
+    - GH_REF: github.com/zendframework/zend-uri.git
+    - secure: "b4gS0ysUKbKmSSxDWk9ig1/OoFz4GOUoiGp84+zl1p7t4UHLfVcWhpHOO0Hu+VJ+3OV9ZNVSskeCgzQH6kdy6lc18kFf9RRrBEOxJQNWpwYmtorwEWxiwemZ3CIVx2DzmZ2zQOJpPaf260PHF25RGdbxATKnAjIPXsDmb82QRSB92AASAmTWnH9DE6Mx/M3jhYjkIBtkasfEtJXBSAlJgHWlFxdNRfABYUb98XTCuOXyAotc8WT/QalBjexMsdhkyAlrJ1AyMv9z8YqcXVkP6aHJwr5EutPp+E48fHAxDhLmo86Ww1CIpM+hB1IbUKtvGrtdMHQdcf7uNSqLoFcnPcxe/uR0oCgCjyRfliAGU3vwu9s9TBuk+CmtCXxNG6BDZbNd2iu468qaKsrlCgwFhKHQ9vLlHIBobhaTDm/wbtAvMXefduR6f2Y6tMvI/OvVU/bK7ESBzg5M6znQUwUikEsrQrNYyfLyEuamJNT5sUwWWxQJ4DZaSnmYu0Y4SSlPACawiNqMu2Eew+b+jI0L5tU+3qLlhTYJns3SGHzafbcy59d5B1CbW6XYxLUX7/D3AQPL/E5JOcEa0WPH4LpEemXSiS7iRWHQhz3FoBJJ8I7a09EeXv3MxcG4Pb8c0OF1Mqk9j04/UnCRsuhQb+G9wupq8upaN5Hemuwe0CCp0SQ="
 
 matrix:
   fast_finish: true
@@ -20,6 +30,8 @@ matrix:
     - php: 5.6
       env:
         - EXECUTE_TEST_COVERALLS=true
+        - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
+        - PATH="$HOME/.local/bin:$PATH"
     - php: 7
     - php: hhvm 
   allow_failures:
@@ -41,6 +53,10 @@ script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi
   - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi
   - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi
+  - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi
+
+after_success:
+  - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi
 
 after_script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi

CHANGELOG.md

@@ -6,7 +6,8 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Added
 
-- Nothing.
+- [#4](https://github.com/zendframework/zend-uri/pull/4) adds and publishes the
+  documentation to https://zendframework.github.io/zend-uri/
 
 ### Deprecated
 

README.md

@@ -3,11 +3,10 @@
 [![Build Status](https://secure.travis-ci.org/zendframework/zend-uri.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-uri)
 [![Coverage Status](https://coveralls.io/repos/zendframework/zend-uri/badge.svg?branch=master)](https://coveralls.io/r/zendframework/zend-uri?branch=master)
 
-`Zend\Uri` is a component that aids in manipulating and validating Uniform
-Resource Identifiers ([URIs](http://www.ietf.org/rfc/rfc3986.txt)). `Zend\Uri`
-exists primarily to service other components, such as `Zend\Http`, but is also
-useful as a standalone utility.
-
+zend-uri aids in manipulating and validating Uniform Resource Identifiers
+([URIs](http://www.ietf.org/rfc/rfc3986.txt)). zend-uri exists primarily to
+assist other components, such as zend-http, but is also useful as a standalone
+utility.
 
 - File issues at https://github.com/zendframework/zend-uri/issues
-- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-uri
+- Documentation is at https://zendframework.github.io/zend-uri/

doc/book/index.html

@@ -0,0 +1,10 @@
+<div class="container">
+  <div class="jumbotron">
+    <h1>zend-uri</h1>
+
+    <p>Object oriented interface to URIs, with facilities for validation.</p>
+
+    <pre><code class="language-bash">$ composer require zendframework/zend-uri</code></pre>
+  </div>
+</div>
+

doc/book/index.md

@@ -0,0 +1 @@
+../../README.md

doc/book/intro.md

@@ -0,0 +1,14 @@
+# Introduction
+
+zend-uri aids in manipulating and validating [Uniform 
+Resource Identifiers](http://www.w3.org/Addressing/)
+([URIs](http://www.ietf.org/rfc/rfc3986.txt)). zend-uri exists primarily
+to assist other components, such as
+[zend-http](https://zendframework.github.io/zend-http/), but is also useful as a
+standalone utility.
+
+URIs always begin with a scheme, followed by a colon. The construction of the
+many different schemes varies significantly. The zend-uri component provides the
+`Zend\Uri\UriFactory` that returns an instance of the appropriate class
+implementing `Zend\Uri\UriInterface` for the given scheme (assuming the factory
+can locate one).

doc/book/usage.md

@@ -0,0 +1,241 @@
+# Usage
+
+## Creating a New URI
+
+`Zend\Uri\UriFactory` will build a new URI from scratch if only a scheme is
+passed to `Zend\Uri\UriFactory::factory()`.
+
+### Creating a New URI with ZendUriUriFactory::factory()
+
+```php
+// To create a new URI from scratch, pass only the scheme
+// followed by a colon.
+$uri = Zend\Uri\UriFactory::factory('http:');
+
+// $uri instanceof Zend\Uri\UriInterface
+```
+
+To create a new URI from scratch, pass only the scheme followed by a colon to
+`Zend\Uri\UriFactory::factory()`. If an unsupported scheme is passed and no
+scheme-specific class is specified, a
+`Zend\Uri\Exception\InvalidArgumentException` will be thrown.
+
+If the scheme or URI passed is supported, `Zend\Uri\UriFactory::factory()` will
+return a class implementing `Zend\Uri\UriInterface` that specializes in the
+scheme referenced.
+
+> ### Supported schemes
+>
+> At the time of writing, zend-uri provides built-in support for the following
+> schemes only: HTTP, HTTPS, MAILTO and FILE.
+
+### Creating a New Custom-Class URI
+
+You can specify a custom class to be used when using the `Zend\Uri\UriFactory`
+by registering your class with the `UriFactory` using
+`Zend\Uri\UriFactory::registerScheme($scheme, $class)`.  This enables you to
+create your own URI class and instantiate new URI objects based on your own
+custom classes.
+
+The 2nd parameter passed to `Zend\Uri\UriFactory::registerScheme()` must be a
+string with the name of a class implementing `Zend\Uri\UriInterface`. The class
+must either be already loaded, or be loadable by the autoloader.
+
+#### Creating a URI using a custom class
+
+The following registers the `ftp` scheme with a custom URI class:
+
+```php
+use MyNamespace\MyClass;
+use Zend\Uri\UriFactory
+
+UriFactory::registerScheme('ftp', MyClass::class);
+
+$ftpUri = UriFactory::factory(
+    'ftp://user@ftp.example.com/path/file'
+);
+
+// $ftpUri is an instance of MyLibrary\MyClass, which implements
+// Zend\Uri\UriInterface
+```
+
+## Manipulating an Existing URI
+
+To manipulate an existing URI, pass the entire URI as a string to
+`Zend\Uri\UriFactory::factory()`, and then manipulate the instance returned.
+
+### Manipulating an Existing URI with Zend\\Uri\\UriFactory::factory()
+
+```php
+use Zend\Uri\UriFactory;
+
+// To manipulate an existing URI, pass it in.
+$uri = UriFactory::factory('http://www.zend.com');
+
+// $uri instanceof Zend\Uri\UriInterface
+```
+
+The URI will be parsed and validated. If it is found to be invalid, a
+`Zend\Uri\Exception\InvalidArgumentException` will be thrown immediately.
+Otherwise, `Zend\Uri\UriFactory::factory()` will return a class implementing
+`Zend\Uri\UriInterface` that specializes in the scheme to be manipulated.
+
+## Common Instance Methods
+
+The `Zend\Uri\UriInterface` defines several instance methods that are useful for
+working with any kind of URI.
+
+### Getting the Scheme of the URI
+
+The scheme of the URI is the part of the URI that precedes the colon. For
+example, the scheme of `http://johndoe@example.com/my/path?query#token` is
+'http'.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
+
+$scheme = $uri->getScheme();  // "mailto"
+```
+
+The `getScheme()` instance method returns only the scheme part of the URI
+object (not the separator).
+
+### Getting the Userinfo of the URI
+
+The userinfo of the URI is the optional part of the URI that follows the
+colon and comes before the host-part. For example, the userinfo of
+`http://johndoe@example.com/my/path?query#token` is 'johndoe'.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
+
+$scheme = $uri->getUserinfo();  // "john.doe"
+```
+
+The `getUserinfo()` method returns only the userinfo part of the URI object.
+
+### Getting the host of the URI
+
+The host of the URI is the optional part of the URI that follows the
+user-part and comes before the path-part. For example, the host of
+`http://johndoe@example.com/my/path?query#token` is 'example.com'.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
+
+$scheme = $uri->getHost();  // "example.com"
+```
+
+The `getHost()` method returns only the host part of the URI object.
+
+### Getting the port of the URI
+
+The port of the URI is the optional part of the URI that follows the host-part
+and comes before the path-part. For example, the host of
+`http://johndoe@example.com:80/my/path?query#token` is '80'.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://example.com:8080');
+
+$scheme = $uri->getPort();  // "8080"
+```
+
+Concrete URI instances can define default ports that can be returned when no
+port is given in the URI:
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://example.com');
+
+$scheme = $uri->getPort();  // "80"
+```
+
+The `getHost()` method returns only the port part of the URI object.
+
+### Getting the path of the URI
+
+The path of the URI is a mandatory part of the URI that follows the port
+and comes before the query-part. For example, the path of
+`http://johndoe@example.com:80/my/path?query#token` is '/my/path'.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
+
+$scheme = $uri->getPath();  // "/my/path"
+```
+
+The `getPath()` method returns only the path of the URI object.
+
+### Getting the query-part of the URI
+
+The query-part of the URI is an optional part of the URI that follows the
+path and comes before the fragment. For example, the query of
+`http://johndoe@example.com:80/my/path?query#token` is 'query'.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
+
+$scheme = $uri->getQuery();  // "a=b&c=d"
+```
+
+The `getQuery()` method returns only the query-part of the URI object.
+
+The query string often contains key=value pairs and therefore can be split into an
+associative array. This array can be retrieved using `getQueryAsArray()`:
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
+
+$scheme = $uri->getQueryAsArray();
+// [
+//  'a' => 'b',
+//  'c' => 'd',
+// ]
+```
+
+### Getting the fragment-part of the URI
+
+The fragment-part of the URI is an optional part of the URI that follows
+the query. For example, the fragment of
+`http://johndoe@example.com:80/my/path?query#token` is 'token'.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
+
+$scheme = $uri->getFragment();  // "token"
+```
+
+The `getFragment()` method returns only the fragment-part of the URI object.
+
+### Getting the Entire URI
+
+The `toString()` method returns the string representation of the entire *URI*.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
+
+echo $uri->toString();  // "http://www.zend.com"
+
+// Alternate method:
+echo (string) $uri;     // "http://www.zend.com"
+```
+
+The `Zend\Uri\UriInterface` defines also the magic `__toString()` method that
+returns the string representation of the URI when the object is cast to a
+string.
+
+## Validating the URI
+
+When using `Zend\Uri\UriFactory::factory()`, the given URI will always be
+validated and a `Zend\Uri\Exception\InvalidArgumentException` will be thrown
+when the URI is invalid. However, after the `Zend\Uri\UriInterface` is
+instantiated for a new URI or an existing valid one, it is possible that the URI
+can later become invalid after it is manipulated.
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
+
+$isValid = $uri->isValid();  // TRUE
+```
+
+The `isValid()` instance method provides a means to check that the URI object
+is still valid.

mkdocs.yml

@@ -0,0 +1,10 @@
+docs_dir: doc/book
+site_dir: doc/html
+pages:
+    - index.md
+    - Intro: intro.md
+    - Usage: usage.md
+site_name: zend-uri
+site_description: zend-uri
+repo_url: 'https://github.com/zendframework/zend-uri'
+copyright: 'Copyright (c) 2016 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'