Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
update packages and fix the filter documentation
- Loading branch information
Showing
55 changed files
with
1,273 additions
and
106 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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->$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 && strlen($value) > $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->$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->$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 && strlen($value) > $max) { | ||
$value = substr($value, 0, $max); | ||
} | ||
|
||
// retain the sanitized value, and done! | ||
$subject->$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' => function () { return new Vendor\Package\Filter\Rule\Validate\ValidateHex(); }, | ||
); | ||
|
||
$sanitize_factories = array( | ||
'hex' => 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->newSubjectFilter(); | ||
|
||
// the 'color' field must be a hex value of no more than 6 digits | ||
$filter->validate('color')->is('hex', 6); | ||
|
||
// force the 'color' field to a hex value of no more than 6 digits | ||
$filter->sanitize('color')->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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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->newValueFilter(); | ||
$filter = $filter_factory->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> |
Oops, something went wrong.