README

Integration of squirrelphp/strings into a Symfony project through service tags and bundle configuration.

Installation

composer require squirrelphp/strings-bundle

Configuration

Enable the bundle by adding Squirrel\StringsBundle\SquirrelStringsBundle to the list of your used bundles. The bundle then configures itself automatically.

Usage

String filters

The default filters are grouped in six categories (links go to squirrelphp/strings documentation):

Newlines, tabs and spaces

• NormalizeNewlinesToUnixStyle
• ReplaceUnicodeWhitespaces
• RemoveExcessSpaces
• LimitConsecutiveUnixNewlinesToTwo
• RemoveZeroWidthSpaces
• ReplaceNewlinesWithSpaces
• Trim
• ReplaceTabsWithSpaces
• WrapLongWordsNoHTML20Chars
• WrapLongWordsWithHTML20Chars

Cases: lowercase, uppercase, camelcase, snakecase

• Lowercase
• Uppercase
• UppercaseFirstCharacter
• UppercaseWordsFirstCharacter
• CamelCaseToSnakeCase
• SnakeCaseToCamelCase

HTML

• RemoveHTMLTags
• RemoveHTMLTagCharacters
• ReplaceUnixStyleNewlinesWithParagraphs
• EncodeBasicHTMLEntities
• DecodeBasicHTMLEntities
• DecodeAllHTMLEntities

Remove/restrict characters and content

• RemoveNonUTF8Characters
• RemoveNonAlphanumeric
• RemoveNonAlphabetic
• RemoveNonNumeric
• RemoveNonAsciiAndControlCharacters
• RemoveEmails
• RemoveURLs

Normalize to ASCII

• NormalizeLettersToAscii
• NormalizeToAlphanumeric
• NormalizeToAlphanumericLowercase
• ReplaceNonAlphanumericWithDash

Streamline input

• StreamlineInputWithNewlines
• StreamlineInputNoNewlines

You can typehint Squirrel\Strings\StringFilterSelectInterface to get a service where all filters are accessible via the getFilter method:

function (\Squirrel\Strings\StringFilterSelectInterface $selector) {
    $string = "hello\n\nthanks a lot!\nbye";

    $string = $selector->getFilter('ReplaceNewlinesWithSpaces')
        ->filter($string);

    // Outputs "hello  thanks a lot! bye"
    echo $string;
}

You can also directly typehint a filter class, like Squirrel\Strings\Filter\NormalizeToAlphanumeric - all classes are registered as services in Symfony with their class names. All filter classes can also be instantiated in your application.

Form string filtering

This bundle automatically configures string filters for your form values that you can use via attributes, example:

<?php

use Squirrel\Strings\Annotation\StringFilter;

class NewsletterChangeAction
{
    #[StringFilter("StreamlineInputNoNewlines","RemoveHTMLTags")]
    public string $firstName = '';

    #[StringFilter("RemoveNonAlphanumeric")]
    public string $confirmToken = '';
}

You can run one or more string filters and use any of the default list of filters or any of your own filters which you added. The filters are run as an early PRE_SUBMIT form event.

Beware: It only works if you map your class properties ($firstName and $lastName in this example) to the form without custom property paths, so the names used in the form have to be identical to the property names in the class. As long as you do not specify property_path in your form you are safe.

Adding new filters

Create a class, implement Squirrel\Strings\StringFilterInterface and tag the service with squirrel.strings.filter in a Symfony config file like this:

services:
    MyCustomStringFilter:
        tags:
            - { name: squirrel.strings.filter, filter: MyCustomStringFilter }

The filter will be available in Squirrel\Strings\StringFilterSelectInterface under the name MyCustomStringFilter (the filter value you defined for the tag) as well as in the StringFilter attribute.

Random string generators

Generates random strings according to a list of possible characters. The following services are configured by default and can be injected into your services (they are implementing Squirrel\Strings\RandomStringGeneratorInterface):

• squirrel.strings.random.62_characters generates a random string with the 62 alphanumeric characters (A-Z, a-z and 0-9)
• squirrel.strings.random.36_characters generates a random string with the 36 alphanumeric lowercase characters (a-z and 0-9)
• squirrel.strings.readfriendly_uppercase generates a random string with 27 easily distinguishable uppercase characters (234579ACDEFGHKMNPQRSTUVWXYZ), ideal if a human has to view and enter a code with such characters
• squirrel.strings.readfriendly_lowercase generates a random string with 27 easily distinguishable lowercase characters (234579acdefghkmnpqrstuvwxyz), the same as the above uppercase variant, just in lowercase

You can add your own random string generator by creating a class implementing Squirrel\Strings\RandomStringGeneratorInterface and tagging it with squirrel.strings.random:

services:
    MyCustomRandomGenerator:
        tags:
            - { name: squirrel.strings.random, generator: MyGenerator }

The generator name in camel case is used when getting a generator via the getGenerator method from the service Squirrel\Strings\RandomStringGeneratorSelectInterface (so 62Characters instead of 62_characters, and ReadfriendlyLowercase instead of readfriendly_lowercase), or if you want to inject the random string generator directly just convert the generator name to snake case, so in this example you could inject the service with @squirrel.strings.random.my_generator.

The classes Squirrel\Strings\Random\GeneratorAscii and Squirrel\Strings\Random\GeneratorUnicode are good base classes to use for your own needs, where you only need to define the allowed characters in the constructor:

services:
    MyCustomRandomGenerator:
        class: Squirrel\Strings\Random\GeneratorAscii
        arguments:
            - '6789'
        tags:
            - { name: squirrel.strings.random, generator: MyGenerator }

    MyOtherCustomRandomGenerator:
        class: Squirrel\Strings\Random\GeneratorUnicode
        arguments:
            - 'öéèä'
        tags:
            - { name: squirrel.strings.random, generator: MyUnicodeGenerator }

The first one would create a generator where only the characters 6, 7, 8 and 9 are generated, the second one where only the unicode characters ö, é, è and ä are generated. Just make sure to not use a character twice, otherwise the class will throw an exception.

Condense a string into a number

Convert an integer to a string with a given "character set" - this way we can encode an integer to condense it (so an integer with 8 numbers is now only a 4-character-string) and later convert it back when needed.

More information is available in the squirrelphp/strings library, this bundle does not provide any additional service definitions for condensing at this point.

URL

The URL class accepts an URL in the constructor and then lets you get or change certain parts of the URL to do the following:

• Get scheme, host, path, query string and specific query string variables
• Change an absolute URL to a relative URL
• Change scheme, host, path and query string
• Replace query string variables, or add/remove them

This can be used to easily build or change your URLs, or to sanitize certain parts of a given URL, for example when redirecting: use the relative URL instead of the absolute URL to avoid malicious redirecting to somewhere outside of your control.

This functionality is taken from squirrelphp/strings, this bundle does not provide any additional functionality to handle URLs.

Regex wrapper

Using the built-in preg_match, preg_match_all, preg_replace and preg_replace_callback PHP functions often makes code less readable and harder to understand for static analyzers because of its uses of references ($matches) and the many possible return values. Squirrel\Strings\Regex wraps the basic functionality of these preg functions, creates easier to understand return values and throws a Squirrel\Strings\Exception\RegexException if anything goes wrong. These are the available static methods for the Regex class:

(This functionality is taken from squirrelphp/strings, this bundle does not provide any additional functionality to handle Regex)

Regex::isMatch(string $pattern, string $subject, int $offset): bool

Wraps preg_match to check if $pattern exists in $subject.

Regex::getMatches(string $pattern, string $subject, int $flags, int $offset): ?array

Wraps preg_match_all to retrieve all occurences of $pattern in $subject with PREG_UNMATCHED_AS_NULL flag always set and the possibility to add additional flags. Returns null if no matches are found, otherwise the array of results as set by preg_match_all for $matches.

Regex::replace(string|array $pattern, string|array $replacement, string $subject, int $limit): string

Wraps preg_replace to replace occurences of $pattern with $replacement and only accepts a string as $subject.

Regex::replaceArray(string|array $pattern, string|array $replacement, array $subject, int $limit): array

Wraps preg_replace to replace occurences of $pattern with $replacement and only accepts an array as $subject.

Regex::replaceWithCallback(string|array $pattern, callback $callback, string $subject, int $limit, int $flags): string

Wraps preg_replace_callback to call a callback with the signature function(array $matches): string for each occurence of $pattern in $subject and only accepts a string as $subject.

Regex::replaceArrayWithCallback(string|array $pattern, callback $callback, array $subject, int $limit, int $flags): array

Wraps preg_replace_callback to call a callback with the signature function(array $matches): string for each occurence of $pattern in $subject and only accepts an array as $subject.