traderinteractive/filter-strings

A filtering implementation for verifying strings

v4.1.0 2024-11-15 13:40 UTC

Requires

• php: ^7.3 || ^8.0
• traderinteractive/exceptions: ^2.0

Requires (Dev)

• ext-dom: *
• ext-json: *
• ext-libxml: *
• ext-simplexml: *
• phpunit/phpunit: ^9.0
• squizlabs/php_codesniffer: ^3.2

Suggests

• ext-SimpleXML: Required for XML filters
• ext-dom: Required for XML validation filters
• ext-json: Required for JSON filters
• ext-libxml: Required for XML validation filters

MIT

• email
• url
• utility
• string
• strings

README

A filtering implementation for verifying the contents of strings and some common formats of strings.

Requirements

Requires PHP 7.0 or newer and uses composer to install further PHP dependencies. See the composer specification for more details.

Installation

filter-strings-php can be installed for use in your project using composer. The recommended way of using this library in your project is to add a composer.json file to your project. The following contents would add filter-strings-php as a dependency:

composer require traderinteractive/filter-strings

Functionality

Strings::filter

This filter verifies that the argument is a string. The second parameter can be set to true to allow null values through without an error (they will stay null and not get converted to false). The last parameters specify the length bounds of the string. The default bounds are 1+, so an empty string fails by default.

The following checks that $value is a non-empty string.

\TraderInteractive\Filter\Strings::filter($value);

Strings::concat

This filter concatenates the given $value, $prefix and $suffix and returns the resulting string.

$value = \TraderInteractive\Filter\Strings::concat('middle', 'begining_', '_end');
assert($value === 'begining_middle_end');

Strings::translate

This filter will accept a string value and return its translated value found in the given $valueMap.

$value = \TraderInteractive\Filter\Strings::translate('active', ['inactive' => 'X', 'active' => 'A']);
assert($value === 'A');

Strings::explode

This filter is essentially a wrapper around the built-in explode method with the value first in order to work with the Filterer. It also defaults to using , as a delimiter. For example:

$value = \TraderInteractive\Filter\Strings::explode('abc,def,ghi');
assert($value === ['abc', 'def', 'ghi']);

Strings::compress

This filter trims and remove superfluous whitespace from a given string.

$value = \TraderInteractive\Filter\Strings::compress(' a string    with lots of    whitespace   ');
assert($value === 'a string with lots of whitespace');

This filter can also replace vertical whitespace such as newlines with single spaces.

$value = \TraderInteractive\Filter\Strings::compress(" a string\nwith lots\nof    \nnewlines\n   ", true);
assert($value === 'a string with lots of newlines');

Strings::redact

This filter will remove specified words from a string or, optionally, replace each letter of the words with a replacement character.

The second argument specifies the words that should be replaced and can either be an array of strings or a callable that returns an array of strings.

The third argument specifies the replacement character. If empty, the words will be removed entirely. If a string with more than one character is provided, only the first character will be used.

$value = \TraderInteractive\Filter\Strings::redact('a string with some unwanted words', ['unwanted', 'words'], '*');
assert($value === 'a string with some ******** *****');

Strings::stripTags

This filter will strip HTML, XML, and PHP tags from a string. This filter also accepts null values, which will be returned as null.

The second, optional argument specifies a replacement string for the removed HTML and XML tags. PHP tags will be stripped without a replacement.

\TraderInteractive\Filter\Strings::stripTags('<div>a string with<br/>tags</div>', ' ');
assert($value === ' a string with tags ');

Url::filter

This filter verifies that the argument is a URL string according to RFC2396. The second parameter can be set to true to allow null values through without an error (they will stay null and not get converted to false).

The following checks that $value is a URL.

\TraderInteractive\Filter\Url::filter($value);

Email::filter

This filter verifies that the argument is an email.

The following checks that $value is an email.

\TraderInteractive\Filter\Email::filter($value);

Json::validate

This filter verifies that the value is in a valid JSON format.

The second parameter can be set to true to allow null values through without an error.

The third parameter determines the maximum recursion depth that is allowed.

The following checks that $value is a valid JSON string.

\TraderInteractive\Filter\Json::validate($value);

Json::parse

This filter parses a valid JSON string into an array, int, double, or bool. Invalid JSON will throw an error.

The second parameter can be set to true to allow null values through without an error.

The third parameter determines the maximum recursion depth that is allowed.

The following checks that $value is a valid JSON string and parses it into an array.

$value = '{ "string": "value", "array": [1, 2, 3] }';
\TraderInteractive\Filter\Json::parse($value);
assert($value === ['string' => 'value', 'array' => [1, 2, 3]]);

UuidFilter::filter

This filter verifies a given string is a valid universally unique identifier.

The second parameter can be set to true to allow null values through without an error.

The third parameter can be set to true to allow Nil UUIDs values through without an error.

The fourth parameter determines which UUID version the value will be validated against. By default, the filter will succeed if the values matches version 1, 2, 3, 4, 5, 6, or 7

// Filtering an UUID string
$value = '1a42403c-a29d-11ef-b864-0242ac120002';
$filtered = \TraderInteractive\Filter\UuidFilter::filter($value);
assert($value === $filtered);

// Filtering null values
$value = null;
$filtered = \TraderInteractive\Filter\UuidFilter::filter($value, true);
assert(null === $filtered);

// Filtering a nil UUID
$value = '00000000-0000-0000-0000-000000000000';
$filtered = \TraderInteractive\Filter\UuidFilter::filter($value, false, true);
assert($value === $filtered);

// Filtering for only UUID v4
$value = '1a42403c-a29d-41ef-b864-0242ac120002';
$filtered = \TraderInteractive\Filter\UuidFilter::filter($value, false, false, [4]);
assert($value === $filtered);

XmlFilter::filter

This filter ensures the given string is valid XML.

$value = "<root><outer><inner>value</inner></outer></root>";
$filtered = \TraderInteractive\Filter\XmlFilter::filter($value);
assert($value === $filtered);

XmlFilter::extract

This filter accepts an XML string and an xpath. It will return the single element found at the xpath.

$value = <<<XML
<?xml version="1.0"?>
<books> 
    <book id="bk101">
        <author>Gambardella, Matthew</author>
        <title>XML Developers Guide</title>
        <genre>Computer</genre>
        <price>44.95</price>
        <publish_date>2000-10-01</publish_date>
        <description>An in-depth look at creating applications with XML.</description>
    </book>
    <book id="bk102">
        <author>Ralls, Kim</author>
        <title>Midnight Rain</title>
        <genre>Fantasy</genre>
        <price>5.95</price>
        <publish_date>2000-12-16</publish_date>
        <description>A former architect battles corporate zombies</description>
    </book>
</books>
XML;
$xpath = '//book[@id="bk102"]';

$filtered = \TraderInteractive\Filter\XmlFilter::extract($value, $xpath);
$expected = <<<XML
<book id="bk102">
    <author>Ralls, Kim</author>
    <title>Midnight Rain</title>
    <genre>Fantasy</genre>
    <price>5.95</price>
    <publish_date>2000-12-16</publish_date>
    <description>A former architect battles corporate zombies</description>
</book>
XML;
assert($filtered === $expected);

XmlFilter::validate

This filter accepts an XML string and a filepath to an XSD. It ensures the given XML is valid using the given XSD and returns the original XML.

$value = <<<XML
<?xml version="1.0"?>
<books> 
    <book id="bk101">
        <author>Gambardella, Matthew</author>
        <title>XML Developers Guide</title>
        <genre>Computer</genre>
        <price>44.95</price>
        <publish_date>2000-10-01</publish_date>
        <description>An in-depth look at creating applications with XML.</description>
    </book>
    <book id="bk102">
        <author>Ralls, Kim</author>
        <title>Midnight Rain</title>
        <genre>Fantasy</genre>
        <price>5.95</price>
        <publish_date>2000-12-16</publish_date>
        <description>A former architect battles corporate zombies</description>
    </book>
</books>
XML;
$xsdFilePath = 'books.xsd';
$filtered = \TraderInteractive\Filter\XmlFilter::validate($value, $xsdFilePath);
assert($filtered === $value);

Contact

Developers may be contacted at:

• Pull Requests
• Issues

Project Build

With a checkout of the code get Composer in your PATH and run:

./vendor/bin/phpcs
./vendor/bin/phpunit

For more information on our build process, read through out our Contribution Guidelines.