diff --git a/_bookdown/book/2.x/bookdown.json b/_bookdown/book/2.x/bookdown.json index da1ddb6..b90593b 100644 --- a/_bookdown/book/2.x/bookdown.json +++ b/_bookdown/book/2.x/bookdown.json @@ -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"}, diff --git a/packages/2.x/Accept.html b/packages/2.x/Accept.html index 844cd0f..00569da 100644 --- a/packages/2.x/Accept.html +++ b/packages/2.x/Accept.html @@ -18,7 +18,7 @@ -

2.1. Aura.Accept

+

2.1. Aura.Accept

Provides content-negotiation tools using Accept* headers.

2.1.1. Foreword

2.1.1.1. Installation

@@ -208,7 +208,7 @@

2.1.2.3. Negotiating Other Values

echo $language->getValue(); // pt-BR ?> - +
-

2.2. Aura.Auth

+

2.2. Aura.Auth

Provides authentication functionality and session tracking using various adapters; currently supported adapters are:

-

2.3. Aura.Autoload

+

2.3. Aura.Autoload

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.

@@ -137,7 +137,7 @@

2.3.2.4. Inspection and Debugging

// ) ?> - +
-

2.4. Aura.Cli

+

2.4. Aura.Cli

Provides the equivalent of request ( Context ) and response ( Stdio ) objects for the command line interface, including Getopt support, and an independent Help object for describing commands.

@@ -438,7 +438,7 @@

2.4.2.7. Formatter Cheat Sheet

For example, to set bold white text on a red background, add <<bold white redbg>> into your output or error string. Reset back to normal with <<reset>>.

- +
-

2.5. Aura.Di

+

2.5. Aura.Di

The Aura.Di package provides a dependency injection container system with the following features:

2.5.2.11. Conclusion

If we construct our dependencies properly with params, setters, services, and factories, we will only need to get one object directly from the Container in our bootstrap file. All object creation will then occur within Container itself or the various factory objects. We will never need to use the Container itself in any of our application objects.

- +
-

2.6. Aura.Dispatcher

+

2.6. Aura.Dispatcher

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 @@ -438,18 +438,18 @@

2.6.6. Intercessory Dispatch Methods

echo $result; // "Read blog entry 88" ?> - +
diff --git a/packages/2.x/Filter/custom.html b/packages/2.x/Filter/custom.html new file mode 100644 index 0000000..c996817 --- /dev/null +++ b/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 +--- + + + +

2.7.6. Creating and Using Custom Rules

+

There are three steps to creating and using new rules:

+
    +
  1. +

    Write a rule class, either to validate or sanitize a subject field

    +
    2. +
  2. +

    Set a factory for the class in the appropriate rule locator

    +
    3. +
  3. +

    Use the new rule in a filter specification

    +
    4. +
+

2.7.6.1. Writing a Rule Class

+

Writing a rule class is straightforward. Define a class with an +__invoke($subject, $field) method, along with any additional needed arguments. +The method should return a boolean: true on success, or false on failure.

+

2.7.6.1.1. A Validate Class

+

Here is an example of a hexdecimal validator:

+
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;
+    }
+}
+
+

2.7.6.1.2. A Sanitize Class

+

Here is an example of a hexadecimal sanitizer. Note how we modify the +$subject->$field value directly at the end of the method.

+
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;
+    }
+}
+
+

2.7.6.2. Set Locator Factories

+

Now we set a factory for the rule into the appropriate locator from the FilterFactory. Pass additional $validate_factories and $sanitize_factories to the FilterFactory at construction time; Wrap the rule instantiation logic in a closure so that it is lazy-loaded only when the rule is called:

+
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
+);
+
+

2.7.6.3. Apply The New Rule

+

Finally, we can use the rule in our filters:

+
$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);
+
+
+ diff --git a/packages/2.x/Filter/getting-started.html b/packages/2.x/Filter/getting-started.html new file mode 100644 index 0000000..8831a33 --- /dev/null +++ b/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 +--- + + + +

2.7.1. Getting Started

+

2.7.1.1. Terminology

+

Unfortunately, there are not many common terms shared between filtering/validating/etc. libraries. To clear up misconception, this library uses the following definitions:

+ +

This library also makes a distinction between a "value" filter and a "subject" filter:

+ +

2.7.1.2. Filter Container

+

The easiest way to interact with the filter system is via the FilterFactory. Instantiate it first; you can then get filter objects from it:

+
use Aura\Filter\FilterFactory;
+
+$filter_factory = new FilterFactory();
+
+$filter = $filter_factory->newValueFilter();
+$filter = $filter_factory->newSubjectFilter();
+
+
+
+ diff --git a/packages/2.x/Filter/index.html b/packages/2.x/Filter/index.html new file mode 100644 index 0000000..5335902 --- /dev/null +++ b/packages/2.x/Filter/index.html @@ -0,0 +1,141 @@ +--- +layout: site +active: packages +title: Aura.Filter 2.x +permalink: /packages/2.x/Filter/ +--- + + + + +

2.7. Aura.Filter 2.x

+
+
2.7.1. Getting Started
+
+
2.7.1.1. Terminology
+
2.7.1.2. Filter Container
+
+
2.7.2. Filtering Individual Values
+
+
2.7.2.1. Using A Value Filter
+
2.7.2.2. Using A Static Value Filter
+
+
2.7.3. Filtering Arrays and Objects
+
+
2.7.3.1. Creating A Subject Filter
+
2.7.3.2. Applying The Subject Filter
+
2.7.3.3. Filter Failures
+
2.7.3.4. Failure Modes
+
2.7.3.5. Field-Specific Failure Messages
+
2.7.3.6. Blank Fields
+
2.7.3.7. Extending And Initializing A Subject Filter
+
2.7.3.8. Asserting or Invoking the Filter
+
+
2.7.4. Rules To Validate Fields
+
+
2.7.4.1. alnum
+
2.7.4.2. alpha
+
2.7.4.3. between
+
2.7.4.4. blank
+
2.7.4.5. bool
+
2.7.4.6. callback
+
2.7.4.7. creditCard
+
2.7.4.8. dateTime
+
2.7.4.9. email
+
2.7.4.10. equalToField
+
2.7.4.11. equalToValue
+
2.7.4.12. float
+
2.7.4.13. inKeys
+
2.7.4.14. int
+
2.7.4.15. inValues
+
2.7.4.16. ip
+
2.7.4.17. isbn
+
2.7.4.18. locale
+
2.7.4.19. lowercase
+
2.7.4.20. lowercaseFirst
+
2.7.4.21. max
+
2.7.4.22. min
+
2.7.4.23. regex
+
2.7.4.24. strictEqualToField
+
2.7.4.25. strictEqualToValue
+
2.7.4.26. string
+
2.7.4.27. strlen
+
2.7.4.28. strlenBetween
+
2.7.4.29. strlenMax
+
2.7.4.30. strlenMin
+
2.7.4.31. titlecase
+
2.7.4.32. trim
+
2.7.4.33. upload
+
2.7.4.34. uppercase
+
2.7.4.35. uppercaseFirst
+
2.7.4.36. url
+
2.7.4.37. word
+
+
2.7.5. Rules To Sanitize Fields
+
+
2.7.5.1. alnum
+
2.7.5.2. alpha
+
2.7.5.3. between
+
2.7.5.4. bool
+
2.7.5.5. callback
+
2.7.5.6. dateTime
+
2.7.5.7. field
+
2.7.5.8. float
+
2.7.5.9. int
+
2.7.5.10. isbn
+
2.7.5.11. lowercase
+
2.7.5.12. lowercaseFirst
+
2.7.5.13. max
+
2.7.5.14. min
+
2.7.5.15. now
+
2.7.5.16. remove
+
2.7.5.17. regex
+
2.7.5.18. string
+
2.7.5.19. strlen
+
2.7.5.20. strlenBetween
+
2.7.5.21. strlenMax
+
2.7.5.22. strlenMin
+
2.7.5.23. titlecase
+
2.7.5.24. trim
+
2.7.5.25. uppercase
+
2.7.5.26. uppercaseFirst
+
2.7.5.27. value
+
2.7.5.28. word
+
+
2.7.6. Creating and Using Custom Rules
+
+
2.7.6.1. Writing a Rule Class
+
+
2.7.6.1.1. A Validate Class
+
2.7.6.1.2. A Sanitize Class
+
+
2.7.6.2. Set Locator Factories
+
2.7.6.3. Apply The New Rule
+
+
+
+ diff --git a/packages/2.x/Filter/sanitize.html b/packages/2.x/Filter/sanitize.html new file mode 100644 index 0000000..bb3a44c --- /dev/null +++ b/packages/2.x/Filter/sanitize.html @@ -0,0 +1,161 @@ +--- +layout: site +active: packages +title: Rules To Sanitize Fields +permalink: /packages/2.x/Filter/sanitize.html +--- + + + +

2.7.5. Rules To Sanitize Fields

+

2.7.5.1. alnum

+

Sanitizes to leave only alphanumeric characters.

+
$filter->sanitize('field')->to('alnum');
+
+

2.7.5.2. alpha

+

Sanitizes to leave only alphabetic characters.

+
$filter->sanitize('field')->to('alpha');
+
+

2.7.5.3. between

+

Sanitizes so that values lower than the range are forced up to the minimum, and values higher than the range are forced down to the maximum.

+
$filter->sanitize('field')->to('between', $min, $max);
+
+

2.7.5.4. bool

+

Sanitizes to a strict PHP boolean value. Pseudo-true values include the strings '1', 'y', 'yes', and 'true'; pseudo-false values include the strings '0', 'n', 'no', and 'false'.

+
// sanitize to `true` and `false`
+$filter->sanitize('field')->to('bool');
+
+

You can sanitize to alternative true and false values in place of PHP true and false.

+
// sanitize to alternative true and false values
+$filter->sanitize('field')->to('bool', $value_if_true, $value_if_false);
+
+

2.7.5.5. callback

+

Sanitizes the value using a callable/callback. The callback should take two arguments, $subject and $field, to indicate the subject and the field within that subject. It should return true to pass, or false to fail.

+
$filter->sanitize('field')->to('callback', function ($subject, $field) {
+    // always force the field to 'foo'
+    $subject->$field = 'foo';
+    return true;
+});
+
+
+

N.b.: Always use object notation ($subject->$field) and not array notation ($subject[$field]) in the callable, as the Filter converts arrays to objects on the fly.

+
+

2.7.5.6. dateTime

+

Sanitizes the value to a specified date/time format, default 'Y-m-d H:i:s'.

+
$filter->sanitize('field')->to('dateTime', $format);
+
+

2.7.5.7. field

+

Sanitizes to the value of another field in the subject.

+
$filter->sanitize('field')->to('field', 'other_field_name');
+
+

2.7.5.8. float

+

Sanitizes the value to transform it into a float; for weird strings, this may not be what you expect.

+
$filter->sanitize('field')->to('float');
+
+

2.7.5.9. int

+

Sanitizes the value to transform it into an integer; for weird strings, this may not be what you expect.

+
$filter->sanitize('field')->to('int');
+
+

2.7.5.10. isbn

+

Sanitizes the value to an ISBN (International Standard Book Number).

+
$filter->sanitize('field')->to('isbn');
+
+

2.7.5.11. lowercase

+

Sanitizes the value to all lowercase characters.

+
$filter->sanitize('field')->to('lowercase');
+
+

2.7.5.12. lowercaseFirst

+

Sanitizes the value to begin with a lowercase character.

+
$filter->sanitize('field')->to('lowercaseFirst');
+
+

2.7.5.13. max

+

Sanitizes so that values higher than the maximum are forced down to the maximum.

+
$filter->sanitize('field')->to('max', $max);
+
+

2.7.5.14. min

+

Sanitizes so that values lower than the minimum are forced up to the minimum.

+
$filter->sanitize('field')->to('min', $min);
+
+

2.7.5.15. now

+

Sanitizes the value to force it to the current datetime, default format 'Y-m-d H:i:s'.

+
$filter->sanitize('field')->to('now', $format);
+
+

2.7.5.16. remove

+

Removes the field from the subject with unset().

+
$filter->sanitize('field')->to('remove');
+
+

2.7.5.17. regex

+

Sanitizes the value using preg_replace().

+
$filter->sanitize('field')->to('regex', $expr, $replace);
+
+

2.7.5.18. string

+

Sanitizes the value by casting to a string and optionally using str_replace() to find and replace within the string.

+
$filter->sanitize('field')->to('string', $find, $replace);
+
+

2.7.5.19. strlen

+

Sanitizes the value to cut off longer values at the right, and str_pad() shorter ones.

+
$filter->sanitize('field')->to('strlen', $len[, $pad_string[, $pad_type]]);
+
+

2.7.5.20. strlenBetween

+

Sanitizes the value to truncate values longer than the maximum, and str_pad() +shorter ones.

+
$filter->sanitize('field')->to('strlenBetween', $min, $max[, $pad_string[, $pad_type]]);
+
+

2.7.5.21. strlenMax

+

Sanitizes the value to truncate values longer than the maximum.

+
$filter->sanitize('field')->to('strlenMax', $max);
+
+

2.7.5.22. strlenMin

+

Sanitizes the value to str_pad() values shorter than the minimum.

+
$filter->sanitize('field')->to('strlenMin', $min[, $pad_string[, $pad_type]]);
+
+

2.7.5.23. titlecase

+

Sanitizes the value to titlecase (eg. "Title Case").

+
$filter->sanitize('field')->to('titlecase');
+
+

2.7.5.24. trim

+

Sanitizes the value to trim() it. Optionally specify characters to trim.

+
$filter->sanitize('field')->to('trim', $chars);
+
+

2.7.5.25. uppercase

+

Sanitizes the value to all uppercase characters.

+
$filter->sanitize('field')->to('uppercase');
+
+

2.7.5.26. uppercaseFirst

+

Sanitizes the value to begin with an uppercase character.

+
$filter->sanitize('field')->to('uppercaseFirst');
+
+

2.7.5.27. value

+

Sanitizes to the specified value.

+
$filter->sanitize('field')->to('value', $other_value);
+
+

2.7.5.28. word

+

Sanitizes the value to remove non-word characters.

+
$filter->sanitize('field')->to('word');
+
+
+ diff --git a/packages/2.x/Filter/subject-filter.html b/packages/2.x/Filter/subject-filter.html new file mode 100644 index 0000000..3ac3355 --- /dev/null +++ b/packages/2.x/Filter/subject-filter.html @@ -0,0 +1,245 @@ +--- +layout: site +active: packages +title: Filtering Arrays and Objects +permalink: /packages/2.x/Filter/subject-filter.html +--- + + + +

2.7.3. Filtering Arrays and Objects

+

You can filter an entire object or array (herein called a "subject") by specifying rules for each object property or array element (herein called "fields").

+

2.7.3.1. Creating A Subject Filter

+

First, create a SubjectFilter via the FilterFactory:

+
$filter_factory = new FilterFactory();
+
+$filter = $filter_factory->newSubjectFilter();
+
+

Next, add rule specifications to validate and/or sanitize each subject field:

+
// the username must be alphanumeric
+// but not *only* numeric,
+// at least 6 characters long,
+// and cast it to a string
+$filter->validate('username')->is('alnum');
+$filter->validate('username')->isNot('int');
+$filter->validate('username')->is('strlenMin', 6);
+$filter->sanitize('username')->to('string');
+
+// the password must be at least 6 characters long, and must match a
+// confirmation field
+$filter->validate('password')->is('strlenMin', 6);
+$filter->validate('password_confirm')->is('equalToField', 'password');
+
+

We can call one of the following methods after validate():

+ +

We can call one of the following methods after sanitize():

+ +

For more about blanks, see the section on Blank Fields.

+

2.7.3.2. Applying The Subject Filter

+

We can then apply the filter specifications to the subject. A true result +means all the rules passed, while false means one or more failed.

+
// the data to be filtered; could also be an object
+$subject = array(
+    'username' => 'bolivar',
+    'password' => 'p@55w0rd',
+    'password_confirm' => 'p@sword', // not the same!
+);
+
+// filter the object and see if there were failures
+$success = $filter->apply($subject);
+if (! $success) {
+    // get the failures
+    $failures = $filter->getFailures();
+    var_dump($failures->getMessages());
+}
+
+

2.7.3.3. Filter Failures

+

When we get the failures via getFailures(), we can examine in detail which fields failed, and what the failure messages were. The getFailures() method returns a FailureCollection (essentially an ArrayObject keyed on the field names). Each field in the FailureCollection has an array of Failure objects, each with these methods:

+ +

These can be combined in various ways to generate output regarding the filter failures.

+

2.7.3.4. Failure Modes

+

Normally, the filter will stop filtering any field that fails one of +its rules, but will continue applying rules to the rest of the fields. Also, +the filter specification will provide a default message when a rule fails.

+

We can modify that behavior by specifying a failure mode, with an optional +custom message:

+ +

In each case, the custom message will be used instead of the default one for +the specified rule. If we want to just set a custom message without changing +the failure mode, we can use $filter->...->setMessage('custom message').

+

2.7.3.5. Field-Specific Failure Messages

+

If a field fails multiple rules, there will be multiple failure messages (one for each failed rule). To specify a single failure message for a field, regardless of which rule(s) it fails, call $filter->useFieldMessage():

+
$filter->validate('field')->isNot('blank')->asSoftRule();
+$filter->validate('field')->is('alnum')->asSoftRule();
+$filter->validate('field')->is('strlenMin', 6)->asSoftRule();
+$filter->validate('field')->is('strlenMax', 12)->asSoftRule();
+
+$filter->useFieldMessage('field', 'Please use 6-12 alphanumeric characters.');
+
+

2.7.3.6. Blank Fields

+

This library incorporates the concept of "blank" fields, as distinct from +isset() and empty(), to allow for input elements that are missing or have +not been filled in. A field is blank if it is:

+ +

Integers, floats, booleans, resources, arrays, and objects are never "blank" +even if they evaluate to zero or are empty:

+
$not_blank = array(
+    0,                // integer
+    0.00,             // float
+    false,            // boolean false
+    array(),          // empty array
+    new StdClass,     // an object
+);
+
+

Generally, a blank field will fail to validate. To allow a validate rule to pass +even if the field is blank, call isBlankOr() or isBlankOrNot() on its rule +specification:

+
// either an alphanumeric value *or* a blank value will validate
+$filter->validate('field')->isBlankOr('alnum');
+
+

Likewise, a blank field may fail to sanitize properly. To allow for a blank +field with a sanitize rule, call toBlankOr() on its rule specification:

+
// both an alphanumeric field *and* a blank field will pass
+$filter->sanitize('field')->toBlankOr('alnum');
+
+

This will cause blank values to be sanitized to null, and non-blank values +to be sanitized using the alnum rule.

+

Finally, if we want blank values to be sanitized to something other than +null, call useBlankValue() to specify the value to use when blank:

+
// both an alphanumeric field *and* a blank field will pass
+$filter->sanitize('field')->toBlankOr('alnum')->useBlankValue('');
+
+

That will cause blank values to be sanitized to an empty string. Additionally, +please note that useBlankValue() implies toBlankOr(), so the following has +the same effect as the above:

+
// both an alphanumeric field *and* a blank field will pass
+$filter->sanitize('field')->to('alnum')->useBlankValue('');
+
+

2.7.3.7. Extending And Initializing A Subject Filter

+

Sometimes it may be useful to extend the Filter class for a specific purpose, one that can initialize itself. This can be useful when filtering a specific kind of object or dataset.

+

To do so, override the the init() method on the extended Filter class; the above examples remain instructive, but use $this instead of $filter since you are working from inside the filter object:

+
namespace Vendor\Package;
+
+use Aura\Filter\SubjectFilter;
+
+class EntityFilter extends SubjectFilter
+{
+    protected function init()
+    {
+        $this->validate('field')->isNot('blank')->asSoftRule();
+        $this->validate('field')->is('alnum')->asSoftRule();
+        $this->validate('field')->is('strlenMin', 6)->asSoftRule();
+        $this->validate('field')->is('strlenMax', 12)->asSoftRule();
+
+        $this->useFieldMessage('field', 'Please use 6-12 alphanumeric characters.');
+    }
+}
+
+

You can then create a new instance of your extended filter class through the FilterFactory:

+
$entity_filter = $filter_factory->newSubjectFilter('Vendor\Package\EntityFilter');
+$success = $entity_filter->apply($entity);
+
+

2.7.3.8. Asserting or Invoking the Filter

+

Whereas calling $filter->apply($subject) returns a boolean, calling $filter->assert($subject) returns null on success, and throws an exception on failure. (Invoking the filter as a callable a la $filter($subject) works the same as assert().)

+
use Aura\Filter\Exception\FilterFailed;
+
+// the data to be filtered; could also be an object
+$subject = array(
+    'username' => 'bolivar',
+    'password' => 'p@55w0rd',
+    'password_confirm' => 'p@55word', // not the same!
+);
+
+// filter the object and see if there were failures
+try {
+    $filter($subject);
+} catch (FilterFailed $e)
+    // ...
+}
+
+

The FilterFailed exception has these methods in addition to the normal Exception methods:

+ +
+ diff --git a/packages/2.x/Filter/validate.html b/packages/2.x/Filter/validate.html new file mode 100644 index 0000000..6909b5f --- /dev/null +++ b/packages/2.x/Filter/validate.html @@ -0,0 +1,205 @@ +--- +layout: site +active: packages +title: Rules To Validate Fields +permalink: /packages/2.x/Filter/validate.html +--- + + + +

2.7.4. Rules To Validate Fields

+

2.7.4.1. alnum

+

Validates the value as alphanumeric only.

+
$filter->validate('field')->is('alnum');
+
+

2.7.4.2. alpha

+

Validates the value as alphabetic only.

+
$filter->validate('field')->is('alpha');
+
+

2.7.4.3. between

+

Validates the value as being within or equal to a minimum and maximum value.

+
$filter->validate('field')->is('between', $min, $max);
+
+

2.7.4.4. blank

+

Validates the value as being blank.

+
$filter->validate('field1')->isBlank();
+$filter->validate('field2')->isBlankOr('strlen', 3);
+$filter->validate('field3')->isBlankOrNot('strlen', 3);
+
+

To validate the value as not being blank.

+
$filter->validate('field')->isNotBlank();
+
+

2.7.4.5. bool

+

Validates the value as being a boolean, or a pseudo-boolean. Pseudo-true values include the strings '1', 'y', 'yes', and 'true'; pseudo-false values include the strings '0', 'n', 'no', and 'false'.

+
$filter->validate('field')->is('bool');
+
+

2.7.4.6. callback

+

Validates the value using a callable/callback. The callable should take two arguments, $subject and $field, to indicate the subject and the field within that subject. It should return true to pass, or false to fail.

+
$filter->validate('field')->is('callback', function ($subject, $field) {
+    if ($subject->$field === 'foo') {
+        return true;
+    }
+    return false;
+});
+
+
+

N.b.: Always use object notation ($subject->$field) and not array notation ($subject[$field]) in the closure, as the Filter converts arrays to objects on the fly.

+
+

2.7.4.7. creditCard

+

Validates the value as being a credit card number.

+
$filter->validate('field')->is('creditCard');
+
+

2.7.4.8. dateTime

+

Validates the value as representing a date and/or time.

+
$filter->validate('field')->is('dateTime');
+
+

2.7.4.9. email

+

Validates the value as being a properly-formed email address per the various relevant RFCs. If the intl extension is loaded, it will also allow for international domain names.

+
$filter->validate('field')->is('email');
+
+

2.7.4.10. equalToField

+

Validates the value as loosely equal (==) to the value of another +field in the subject.

+
$filter->validate('field')->is('equalToField', 'other_field_name');
+
+

2.7.4.11. equalToValue

+

Validates the value as loosely equal (`==') to a specified value.

+
$filter->validate('field')->is('equalToValue', $other_value);
+
+

2.7.4.12. float

+

Validates the value as representing a float.

+
$filter->validate('field')->is('float');
+
+

2.7.4.13. inKeys

+

Validates that the value is loosely equal (==) to a key in a given array.

+
$filter->validate('field')->is('inKeys', $array);
+
+

2.7.4.14. int

+

Validates the value as representing an integer.

+
$filter->validate('field')->is('int');
+
+

2.7.4.15. inValues

+

Validates that the value is strictly equal (===) to a value in a given array.

+
$filter->validate('field')->is('inValues', $array);
+
+

2.7.4.16. ip

+

Validates the value as an IPv4 or IPv6 address, allowing reserved and private addresses.

+
$filter->validate('field')->is('ip');
+
+

To modify restrictions on the filter, pass the appropriate FILTER_FLAG_* constants (seen here) as a second parameter.

+
// only allow IPv4 addresses in the non-private range.
+$filter->validate('field')->is('ip', FILTER_FLAG_IPV4 | FILTER_FLAG_NO_PRIV_RANGE);
+
+// only allow IPv6 addresses in non-reserved range.
+$filter->validate('field')->is('ip', FILTER_FLAG_IPV6 | FILTER_FLAG_NO_RES_RANGE);
+
+

2.7.4.17. isbn

+

Validates the value is a correct ISBN (International Standard Book Number).

+
$filter->validate('field')->is('isbn');
+
+

2.7.4.18. locale

+

Validates the given value against a list of locale strings (internal to the rule class).

+
$filter->validate('field')->is('locale');
+
+

2.7.4.19. lowercase

+

Validates the value as all lowercase.

+
$filter->validate('field')->is('lowercase');
+
+

2.7.4.20. lowercaseFirst

+

Validates the value begins with a lowercase character.

+
$filter->validate('field')->is('lowercaseFirst');
+
+

2.7.4.21. max

+

Validates the value as being less than or equal to a maximum.

+
$filter->validate('field')->is('max', $max);
+
+

2.7.4.22. min

+

Validates the value as being greater than or equal to a minimum.

+
$filter->validate('field')->is('min', $min);
+
+

2.7.4.23. regex

+

Validates the value using preg_match().

+
$filter->validate('field')->is('regex', $expr);
+
+

2.7.4.24. strictEqualToField

+

Validates the value as strictly equal (===) to the value of another field in the subject.

+
$filter->validate('field')->is('strictEqualToField', 'other_field_name');
+
+

2.7.4.25. strictEqualToValue

+

Validates the value as strictly equal (===) to a specified value.

+
$filter->validate('field')->is('strictEqualToValue', $other_value);
+
+

2.7.4.26. string

+

Validates the value can be represented by a string.

+
$filter->validate('field')->is('string');
+
+

2.7.4.27. strlen

+

Validates the value has a specified length.

+
$filter->validate('field')->is('strlen', $len);
+
+

2.7.4.28. strlenBetween

+

Validates the value as being within or equal to a minimum and maximum length.

+
$filter->validate('field')->is('strlenBetween', $min, $max);
+
+

2.7.4.29. strlenMax

+

Validates the value length as being no longer than a maximum.

+
$filter->validate('field')->is('strlenMax', $max);
+
+

2.7.4.30. strlenMin

+

Validates the value length as being no shorter than a minimum.

+
$filter->validate('field')->is('strlenMin', $min);
+
+

2.7.4.31. titlecase

+

Validates the value as title case

+
$filter->validate('field')->is('titlecase');
+
+

2.7.4.32. trim

+

Validates the value is trim()med. Optionally specify characters to trim.

+
$filter->validate('field')->is('trim', $chars);
+
+

2.7.4.33. upload

+

Validates the value represents a PHP upload information array, and that the file is an uploaded file.

+
$filter->validate('field')->is('upload');
+
+

2.7.4.34. uppercase

+

Validates the value as all uppercase.

+
$filter->validate('field')->is('uppercase');
+
+

2.7.4.35. uppercaseFirst

+

Validates the value begins with an uppercase character.

+
$filter->validate('field')->is('uppercaseFirst');
+
+

2.7.4.36. url

+

Validates the value is a well-formed URL.

+
$filter->validate('field')->is('url');
+
+

2.7.4.37. word

+

Validates the value as being composed only of word characters.

+
$filter->validate('field')->is('word');
+
+
+ diff --git a/packages/2.x/Filter/value-filter.html b/packages/2.x/Filter/value-filter.html new file mode 100644 index 0000000..a5f6a48 --- /dev/null +++ b/packages/2.x/Filter/value-filter.html @@ -0,0 +1,108 @@ +--- +layout: site +active: packages +title: Filtering Individual Values +permalink: /packages/2.x/Filter/value-filter.html +--- + + + +

2.7.2. Filtering Individual Values

+

You can filter an individual value by using a ValueFilter.

+

2.7.2.1. Using A Value Filter

+

First, create a ValueFilter object from the FilterFactory:

+
$filter = $filter_factory->newValueFilter();
+
+

Then, to apply the filter, call its validate() and sanitize() methods. Supply the variable to be filtered, along with a rule name and any arguments for the rule. (These methods return true to indicate success, or false to indicate failure.)

+
// the username must be alphanumeric,
+// but not *only* numeric,
+// between 6 and 10 characters long,
+// and cast it to a string
+$ok = $filter->validate($username, 'alnum')
+   && ! $filter->validate($username, 'int')
+   && $filter->validate($username, 'strlenBetween', 6, 10)
+   && $filter->sanitize($username, 'string');
+if (! $ok) {
+    echo "The username is not valid.";
+}
+
+// the password must be at least 6 characters long, and must match a
+// confirmation field
+$ok = $filter->validate($password, 'strlenMin', 6)
+   && $filter->validate($password, 'equalToValue', $password_confirm);
+if (! $ok) {
+    echo "The password is not valid.";
+}
+
+

Note that while validate() will not change the value being filtered, sanitize() will modify the value (thus sanitizing it).

+

2.7.2.2. Using A Static Value Filter

+

In general, the Aura project avoids using statics, and recommends against them in all but the most limited cases. However, some developers are fine with the tradeoffs of using globally-available static methods. For these developers, this package provides an abstract implementation that acts as a static proxy to a ValueFilter instance.

+

To use a static value filter, first extend the AbstractStaticFilter with your own class name; this helps to deconflict between different static filters:

+
use Aura\Filter\AbstractStaticFilter;
+
+class MyStaticFilter extends AbstractStaticFilter
+{
+}
+
+

Then pass a new ValueFilter into your static proxy class:

+
MyStaticFilter::setInstance($filter_factory->newValueFilter());
+
+
+

N.b.: You can set the instance only once; further calls will throw an exception.

+
+

Now you can use the static proxy as a global:

+
use MyStaticFilter as Filter;
+
+class CreateUserCommand
+{
+    protected $username;
+    protected $password;
+
+    public function __construct($username, $password, $password_confirm)
+    {
+        $ok = Filter::validate($username, 'alnum')
+           && ! Filter::validate($username, 'int')
+           && Filter::validate($username, 'strlenBetween', 6, 10)
+           && Filter::sanitize($username, 'string');
+
+        if (! $ok) {
+            throw new Exception("The username is not valid.");
+        }
+
+        $ok = Filter::validate($password, 'strlenMin', 6)
+           && Filter::validate($password, 'equalToValue', $password_confirm);
+        if (! $ok) {
+            throw new Exception("The password is not valid.");
+        }
+
+        $this->username = $username;
+        $this->password = $password;
+    }
+}
+
+
+ diff --git a/packages/2.x/Html.html b/packages/2.x/Html.html index 924e23f..97746e3 100644 --- a/packages/2.x/Html.html +++ b/packages/2.x/Html.html @@ -12,13 +12,13 @@ 2.8. Aura.Html - Aura.Filter + Creating and Using Custom Rules 2. Version 2.x Aura.Includer -

2.8. Aura.Html

+

2.8. Aura.Html

Provides HTML escapers and helpers, including form input helpers, that can be used in any template, view, or presentation system.

2.8.1. Foreword

2.8.1.1. Installation

@@ -207,16 +207,16 @@

2.8.2.3. Escaping

</body> - +
-

2.9. Aura.Includer

+

2.9. Aura.Includer

Provides a facility to include multiple files from specified directories, in order, with variables extracted into a limited include scope.

2.9.1. Foreword

@@ -237,7 +237,7 @@

2.9.2.7. Debugging

Sometimes it will be useful to see what files the Includer actually found. Use the getDebug() method to return an array of information about what the Includer found, in what order, and in what mode.

- +
-

2.10. Aura.Router

+

2.10. Aura.Router

Provides a web router implementation: given a URL path and a copy of $_SERVER, it will extract path-info and $_SERVER values for a specific route.

@@ -714,7 +714,7 @@

2.10.3.11. As a Micro-Framework

With the above example action, the URL /blog/read/1.json will send JSON ouput, but for /blog/read/1 it will send plain text output.

- +
-

2.11. Aura Session

+

2.11. Aura Session

Provides session management functionality, including lazy session starting, session segments, next-request-only ("flash") values, and CSRF tools.

2.11.1. Foreword

@@ -30,7 +30,7 @@

2.11.1.2. Quality

Scrutinizer Code Quality Code Coverage Build Status

-

To run the unit tests at the command line, issue composer install and then phpunit at the package root. This requires Composer to be available as composer, and PHPUnit to be available as phpunit.

+

To run the unit tests at the command line, issue composer install and then vendor/bin/phpunit at the package root. This requires Composer to be available as composer.

This library attempts to comply with PSR-1, PSR-2, and PSR-4. If you notice compliance oversights, please send a patch via pull request.

2.11.1.3. Community

@@ -254,7 +254,7 @@

2.11.3.3. Session Lifetime

N.b: The setCookieParams method calls session_set_cookie_params internally.

- +
-

2.12. Aura.Sql

+

2.12. Aura.Sql

Provides an extension to the native PDO along with a profiler and connection locator. Because ExtendedPdo is an extension of the native PDO, code already using the native PDO or typehinted to the native @@ -507,7 +507,7 @@

2.12.4.1. Construction-Time Configuration

$connections = new ConnectionLocator($default, $read, $write); ?> - +
-

2.13. Aura.SqlQuery

+

2.13. Aura.SqlQuery

Provides query builders for MySQL, Postgres, SQLite, and Microsoft SQL Server. These builders are independent of any particular database connection library, although PDO in general is recommended.

@@ -620,7 +620,7 @@

2.13.9. Table Prefixes

result of the hard trials of experience. For those of you who want modifiable table prefixes, we suggest using constants with your table names prefixed as desired; as the prefixes change, you can then change your constants.

- +
-

2.14. Aura.SqlSchema

+

2.14. Aura.SqlSchema

Provides facilities to read table names and table columns from a database using a PDO connection.

2.14.1. Foreword

@@ -108,7 +108,7 @@

2.14.2.3. Fetching Column Information

primary: (bool) Is the column part of the primary key?

- +
-

2.15. Aura View

+

2.15. Aura View

This package provides an implementation of the TemplateView and TwoStepView patterns using PHP itself as the templating language. It supports both file-based and closure-based templates along with helpers and sections.

It is preceded by systems such as @@ -350,7 +350,7 @@

2.15.2.14. Advanced Configuration

$layout_registry = $view->getLayoutRegistry(); $layout_registry->set('default', '/path/to/layouts/default.php'); - +
-

2.16. Aura.Web

+

2.16. Aura.Web

Provides web Request and Response objects for use by web controllers and actions. These are representations of the PHP web environment, not HTTP request and response objects proper.

@@ -122,7 +122,7 @@

2.16.2.2. Request and Response Objects

prefer, including plain PHP.

Be sure to read the Request and Response pages for more detailed information.

- +
-

1.1.9. Auto-Resolution Of Constructor Parameters

+

1.1.9. Auto-Resolution Of Constructor Parameters

Some developers prefer to let the Container resolve dependencies on its own, without having to specify anything in a configuration file. Note that there can be unusual debugging problems inherent in tracking down the default injections, so auto-resolution may or may not be your preference.

To use auto-resolution in a Container, build the Container with $container = $builder->newInstance($builder::AUTO_RESOLVE).

Note that auto-resolution only works for class/interface typehints. It does not work for array typehints.

@@ -86,7 +86,7 @@

1.1.9.4. Overriding Auto-Resolution

// resolve to this other service $di->params['OtherClass']['db'] = $di->lazyGet('other_connection'); - +
-

1.1.8. Container Builder and Config Classes

+

1.1.8. Container Builder and Config Classes

The ContainerBuilder also builds fully-configured Container objects using ContainerConfig classes. It works using a two-stage configuration system.

The two stages are "define" and "modify". In the "define" stage, the ContainerConfig object defines constructor parameter values, setter method values, services, and so on. The ContainerBuilder then locks the Container so that these definitions cannot be changed, and begins the "modify" stage. In the "modify" stage, we may get() services from the Container and modify them programmatically if needed.

To build a fully-configured Container using the ContainerBuilder, we do something like the following:

@@ -81,7 +81,7 @@

1.1.8. Container Builder and Config Classes

'Aura\Web\_Config\Common', ]); - +
-

1.1.2. Constructor Injection

+

1.1.2. Constructor Injection

When we use the Container to instantiate a new object, we often need to inject (i.e., set) constructor parameter values in various ways.

We can define default values for constructor parameters using the $di->params array on the Container before locking it.

Let's look at a class that takes some constructor parameters:

@@ -48,7 +48,7 @@

1.1.2. Constructor Injection

N.b.: If you try to access $params after calling newInstance() (or after locking the Container using the lock() method) the Container will throw an exception. This is to prevent modifying the params after objects have been created. Thus, be sure to set up all params for all objects before creating an object.

- +
-

1.1.7. Instance Factories

+

1.1.7. Instance Factories

Occasionally, a class will need to receive not just an instance, but a factory that is capable of creating a new instance over and over. For example, say we have a class like the following:

class ExampleNeedsFactory
 {
@@ -51,7 +51,7 @@ 
1.1.7. Instance Factories

Note that the arguments passed to the factory __invoke() method will be passed to the underlying instance constructor sequentially, not by name. This means the __invoke() method works more like the native new keyword, and not like $di->lazyNew(). These arguments override any $di->params values that have been set for the class being factoried; without the overrides, all existing $di->params values for that class will be honored. (Values from $di->setter for the class will also be honored, but cannot be overridden.)

Do not feel limited by the Factory implementation. We can create and inject factory objects of our own if we like. The Factory returned by the $di->newFactory() method is an occasional convenience, nothing more.

- +
-

1.1.1. Getting Started

+

1.1.1. Getting Started

1.1.1.1. Overview

The Aura.Di package provides a serializable dependency injection container with the following features:

@@ -78,7 +78,7 @@

1.1.1.3. Creating Object Instances

N.b.: The Container locks itself once a new instance is produced; this ensures that the Container configuration cannot be modified once objects have been created.

However, this is a relatively naive way to create objects with the Container. It is better to specify the various constructor parameters, setter methods, and so on, and let the Container inject those values for us only when the object is used as a dependency for something else.

- +
-

1.1.4. Class, Interface, and Trait Inheritance

+

1.1.4. Class, Interface, and Trait Inheritance

N.b.: When specifying fully-qualified class names, do not include the leading namespace separator. Doing so may lead to unexpected behavior. In other words, always use ClassName and never use \ClassName.

@@ -96,7 +96,7 @@

1.1.4.2. Interface And Trait Inheritance

When we call $di->newInstance('Example'), those setter methods will be called by the Container with those values.

Note that if we have class-specific $di->setter values, those will take precedence over the trait and interface setter values.

- +
-

1.1.6. Lazy Injection

+

1.1.6. Lazy Injection

Unlike the newInstance() and get() methods, calling one of the lazy*() methods on the Container will not lock the Container. Using lazy injection is the preferred and recommended way to defines object values for $params and $setters, and to define services.

1.1.6.1. Lazy Instances

Thus far, we have used newInstance() to create objects through the Container. @@ -165,7 +165,7 @@

1.1.6.7. Generic Lazy Calls

));

Beware of relying on generic Lazy calls too much; if we do, it probably means we need to separate our configuration concerns better than we are currently doing.

- +
-

1.1.10. Migrating from 2.x to 3.x

+

1.1.10. Migrating from 2.x to 3.x

Aura.Di 3.x is largely similar to 2.x, but there are some backwards-compatibility breaks, as well as some new features.

1.1.10.1. BC Breaks

1.1.10.1.1. Instantiation

@@ -66,7 +66,7 @@

1.1.10.2.1. lazyGetCall()

Here the value assigned to matcher is taken from the RouterContainer getMatcher() method.

1.1.10.2.2. Instance Factories

An instance factory creates multiple instances of the same class; refer the docs for more information.

- +
-

1.1.5. Services

+

1.1.5. Services

A "service" is an object stored in the Container under a unique name. Any time you get() the named service, you always get back the same object instance.

// define the Example class
 class Example
@@ -39,7 +39,7 @@ 
1.1.5. Services

 

 
N.b.: If you try to access $params or $setters, or to call set(), after calling get() or after locking the Container using the lock() method, the Container will throw an exception. This is to prevent modifying the params after objects have been created. Thus, be sure to set up all params for all objects before creating an object.

 

-
+
-

1.1.3. Setter Injection

+

1.1.3. Setter Injection

The Container supports setter injection in addition to constructor injection. (These can be combined as needed.)

After the Container constructs a new instance of an object, we can specify that certain methods should be called with certain values immediately after instantiation by using the $di->setter array before locking it.

Say we have class like the following:

@@ -41,7 +41,7 @@

1.1.3. Setter Injection

N.b.: If you try to access $setters after calling newInstance() (or after locking the Container using the lock() method) the Container will throw an exception. This is to prevent modifying the params after objects have been created. Thus, be sure to set up all params for all objects before creating an object.

- +
-

1.2. Aura.Intl

+

1.2. Aura.Intl

The Aura.Intl package provides internationalization (I18N) tools, specifically package-oriented per-locale message translation.

1.2.1. Getting Started

@@ -197,7 +197,7 @@

1.2.6. Pluralized Messages

Note that you can use other tokens within a pluralized token string to build more complex messages. For more information, see the following:

http://icu-project.org/apiref/icu4j/com/ibm/icu/text/MessageFormat.html

- +
-

1.3. Aura.Payload

+

1.3. Aura.Payload

You use a Payload as a data transfer object to send domain-layer results to your user-interface layer, along with meta-data indicating the meaning of the domain results.

@@ -336,7 +336,7 @@

1.3.4. Example

} ?> - +
-

1.4.3. Attaching Route Groups

+

1.4.3. Attaching Route Groups

You can add a series of routes under a single master path in the Map using the Map::attach() method with a name prefix, path prefix, and a callable to perform the attachment logic. The callable must take a Map as its only argument.

For example, if you want all your blog-related routes to be mounted at /blog in your application, and all of their names to be prefixed with blog., you can do the following:

<?php
@@ -63,7 +63,7 @@ 
1.4.3. Attaching Route Groups

 
 
 
Any defaults you set on the $map inside the callable will revert to their previous values when the callable is complete.

-
+
-

1.4.5. Building Custom Maps and Routes

+

1.4.5. Building Custom Maps and Routes

1.4.5.1. Extending the Map Class

You might want to extend the Map class to provide convenience methods specific to your application. As with writing a custom matching rule, this is a bit involved but not difficult:

    @@ -154,7 +154,7 @@

    1.4.5.3. Automated Route Caching and Building

    N.b.: If there are closures in the Route objects (e.g. in the handlers), you will not be able to serialize the routes for caching. This is because closures cannot be serialized by PHP. Consider using non-closure callables instead.

    Now when you call $routerContainer->getMap(), the container will automatically call the map-builder logic and apply it to the $map before returning it.

    - +
-

1.4.6. Custom Matching Rules

+

1.4.6. Custom Matching Rules

1.4.6.1. Writing A Custom Rule

Writing a custom matching rule, say one that checks the authentication state, is a bit involved but not difficult.

    @@ -106,7 +106,7 @@

    1.4.6.2. Setting Rules

    new Rule\Allows(), ]);     - +
-

1.4.2. Defining Routes

+

1.4.2. Defining Routes

Every time you add a route to the Map, you get back a Route object. The Route object is pretty powerful, and allows you to define a wide range of matching conditions. All of the Route methods are fluent, so you can chain them together.

1.4.2.1. Placeholder Tokens and Default Values

When you add a {token} placeholer in the path, it uses a default regular expression of ([^/]+). Essentially, this matches everything except a slash, which of course indicates the next path segment.

@@ -220,7 +220,7 @@

1.4.2.13. Default Map Route Specifications

$map->delete('blog.delete', '/blog/{id}'); ?> - +
-

1.4.4. Generating Paths From Routes

+

1.4.4. Generating Paths From Routes

To generate a path from a route so that you can create links, first retrieve the Generator from the RouterContainer.

<?php
 $generator = $routerContainer->getGenerator();
@@ -67,7 +67,7 @@ 
1.4.4.2. Wildcard Attributes

 ]); // "/post/88/foo/bar/baz"
 ?>
- +
-

1.4.1. Getting Started

+

1.4.1. Getting Started

Aura.Router is a web router implementation for PSR-7.

You get all the router objects through a library-specific RouterContainer, which manages object creation, dependencies, and wiring for you. That means you need to instantiate the container before anything else.

<?php
@@ -216,7 +216,7 @@ 
1.4.1.5. Working Example

 
$ php -S localhost:8000 -t .
 

 
... and point your browser to http://localhost:8000/blog/12 .

-
+
-

1.4.7. Other Topics

+

1.4.7. Other Topics

1.4.7.1. Catchall Routes

You can use optional placeholder tokens to create a generic catchall route:

<?php
@@ -103,7 +103,7 @@ 
1.4.7.4. Route Helpers

     'slug' => 'my title'
 ]); // "/path/to/subdir/blog/my title"
- +
-

1.5.5. Connection Locator

+

1.5.5. Connection Locator

Frequently, high-traffic PHP applications use multiple database servers, generally one for writes, and one or more for reads. The ConnectionLocator allows you to define multiple ExtendedPdo objects for lazy-loaded read and @@ -153,7 +153,7 @@

1.5.5.2. Construction-Time Configuration

// configure locator at construction time $connections = new ConnectionLocator($default, $read, $write); - +
-

1.5.2. The fetch*() Methods

+

1.5.2. The fetch*() Methods

ExtendedPdo comes with fetch*() methods to help reduce boilerplate code. Instead of issuing prepare(), a series of bindValue() calls, execute(), and then fetch*() on a PDOStatement, you can bind values and fetch results @@ -74,7 +74,7 @@

1.5.2. The fetch*() Methods

$stm = "UPDATE test SET incr = incr + 1 WHERE foo = :foo AND bar = :bar"; $row_count = $pdo->fetchAffected($stm, $bind); - +
-

1.5.1. Getting Started

+

1.5.1. Getting Started

1.5.1.1. Instantiation

You can instantiate ExtendedPdo so that it uses lazy connection, or you can use DecoratedPdo to decorate an existing PDO instance.

@@ -127,7 +127,7 @@

1.5.1.3. The perform() Method

Finally, note that array quoting works only via the perform() method, not on returned PDOStatement instances.

- +
-

1.5.4. Profiling and Logging

+

1.5.4. Profiling and Logging

It is often useful to see what queries have been executed, where they were issued from in the codebase, and how long they took to complete. As such, ExtendedPdo comes with a profiler that logs to any PSR-3 implementation. @@ -91,7 +91,7 @@

1.5.4.4. Profiler Log Level

$pdo->getProfiler()->setLogLevel(LogLevel::INFO);

Likewise, you can get the current log level with Profiler::getLogLevel().

- +
-

1.5.6. 3.x Upgrade Notes

+

1.5.6. 3.x Upgrade Notes

The vast majority of changes and breaks from the 2.x version are "under the hood," so to speak. The main functionality methods (query(), exec(), perform(), fetch*(), yield*(), etc.) are unchanged and work just the same @@ -201,7 +201,7 @@

1.5.6.4. Miscellaneous

should help keep unexpected output of stack traces from revealing credentials.

- +
-

1.5.3. The yield*() Methods

+

1.5.3. The yield*() Methods

ExtendedPdo comes with yield*() methods to help reduce memory usage. Whereas many fetch*() methods collect all the query result rows before returning them all at once, the equivalent yield*() methods generate one result row at a @@ -56,7 +56,7 @@

1.5.3. The yield*() Methods

// ... } - +