Fluent regular expressions in PHP.

v0.5.3 2015-12-08 23:09 UTC

This package is auto-updated.

Last update: 2024-10-29 03:58:58 UTC


README

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