Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
update packages and fix the filter documentation
  • Loading branch information
harikt committed Sep 28, 2017
1 parent 8edf830 commit c04a7b7
Show file tree
Hide file tree
Showing 55 changed files with 1,273 additions and 106 deletions.
2 changes: 1 addition & 1 deletion _bookdown/book/2.x/bookdown.json
Expand Up @@ -7,7 +7,7 @@
{"Cli": "https://raw.githubusercontent.com/auraphp/Aura.Cli/2.x/README.md"},
{"Di": "https://raw.githubusercontent.com/auraphp/Aura.Di/2.x/README.md"},
{"Dispatcher": "https://raw.githubusercontent.com/auraphp/Aura.Dispatcher/2.x/README.md"},
{"Filter": "https://raw.githubusercontent.com/auraphp/Aura.Filter/2.x/README.md"},
{"Filter": "https://raw.githubusercontent.com/auraphp/Aura.Filter/2.x/docs/_bookdown.json"},
{"Html": "https://raw.githubusercontent.com/auraphp/Aura.Html/2.x/README.md"},
{"Includer": "https://raw.githubusercontent.com/auraphp/Aura.Includer/2.x/README.md"},
{"Router": "https://raw.githubusercontent.com/auraphp/Aura.Router/2.x/README.md"},
Expand Down
4 changes: 2 additions & 2 deletions packages/2.x/Accept.html
Expand Up @@ -18,7 +18,7 @@
</tr>
</table>
</nav>
<h1 id="2-1">2.1. Aura.Accept</h1>
<div id="section-main"><h1 id="2-1">2.1. Aura.Accept</h1>
<p>Provides content-negotiation tools using <code>Accept*</code> headers.</p>
<h2 id="2-1-1">2.1.1. Foreword</h2>
<h3 id="2-1-1-1">2.1.1.1. Installation</h3>
Expand Down Expand Up @@ -208,7 +208,7 @@ <h3 id="2-1-2-3">2.1.2.3. Negotiating Other Values</h3>
echo $language-&gt;getValue(); // pt-BR
?&gt;
</code></pre>

</div>
<nav class="navfooter">
<table>
<tr>
Expand Down
4 changes: 2 additions & 2 deletions packages/2.x/Auth.html
Expand Up @@ -18,7 +18,7 @@
</tr>
</table>
</nav>
<h1 id="2-2">2.2. Aura.Auth</h1>
<div id="section-main"><h1 id="2-2">2.2. Aura.Auth</h1>
<p>Provides authentication functionality and session tracking using various adapters; currently supported adapters are:</p>
<ul>
<li>Apache htpasswd files</li>
Expand Down Expand Up @@ -806,7 +806,7 @@ <h4 id="2-2-2-6-4">2.2.2.6.4. Aura\Auth\Adapter\PdoAdapter</h4>
);
?&gt;
</code></pre>

</div>
<nav class="navfooter">
<table>
<tr>
Expand Down
4 changes: 2 additions & 2 deletions packages/2.x/Autoload.html
Expand Up @@ -18,7 +18,7 @@
</tr>
</table>
</nav>
<h1 id="2-3">2.3. Aura.Autoload</h1>
<div id="section-main"><h1 id="2-3">2.3. Aura.Autoload</h1>
<p>Provides a full PSR-4 and limited PSR-0 autoloader. Although it is
installable via Composer, its best use is probably outside a Composer-oriented
project.</p>
Expand Down Expand Up @@ -137,7 +137,7 @@ <h3 id="2-3-2-4">2.3.2.4. Inspection and Debugging</h3>
// )
?&gt;
</code></pre>

</div>
<nav class="navfooter">
<table>
<tr>
Expand Down
4 changes: 2 additions & 2 deletions packages/2.x/Cli.html
Expand Up @@ -18,7 +18,7 @@
</tr>
</table>
</nav>
<h1 id="2-4">2.4. Aura.Cli</h1>
<div id="section-main"><h1 id="2-4">2.4. Aura.Cli</h1>
<p>Provides the equivalent of request ( <em>Context</em> ) and response ( <em>Stdio</em> )
objects for the command line interface, including <em>Getopt</em> support, and an
independent <em>Help</em> object for describing commands.</p>
Expand Down Expand Up @@ -438,7 +438,7 @@ <h3 id="2-4-2-7">2.4.2.7. Formatter Cheat Sheet</h3>
</code></pre>
<p>For example, to set bold white text on a red background, add <code>&lt;&lt;bold white redbg&gt;&gt;</code>
into your output or error string. Reset back to normal with <code>&lt;&lt;reset&gt;&gt;</code>.</p>

</div>
<nav class="navfooter">
<table>
<tr>
Expand Down
4 changes: 2 additions & 2 deletions packages/2.x/Di.html
Expand Up @@ -18,7 +18,7 @@
</tr>
</table>
</nav>
<h1 id="2-5">2.5. Aura.Di</h1>
<div id="section-main"><h1 id="2-5">2.5. Aura.Di</h1>
<p>The Aura.Di package provides a dependency injection container system with the
following features:</p>
<ul>
Expand Down Expand Up @@ -472,7 +472,7 @@ <h3 id="2-5-2-10">2.5.2.10. Container Builder and Config Classes</h3>
</ul>
<h3 id="2-5-2-11">2.5.2.11. Conclusion</h3>
<p>If we construct our dependencies properly with params, setters, services, and factories, we will only need to get one object directly from the <em>Container</em> in our bootstrap file. All object creation will then occur within <em>Container</em> itself or the various factory objects. We will never need to use the <em>Container</em> itself in any of our application objects.</p>

</div>
<nav class="navfooter">
<table>
<tr>
Expand Down
10 changes: 5 additions & 5 deletions packages/2.x/Dispatcher.html
Expand Up @@ -14,11 +14,11 @@
<tr>
<td class="prev"><a href="/packages/2.x/Di.html">Aura.Di</a></td>
<td class="parent">2. Version 2.x</th>
<td class="next"><a href="/packages/2.x/Filter.html">Aura.Filter</a></td>
<td class="next"><a href="/packages/2.x/Filter/">Aura.Filter 2.x</a></td>
</tr>
</table>
</nav>
<h1 id="2-6">2.6. Aura.Dispatcher</h1>
<div id="section-main"><h1 id="2-6">2.6. Aura.Dispatcher</h1>
<p>Provides tools to map arbitrary names to dispatchable objects, then to
dispatch to those objects using named parameters. This is useful for invoking
controller and command objects based on path-info parameters or command line
Expand Down Expand Up @@ -438,18 +438,18 @@ <h2 id="2-6-6">2.6.6. Intercessory Dispatch Methods</h2>
echo $result; // "Read blog entry 88"
?&gt;
</code></pre>

</div>
<nav class="navfooter">
<table>
<tr>
<td class="prev"><a href="/packages/2.x/Di.html">Prev</a></td>
<td class="parent"><a href="/packages/2.x/">Up</a></td>
<td class="next"><a href="/packages/2.x/Filter.html">Next</a></td>
<td class="next"><a href="/packages/2.x/Filter/">Next</a></td>
</tr>
<tr>
<td class="prev">2.5. Aura.Di</td>
<td class="parent">2. Version 2.x</td>
<td class="next">2.7. Aura.Filter</td>
<td class="next">2.7. Aura.Filter 2.x</td>
</tr>
</table>
</nav>
144 changes: 144 additions & 0 deletions packages/2.x/Filter/custom.html
@@ -0,0 +1,144 @@
---
layout: site
active: packages
title: Creating and Using Custom Rules
permalink: /packages/2.x/Filter/custom.html
---
<script>hljs.initHighlightingOnLoad();</script>

<nav class="navheader">
<table>
<tr>
<th colspan="3" class="curr">2.7.6. Creating and Using Custom Rules</th>
</tr>
<tr>
<td class="prev"><a href="/packages/2.x/Filter/sanitize.html">Rules To Sanitize Fields</a></td>
<td class="parent">2.7. Aura.Filter 2.x</th>
<td class="next"><a href="/packages/2.x/Html.html">Aura.Html</a></td>
</tr>
</table>
</nav>
<div id="section-main"><h1 id="2-7-6">2.7.6. Creating and Using Custom Rules</h1>
<p>There are three steps to creating and using new rules:</p>
<ol>
<li>
<p>Write a rule class, either to validate or sanitize a subject field</p>
</li>
<li>
<p>Set a factory for the class in the appropriate rule locator</p>
</li>
<li>
<p>Use the new rule in a filter specification</p>
</li>
</ol>
<h2 id="2-7-6-1">2.7.6.1. Writing a Rule Class</h2>
<p>Writing a rule class is straightforward. Define a class with an
<code>__invoke($subject, $field)</code> method, along with any additional needed arguments.
The method should return a boolean: true on success, or false on failure.</p>
<h3 id="2-7-6-1-1">2.7.6.1.1. A Validate Class</h3>
<p>Here is an example of a hexdecimal validator:</p>
<pre><code class="language-php">namespace Vendor\Package\Filter\Rule\Validate;

class ValidateHex
{
public function __invoke($subject, $field, $max = null)
{
// must be scalar
$value = $subject-&gt;$field;
if (! is_scalar($value)) {
return false;
}

// must be hex
$hex = ctype_xdigit($value);
if (! $hex) {
return false;
}

// must be no longer than $max chars
if ($max &amp;&amp; strlen($value) &gt; $max) {
return false;
}

// done!
return true;
}
}
</code></pre>
<h3 id="2-7-6-1-2">2.7.6.1.2. A Sanitize Class</h3>
<p>Here is an example of a hexadecimal sanitizer. Note how we modify the
<code>$subject-&gt;$field</code> value directly at the end of the method.</p>
<pre><code class="language-php">namespace Vendor\Package\Filter\Rule\Sanitize;

class SanitizeHex
{
public function __invoke($subject, $field, $max = null)
{
$value = $subject-&gt;$field;

// must be scalar
if (! is_scalar($value)) {
// sanitizing failed
return false;
}

// strip out non-hex characters
$value = preg_replace('/[^0-9a-f]/i', '', $value);
if ($value === '') {
// failed to sanitize to a hex value
return false;
}

// now check length and chop if needed
if ($max &amp;&amp; strlen($value) &gt; $max) {
$value = substr($value, 0, $max);
}

// retain the sanitized value, and done!
$subject-&gt;$field = $value;
return true;
}
}
</code></pre>
<h2 id="2-7-6-2">2.7.6.2. Set Locator Factories</h2>
<p>Now we set a factory for the rule into the appropriate locator from the <em>FilterFactory</em>. Pass additional <code>$validate_factories</code> and <code>$sanitize_factories</code> to the <em>FilterFactory</em> at construction time; Wrap the rule instantiation logic in a closure so that it is lazy-loaded only when the rule is called:</p>
<pre><code class="language-php">use Aura\Filter\FilterFactory;

$validate_factories = array(
'hex' =&gt; function () { return new Vendor\Package\Filter\Rule\Validate\ValidateHex(); },
);

$sanitize_factories = array(
'hex' =&gt; function () { return new Vendor\Package\Filter\Rule\Sanitize\SanitizeHex(); },
);

$filter_factory = new FilterFactory(
$validate_factories,
$sanitize_factories
);
</code></pre>
<h2 id="2-7-6-3">2.7.6.3. Apply The New Rule</h2>
<p>Finally, we can use the rule in our filters:</p>
<pre><code class="language-php">$filter = $filter_factory-&gt;newSubjectFilter();

// the 'color' field must be a hex value of no more than 6 digits
$filter-&gt;validate('color')-&gt;is('hex', 6);

// force the 'color' field to a hex value of no more than 6 digits
$filter-&gt;sanitize('color')-&gt;to('hex', 6);
</code></pre>
</div>
<nav class="navfooter">
<table>
<tr>
<td class="prev"><a href="/packages/2.x/Filter/sanitize.html">Prev</a></td>
<td class="parent"><a href="/packages/2.x/Filter/">Up</a></td>
<td class="next"><a href="/packages/2.x/Html.html">Next</a></td>
</tr>
<tr>
<td class="prev">2.7.5. Rules To Sanitize Fields</td>
<td class="parent">2.7. Aura.Filter 2.x</td>
<td class="next">2.8. Aura.Html</td>
</tr>
</table>
</nav>
68 changes: 68 additions & 0 deletions packages/2.x/Filter/getting-started.html
@@ -0,0 +1,68 @@
---
layout: site
active: packages
title: Getting Started
permalink: /packages/2.x/Filter/getting-started.html
---
<script>hljs.initHighlightingOnLoad();</script>

<nav class="navheader">
<table>
<tr>
<th colspan="3" class="curr">2.7.1. Getting Started</th>
</tr>
<tr>
<td class="prev"><a href="/packages/2.x/Filter/">Aura.Filter 2.x</a></td>
<td class="parent">2.7. Aura.Filter 2.x</th>
<td class="next"><a href="/packages/2.x/Filter/value-filter.html">Filtering Individual Values</a></td>
</tr>
</table>
</nav>
<div id="section-main"><h1 id="2-7-1">2.7.1. Getting Started</h1>
<h2 id="2-7-1-1">2.7.1.1. Terminology</h2>
<p>Unfortunately, there are not many common terms shared between filtering/validating/etc. libraries. To clear up misconception, this library uses the following definitions:</p>
<ul>
<li>
<p>"filter": validate and/or sanitize one or more fields</p>
</li>
<li>
<p>"validate": determine if a field value conforms to a particular format, but do not modify the field value</p>
</li>
<li>
<p>"sanitize": modify, transform, or otherwise force a field value to conform to a particular format</p>
</li>
</ul>
<p>This library also makes a distinction between a "value" filter and a "subject" filter:</p>
<ul>
<li>
<p>A "value" filter validates and sanitizes an individual value</p>
</li>
<li>
<p>A "subject" filter validates and sanitzes the collection of elements in an array, or the collection of properties in an object. (The "subject" is the array or object.)</p>
</li>
</ul>
<h2 id="2-7-1-2">2.7.1.2. Filter Container</h2>
<p>The easiest way to interact with the filter system is via the <em>FilterFactory</em>. Instantiate it first; you can then get filter objects from it:</p>
<pre><code class="language-php">use Aura\Filter\FilterFactory;

$filter_factory = new FilterFactory();

$filter = $filter_factory-&gt;newValueFilter();
$filter = $filter_factory-&gt;newSubjectFilter();

</code></pre>
</div>
<nav class="navfooter">
<table>
<tr>
<td class="prev"><a href="/packages/2.x/Filter/">Prev</a></td>
<td class="parent"><a href="/packages/2.x/Filter/">Up</a></td>
<td class="next"><a href="/packages/2.x/Filter/value-filter.html">Next</a></td>
</tr>
<tr>
<td class="prev">2.7. Aura.Filter 2.x</td>
<td class="parent">2.7. Aura.Filter 2.x</td>
<td class="next">2.7.2. Filtering Individual Values</td>
</tr>
</table>
</nav>

0 comments on commit c04a7b7

Please sign in to comment.