move documentation to master

thephpleague · Nov 14, 2016 · e5d2f7f · e5d2f7f
1 parent e5d8041
commit e5d2f7f
Show file tree

Hide file tree

Showing 42 changed files with 5,761 additions and 5 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -2,14 +2,14 @@
 
 /.editorconfig     export-ignore
 /.gitattributes    export-ignore
-/.github           export-ignore
 /.gitignore        export-ignore
 /.php_cs           export-ignore
 /.scrutinizer.yml  export-ignore
 /.travis.yml       export-ignore
+/.github           export-ignore
+/docs              export-ignore
+/test              export-ignore
 /README.md         export-ignore
-/scrutinizer.yml   export-ignore
 /CHANGELOG.md      export-ignore
 /CONDUCT.md        export-ignore
-/phpunit.xml       export-ignore
-/test              export-ignore
+/phpunit.xml       export-ignore
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,4 @@
 vendor
 build
-docs
 composer.lock
 .idea
diff --git a/docs/CNAME b/docs/CNAME
@@ -0,0 +1 @@
+uri.thephpleague.com
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,4 @@
+---
+permalink: pretty
+gems:
+  - jekyll-redirect-from
diff --git a/docs/_data/images.yml b/docs/_data/images.yml
@@ -0,0 +1,8 @@
+# Path to project specific favicon.ico, leave blank to use default
+favicon:
+
+# Path to project specific apple-touch-icon-precomposed.png, leave blank to use default
+apple_touch:
+
+# Path to project logo
+logo:
diff --git a/docs/_data/menu.yml b/docs/_data/menu.yml
@@ -0,0 +1,38 @@
+Getting Started:
+    Introduction: '/'
+    Terminology: '/definitions/'
+    Installation: '/installation/'
+    Usage: '/examples/'
+    Changelog: '/changelog/'
+Uri:
+    Instantiation: '/uri/instantiation/'
+    Properties: '/uri/properties/'
+Uri Schemes:
+    Http URIs: '/uri/schemes/http/'
+    Websocket URIs: '/uri/schemes/ws/'
+    FTP URI: '/uri/schemes/ftp/'
+    Data URI: '/uri/schemes/data-uri/'
+    Extension Guide: '/uri/extension/'
+Uri manipulation:
+    Overview: '/uri/manipulation/'
+    Uri Modifiers: '/uri/manipulation/generic/'
+    Host Modifiers: '/uri/manipulation/host/'
+    Path Modifiers: '/uri/manipulation/path/'
+    Query Modifiers: '/uri/manipulation/query/'
+Uri Parts API:
+    Overview: '/components/overview/'
+    Scheme: '/components/scheme/'
+    User: '/components/user/'
+    Pass: '/components/pass/'
+    User Information: '/components/userinfo/'
+    Host: '/components/host/'
+    Port: '/components/port/'
+    Path: '/components/path/'
+    Hierarchical Path: '/components/hierarchical-path/'
+    Data Path: '/components/datauri-path/'
+    Query: '/components/query/'
+    Fragment: '/components/fragment/'
+Services:
+    Uri Parser: '/services/parser-uri/'
+    Query Parser: '/services/parser-query/'
+    Formatter: '/services/formatter/'
diff --git a/docs/_data/project.yml b/docs/_data/project.yml
@@ -0,0 +1,4 @@
+title: "URI"
+tagline: "Modern API to process URI in PHP."
+description: "Modern API to process URI in PHP"
+google_analytics_tracking_id: UA-46050814-14
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    {% if page.url == '/' %}
+        <title>{{ site.data.project.title }} - {{ site.data.project.tagline }}</title>
+    {% else %}
+        <title>{{ page.title }} - {{ site.data.project.title }}</title>
+    {% endif %}
+    {% if site.data.project.description %}
+        <meta name="description" content="{{ site.data.project.description }}">
+    {% endif %}
+    {% if site.data.images.favicon %}
+        <link rel="icon" type="image/x-icon" href="{{ site.data.images.favicon }}" />
+    {% else %}
+        <link rel="icon" type="image/x-icon" href="http://theme.thephpleague.com/img/favicon.ico" />
+    {% endif %}
+    {% if site.data.images.apple_touch %}
+        <link rel="apple-touch-icon-precomposed" href="{{ site.data.images.apple_touch }}">
+    {% else %}
+        <link rel="apple-touch-icon-precomposed" href="http://theme.thephpleague.com/img/apple-touch-icon-precomposed.png">
+    {% endif %}
+    <link rel="stylesheet" href="http://theme.thephpleague.com/css/all.css?2">
+    <link rel="stylesheet" href="/custom.css">
+</head>
+<body>
+
+<section class="all_packages">
+    <a href="http://thephpleague.com/">
+        <img src="http://theme.thephpleague.com/img/loep_logo.png" width="195" height="200" alt="The League of Extraordinary Packages">
+    </a>
+    <h2>Our Packages:</h2>
+    <ul>
+        <!-- Loaded via JavaScript -->
+    </ul>
+</section>
+
+<header>
+    <a class="logo" href="/">
+        {% if site.data.images.logo %}
+            <span class="icon">
+                <img src="{{ site.data.images.logo }}" width="50" height="40" alt="{{ site.data.project.title }} - {{ site.data.project.tagline }}">
+            </span>
+        {% endif %}
+        <span class="name">{{ site.data.project.title }}</span>
+        <span class="tagline">{{ site.data.project.tagline }}</span>
+    </a>
+    <a href="http://thephpleague.com/" class="league">
+        Presented by The League of Extraordinary Packages
+    </a>
+</header>
+
+<input type="checkbox" id="menu">
+<label for="menu" onclick>
+    <div class="closed">&#9776; Menu</div>
+    <div class="open">&#9776; Hide Menu</div>
+</label>
+
+<main>
+    <menu>
+        {% for section in site.data.menu %}
+            <h2>{{ section[0] }}</h2>
+            <ul>
+                {% for link in section[1] %}
+                    <li {% if page.url == link[1] %}class="selected"{% endif %}>
+                        <a href="{{ link[1] }}">{{ link[0] }}</a>
+                    </li>
+                {% endfor %}
+            </ul>
+        {% endfor %}
+    </menu>
+    <article>
+        {{ content }}
+    </article>
+</main>
+
+<footer>
+    <span>&copy; Copyright <a href="http://thephpleague.com">The League of Extraordinary Packages</a>.</span>
+    <span>Site design by <a href="http://reinink.ca">Jonathan Reinink</a>.</span>
+</footer>
+
+<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
+<script src="http://theme.thephpleague.com/js/scripts.js"></script>
+<script src="/custom.js"></script>
+
+{% if site.data.project.google_analytics_tracking_id %}
+    <script>
+        (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]=
+        function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date;
+        e=o.createElement(i);r=o.getElementsByTagName(i)[0];
+        e.src='//www.google-analytics.com/analytics.js';
+        r.parentNode.insertBefore(e,r)}(window,document,'script','ga'));
+        ga('create','{{  site.data.project.google_analytics_tracking_id }}');ga('send','pageview');
+    </script>
+{% endif %}
+
+</body>
+</html>
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,13 @@
+---
+layout: default
+title: Version 4 - Changelog
+---
+
+# Changelog
+
+All Notable changes to `Uri` will be documented in this file
+
+{% for release in site.github.releases %}
+## [{{ release.name }}]({{ release.html_url }}) - {{ release.published_at | date: "%Y-%m-%d" }}
+{{ release.body | markdownify }}
+{% endfor %}
diff --git a/docs/components/datauri-path.md b/docs/components/datauri-path.md
@@ -0,0 +1,171 @@
+---
+layout: default
+title: The Data Uri Path component
+---
+
+# Data URI Path
+
+The library provides a `League\Uri\Components\DataPath` class to ease complex path manipulation on a Data URI object.  The class extends the default `Path` object with methods dedicated to manipulate Data URI paths.
+
+## Instantiation
+
+### Using the default constructor
+
+Just like any other component, a new `League\Uri\Components\DataPath` object can be instantiated using its default constructor.
+
+~~~php
+<?php
+
+use League\Uri\Components\DataPath as Path;
+
+$path = new Path('text/plain;charset=us-ascii,Hello%20World%21');
+echo $path; //returns 'text/plain;charset=us-ascii,Hello%20World%21'
+~~~
+
+<p class="message-notice">The <code>mediatype</code> is only validated according to its syntax. You should use an independent mediatype validator if necessary.</p>
+
+<p class="message-warning">If the submitted value is not a valid path an <code>InvalidArgumentException</code> will be thrown.</p>
+
+### Using a Data Uri object
+
+~~~php
+<?php
+
+use League\Uri\Schemes\Data as DataUri;
+
+$uri  = DataUri::createFromString('data:text/plain;charset=us-ascii,Hello%20World%21');
+$path = $uri->path; // $path is a League\Uri\Components\DataPath object;
+~~~
+
+### Using a named constructor
+
+### Instantiating using a file path
+
+Because data URI represents files you can also instantiate a new data URI object from a file path using the `createFromPath` named constructor
+
+~~~php
+<?php
+
+use League\Uri\Components\DataPath as Path;
+
+$path = Path::createFromPath('path/to/my/png/image.png');
+echo $uri; //returns 'image/png;charset=binary;base64,...'
+//where '...' represent the base64 representation of the file
+~~~
+
+If the file is not readable or accessible an InvalidArgumentException exception will be thrown. The class uses PHP's `finfo` class to detect the required mediatype as defined in RFC2045.
+
+## Path representations
+
+### String representation
+
+Basic path representations is done using the following methods:
+
+~~~php
+<?php
+
+use League\Uri\Components\DataPath as Path;
+
+$path = new Path('text/plain;charset=us-ascii,Hello%20World%21');
+$path->__toString(); //returns 'text/plain;charset=us-ascii,Hello%20World%21'
+$path->getUriComponent(); //returns 'text/plain;charset=us-ascii,Hello%20World%21'
+~~~
+
+## Properties
+
+### Attributes
+
+The DataPath class exposes the following specific methods:
+
+- `getMediaType`: This method returns the Data URI current mediatype;
+- `getMimeType`: This method returns the Data URI current mimetype;
+- `getParameters`: This method returns the parameters associated with the mediatype;
+- `getData`: This methods returns the encoded data contained is the Data URI;
+
+Each of these methods return a string. This string can be empty if the data where no supplied when constructing the URI.
+
+~~~php
+<?php
+
+use League\Uri\Components\DataPath as Path;
+
+$uri = DataUri::createFromString('data:text/plain;charset=us-ascii,Hello%20World%21');
+echo $uri->getMediaType(); //returns 'text/plain;charset=us-ascii'
+echo $uri->getMimeType(); //returns 'text/plain'
+echo $uri->getParameters(); //returns 'charset=us-ascii'
+echo $uri->getData(); //returns 'Hello%20World%21'
+~~~
+
+### Is it a binary data ?
+
+To tell whether the data URI represents some binary data you can call the `isBinaryData` method. This method which returns a boolean will return `true` if the data is in a binary state. The binary state is checked on instantiation. Invalid binary dataURI will throw an `InvalidArgumentException` exception on initiation.
+
+~~~php
+<?php
+
+use League\Uri\Components\DataPath as Path;
+
+$uri = DataUri::createFromPath('path/to/my/png/image.png');
+$uri->isBinaryData(); //returns true
+$altUri = DataUri::createFromString('data:text/plain;charset=us-ascii,Hello%20World%21');
+$altUri->isBinaryData(); //returns false
+~~~
+
+## Manipulation
+
+The data URI Path class is an immutable object everytime you manipulate the object a new object is returned with the modified value if needed.
+
+### Update the Data URI parameters
+
+Since we are dealing with a data and not just a URI, the only property that can be easily modified are its optional parameters.
+
+To set new parameters you should use the `withParameters` method:
+
+~~~php
+<?php
+
+use League\Uri\Components\DataPath as Path;
+
+$path = new Path('text/plain;charset=us-ascii,Hello%20World%21');
+$newPath = $path->withParameters('charset=utf-8');
+echo $newPath; //returns 'text/plain;charset=utf-8,Hello%20World%21'
+~~~
+
+<p class="message-notice">Of note the data should be urlencoded if needed.</p>
+
+### Transcode the data between its binary and ascii representation
+
+Another manipulation is to transcode the data from ASCII to is base64 encoded (or binary) version. If no conversion is possible the former object is returned otherwise a new valid data uri object is created.
+
+~~~php
+<?php
+
+use League\Uri\Components\DataPath as Path;
+
+$path = new Path('data:text/plain;charset=us-ascii,Hello%20World%21');
+$path->isBinaryData(); // return false;
+$newPath = $path->toBinary();
+$newPath->isBinaryData(); //return true;
+$newPath->toAscii()->sameValueAs($path); //return true;
+~~~
+
+## Saving the Data URI Path
+
+Since the path can be interpreted as a file, it is possible to save it to a specified path using the dedicated `save` method. This method accepts two parameters:
+
+- the file path;
+- the open mode (à la PHP `fopen`);
+
+By default the open mode is set to `w`. If for any reason the file is not accessible a `RuntimeException` will be thrown.
+
+The method returns the `SplFileObject` object used to save the data-uri data for further analysis/manipulation if you want.
+
+~~~php
+<?php
+
+use League\Uri\Components\DataPath as Path;
+
+$uri = Path::createFromPath('path/to/my/file.png');
+$file = $uri->save('path/where/to/save/my/image.png');
+//$file is a SplFileObject which point to the newly created file;
+~~~