Fluent regular expressions in PHP
PHP
Latest commit f980cf6 Dec 9, 2015 @selvinortiz Merge pull request #12 from roxburghm/master
Fixed problem with zero min lengths being ignored

README.md

FLUX (Fluent Regex) 0.5.2

Build Status Total Downloads Latest Stable Version

by Selvin Ortiz

Description

Fluent Regular Expressions in PHP inspired by and largely based on VerbalExpressions:JS by Jesse Luoto

@see inspiration & credits below for more info.

Requirements

  • PHP 5.3
  • Composer

Install

Flux is available as a package via composer

  • require: "selvinortiz/flux": "dev-master"
  • autoload: require_once 'path/to/vendor/autoload.php'
  • namespace: use SelvinOrtiz\Utils\Flux\Flux;
  • instantiate: $flux = Flux::getInstance();

You can additionally clone/download this repo and do whatever you want: )


@Example

This simple example illustrates the way you would use flux and it's fluent interface to build complex patterns.

require_once realpath(__DIR__.'/../vendor/autoload.php');

use SelvinOrtiz\Utils\Flux\Flux;
use SelvinOrtiz\Utils\Flux\Helper;

// The subject string (URL)
$str    = 'http://www.selvinortiz.com';

// Building the pattern (Fluently)
$flux   = Flux::getInstance()
        ->startOfLine()
        ->find('http')
        ->maybe('s')
        ->then('://')
        ->maybe('www.')
        ->anythingBut('.')
        ->either('.co', '.com')
        ->ignoreCase()
        ->endOfLine();

// Output the Flux instance
Helper::dump( $flux );

// Output the fluently built pattern (@see /src/SelvinOrtiz/Utils/Flux/Helper)
Helper::msg( $flux ); // /^(http)(s)?(\:\/\/)(www\.)?([^\.]*)(.co|.com)$/i

// Inspect the results
Helper::msg( $str );
Helper::msg( $flux->match( $str ) ? 'matched' : 'unmatched' );
Helper::msg( $flux->replace( 'https://$5$6', $str ) );

For other examples, please see the /etc directory.


@Changelog


0.5.2

  • Adds length() method which adds or replaces the modifier used in the previous call
  • Adds getLastSegmentKey()
  • Adds the (empty) Factory class for optimized, often used patterns
  • Fixes indentation and EOF on phpunit.xml
  • Fixes comment typos on README and example files Pull Request #10

0.5.1

  • Adds getSegments() which was not included in 0.5.0 Issue #5
  • Adds removeSegment() which can be used in unit tests as well
  • Adds lineBreak() and br() which matches a new line (DOS/Unix)
  • Adds clear() which allows you to clear out the pattern and start from scratch
  • Adds getPattern() which compiles the expression and returns it
  • Adds `deprecation candidates as @todos
  • Fixes mixed logic between add() and raw()
  • Fixes implementation on the orTry() method
  • Moves example in readme above changelog
  • Improves unit tests

0.5.0 (Beta)

  • Adds getSegments() to improve testability Issue #5
  • Adds composer package selvinortiz/flux
  • Adds dev branch
  • Adds contributing notes
  • Adds install notes

0.4.5

  • Fixes internal namespace conflict
  • Changes namespace from Sortiz\Tools to SelvinOrtiz\Utils\Flux
  • Adds composer support Issue #3
  • Adds the addSeed() and removeSeed() methods Issue #4
  • Adds the getInstance() static method
  • Adds FluxUrlExample.php, FluxDateExample.php, and FluxPhoneExample.php
  • Adds getSeed() to get the seed without forcing __toString on the object
  • Adds getSegment() to extract a segment (capturing group) from the pattern
  • Implements unit tests (60% coverage) Issue #3
  • Implements Full PSR-2 Compliance (Tabs over Spaces)
  • Enables the seed on match() and replace() Issue #4
  • Removes example.php and defines them elsewhere
  • Moves examples into /etc and defines one example per file
  • Other small fixes and additions

0.4.0

  • Adds Flux to the Sortiz\Tools namespace
  • Implements PSR-2 Compliance (Tabs over Spaces)
  • Updates version number on Flux and this readme file
  • Updates the class instantiation with fully qualified class name on example.php
  • Adds references to other repos that have ported flux
  • Addresses concerns outlined in Issue #3

0.3.0

  • Improves documentation with phone/date examples
  • Adds the letters() method
  • Renames the numbers() method to digits()
  • Adds support for quantifiers for digits()
  • Adds ignoreCase() and promotes it above inAnyCase()
  • Improves the documented API

Thought hard about changing the name to FluentX any thoughts?


0.2.0

  • Adds the either( $option1, $option2 [, $option3 ...] ) method to handle OR cases
  • Updates the fluent example in this readme file
  • Adds the license

0.1.0 (Alpha)

Initial preview release


@Todo

  • Add source code comments
  • Add support for quantifiers
  • Add language methods for more advanced use cases
  • Add reference to repos that have ported Flux (*)
  • Add license notes (*)
  • Add contributing notes (*)
  • Add credits (*)

FLUX API

The flux API was designed to give you a fluent chainable object to build patterns with.

startOfLine()

Adds a beginning of line ^ modifier

endOfLine()

Adds an end of line $ modifier

find( $val ) & then( $val )

Allows you to augment the pattern with a required segment and it escapes regular expression characters

maybe( $val )

Allows you to augment the pattern with an optional segment

any( $val ) & anyOf( $val )

Allows you to create a set of characters to match

anything()

Adds a wild card (.*) segment to the pattern but it does not make dotAll() explicit

anythingBut( $val )

Will match anything but the characters in $val which is opposite of any() and anyOf

br() & lineBreak()

Allows you to match a new line (DOS/Unix)

tab()

Adds a (\t) to the pattern which will match a tab

word()

Adds (\w+) to the pattern which will match a single word

letters( $min=null, $max=null )

Only matches characters in the alphabet and uses $min and $max to create a quantifier

digits( $mix=null, $max=null )

Only matches digits and uses $min and $max to create a quantifier like word()

range( $from, $to [, $from, $to ...])

Allows you to create a range character class like a-z0-9 by calling range('a', 'z', 0, 9)

orTry( $val='' )

Allows you to create OR cases (this)|(else) and retain the capturing order to use in replace()

ignoreCase() & inAnyCase()

Adds the i modifier to the pattern which will allow you to match in a case insensitive manner

matchNewLine() & dotAll()

Adds the s modifier to the pattern which will allow you to match a new line when using anything()

multiline()

Adds the m modifier to the pattern which will allow you to search across multiple lines

oneLine() & searchOneLine()

Removes the modifier added by multiline() if it was previously called

match( $subject )

Simply takes your $subject in, compares it against the pattern, and returns whether a it matched or not

replace( $replacement, $subject )

You can replace matched segments by using the $x format where x is the (int) position of the matched segment

getPattern()

Returns the compiled pattern which you can also get by using the flux instance in a context where __toString() will be called

clear()

Clears the created pattern along with the modifiers, prefixes, and suffixes


Flux Elsewhere

There is a straight port of Flux for NodeJS by James Brooks whom has also collaborated on this project.

Feedback

This is something that started as a weekend experiment but I would love to take it further so if you have any suggestions, please fire away!

The best way to get in touch with me is via twitter @selvinortiz we'll take if from there :)

Contributing

  1. Check for open issues or open a new issue for a feature request or a bug
  2. Fork this repo to start making your changes to the dev branch or branch off
  3. Write a test which shows that the bug was fixed or that the feature works as expected
  4. Send a pull request and bug me until I merge it or tell you no cigar; )

Inspiration & Credits

This project is inspired and largely based on VerbalExpressions:JS by Jesse Luoto whom on July 20, 2013 started a weekend project that generated a lot of interest in the developer community and that project has proven to have a lot of potential.

Flux is not a straight port of VerbalExpressions but if you're interested in a straight VerbalExpressions port for PHP you should checkout VerbalExpressions:PHP by Mark Wilson

VerbalExpressions has also been ported to Ruby, Java, Groovy as of this update (July 25, 2013).

For a little background as to why flux was created and why you should use it, please refer to Issue #7 for a discussion on that matter.

MIT License

Flux is released under the MIT license which pretty much means you can do with it as you please and I won't get mad because I'm that nice; )