selvinortiz / flux
Fluent regular expressions in PHP.
Installs: 1 994
Dependents: 3
Suggesters: 0
Security: 0
Stars: 340
Watchers: 14
Forks: 20
Open Issues: 1
Requires
- php: >=5.3.0
README
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 in0.5.0
Issue #5 - Adds
removeSegment()
which can be used in unit tests as well - Adds
lineBreak()
andbr()
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()
andraw()
- 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
toSelvinOrtiz\Utils\Flux
- Adds composer support Issue #3
- Adds the
addSeed()
andremoveSeed()
methods Issue #4 - Adds the
getInstance()
static method - Adds
FluxUrlExample.php
,FluxDateExample.php
, andFluxPhoneExample.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
onmatch()
andreplace()
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 theSortiz\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 todigits()
- Adds support for quantifiers for
digits()
- Adds
ignoreCase()
and promotes it aboveinAnyCase()
- 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
- Check for open issues or open a new issue for a feature request or a bug
- Fork this repo to start making your changes to the
dev
branch or branch off - Write a test which shows that the bug was fixed or that the feature works as expected
- 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; )