README
grunt-php-router-gen
Create a Fastest Php router by grunt
Generate JSON routing behavior file
Php Router read the file and find match
that's all.
routerphp--class in attached
Getting Started
This plugin requires Grunt ~0.4.4
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-php-router-gen --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-php-router-gen');
The "php_router_gen" task
Overview
In your project's Gruntfile, add a section named php_router_gen
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
php_router_gen: {
options: {
// Task-specific options go here.
},
your_target: {
options: {
// Target-specific options go here.
},
files: [
{
expand: true,
cwd: 'path/to/source/dir/',
src: 'filesForRouteParsing.json'
dest: 'path/to/destination/dir/',
ext: 'json'
}
]
// Target-specific file lists and/or options go here.
},
},
});
Options
options.read (fpath)
Type: function
Method to open file.
// example (default)
read: function (fpath) {
var readMethod = 'read';
if (/.json$/.test(fpath)) {
readMethod = 'readJSON';
} else if (/.yml$/.test(fpath)) {
readMethod = 'readYML';
}
return grunt.file[readMethod](fpath);
},
options.parse (fileContent)
Type: function
Method for parsing file
// example (default)
parse: function (fileContent) {
return fileContent; // must return array of rows of routes
},
// MUST RETURN ARRAY of OBJECTS
[
{
name: 'someName', // required
method: 'get',
url: 'url/to/parse/(:args)/(...)' // required
}
]
options.collect
Type: function
Method for compile route to json
collect: function (route) {
return _.pick(route, 'name', 'method', 'args', 'reverse', 'pattern', 'data');
},
options.collectPattern (urlPattern, route)
Type: function
Method for compile url-pattern from urlSegments and route options
collectPattern: function (urlSegments, routeOptions) {
var url = _.map(urlSegments,function (segmentObj) {
return segmentObj.pattern;
}).join('/');
var lastSlash = (routeOptions.trailingSensitive ? (routeOptions.hasLastSlash ? '/' : '') : '[/]?');
var flags = routeOptions.caseSensitive ? '' : 'i';
flags += routeOptions.unicodeSensitive ? 'u' : '';
url = '#^/?' + url.replace(/^\s*\/+/, '') + lastSlash + '$#' + flags;
return url;
},
options.collectReverse
Type: function
Method for compile reverse url-pattern from urlSegments and route options
collectReverse: function (urlSegments, routeOptions) {
var r = _.map(urlSegments, function (segmentObj) {
var url = segmentObj.pattern;
_.each(segmentObj.args, function (arg) {
url = url.replace(arg.pattern + '?', '<' + arg.name + '?>');
url = url.replace(arg.pattern, '<' + arg.name + '>');
});
return url;
});
r = r.join('/');
r = utils.cleanUrl(r);
return r;
},
options.caseSensitive
Type: boolean
Default value: true
option for reg exp of end url-pattern
options.unicodeSensitive
Type: boolean
Default value: true
option for reg exp of end url-pattern
options.trailingSensitive
Type: boolean
Default value: true
Option for reg exp of end url-pattern. Last slash sensitivity. Url dependence of slash if true. add [/]? in end if else
options.beautify
Type: boolean
Default value: false
JSON stringify option (add indent if true)
options.map
Type: object|function|null
Default value: null
route's data (such as params and other). This object will be returned if route found match with route.uri
{
someRouteName: {
params: {
someUrlParamName: defaultValue1,
someParamName: defaultValue2
}
}
}
options.getRouteParamsByMap (routeName, map)
Get route data from route-data-map.
// example
getRouteParamsByMap: function (routeName, map) {
if (map[routeName] == null) {
grunt.fail.fatal('Undefined route "' + routeName + '" in data-map');
}
return map[routeName];
}
options.aliases
Type: object
Default value: {}
Constraint aliases. for use in url patterns as (decimal:paramName)
{
'decimal': '\\d+',
'integer': '-?\\d+'
}
options.parseUrlSegment
Type: function
Detect args in current url segment.
default detection format of simple url param: (PATTERN_OR_ALIAS:PARAM_NAME) default detection format of infinite url params: (...)
//MUST RETURN
segmentObj = {
args: [
{
name: 'strName', // string name mast compatible with template /^[a-z][a-zA-Z0-9_]$/
pattern: '(?P<strName>.+)' // VALID NAMING REG_EXP PATTERN FOR DETECT PARAM FROM THIS SEGMENT STRING
},
{
name: 'strName',
pattern: '(?P<strName>.+)'
}
],
segment: strSegmentPattern // string
};
return segmentObj;
Usage Examples
source/routes.json
[
{
"name": "hello-1",
"url": "test/one/((\\d+|_\\d+):var1)/",
"method": "get"
},
{
"name": "one-hello",
"url": "test/one/(:var1)/",
"method": "get"
},
{
"name": "two-hello",
"url": "test/one/(:var1)",
"method": "get"
},
{
"name": "tree-hello",
"url": "test/one/(:var1)/222",
"method": "get"
}
]
gruntfile
In this example, custom options are used to do something else with whatever else. So if the testing
file has the content Testing
and the 123
file had the content 1 2 3
, the generated result in this case would be Testing: 1 2 3 !!!
grunt.initConfig({
php_router_gen: {
options: {
separator: ': ',
punctuation: ' !!!',
},
test_one: {
options:{
beautify: true
},
files: [
{
expand: true,
cwd: './test/one',
src: 'routes_one.json',
dest: 'tmp'
}
]
},
},
});
ADVANCE USAGE
routes test/two/routes_two.txt
this file translate into need format. but this format better for routing
get / -> user.post
get user/(...)? -> user.post
get user -> user.get.one #line comment
post user -> user.post
put user/(...) -> user.post
get user/(...)?/123 -> user.post
get session/(...)?/123 -> session.get
#line comment
get /user/(decimal:id)?/asd -> user.get.all
get user/(\d+:id)? -> user.get.all2
get hello/(\d+:ggg)? -> hello.get
map test/two/map_two.json
{
"root": "/controllers",
"<user>": {
"path": "/user",
"<get>": {
"<all>": {},
"<all2>": {},
"<one>": {}
},
"<post>": {}
},
"<hello>": {
"params": {
"ggg": 111
},
"<get>": {
"params": {
"ggg": 222
}
}
},
"<session>": {
"params": {
"aaaa": 111
},
"<get>": {
"params": {
"aaaa": 222
}
}
}
}
gruntfile
grunt.initConfig({
php_router_gen: {
test_two: {
options: {
map: function () {
var json = grunt.file.readJSON('test/two/map_two.json');
var getAllResources = function (currObj, _prevName, options, _result) {
options = options || {};
_result = _result == null ? {} : _result;
_prevName = _prevName == null ? '' : _prevName + '.';
var resourceNodeExp = /^<([^>]+)>$/;
var resources = {};
_.each(currObj, function (v, k) {
if (resourceNodeExp.test(k)) {
resources[_prevName + k.replace(resourceNodeExp, '$1')] = v;
} else {
options[k] = v;
}
});
_.each(resources, function (v, name) {
_result[name] = getAllResources(v, name, _.clone(options), _result).options;
});
return {
options: options,
result: _result
};
};
return getAllResources(json).result;
},
aliases: {
"decimal": "[0-9]+"
},
parse: function (fileContent) {
var routes = [];
var rows = fileContent
.trim()
.replace(/^\s+/mg, '').replace(/\s+$/mg, '')
.replace(/\s*->\s*([^\s]*)$/gm, ' $1')
.split(/\n\s*/);
_.each(rows, function (row) {
row = row.replace(/#.+$/, '');
if (!row.length) {
return;
}
var rowObj = {
name: null,
method: null,
url: null
};
var rowSegments = row.trim().split(/\s+/);
var root = '/test/two/';
if (rowSegments.length === 3) {
rowObj.method = rowSegments[0];
rowObj.url = rowSegments[1];
rowObj.name = rowSegments[2];
} else if (rowSegments.length === 2) {
rowObj.method = null;
rowObj.url = rowSegments[0];
rowObj.name = rowSegments[1];
}
if (rowObj.url) {
rowObj.url = rowObj.url.trim();
if (!/^\/.+$/.test(rowObj.url)) {
rowObj.url = root + rowObj.url;
}
}
routes.push(rowObj);
});
return routes; // must be [{method: 'get', url: '/needed/url/string', name: 'resource.name'}]
},
caseSensitive: true,
unicodeSensitive: true,
trailingSensitive: true,
beautify: true
},
files: [
{
expand: true,
cwd: 'test/two',
src: 'routes_two.txt',
dest: 'tmp',
ext: '.json'
}
]
}
},
});
usage in PHP
detect current route
require_once('Router.php');
$routes = json_decode(file_get_contents('../../tmp/routes_one.json'), true);
$router = new Router($routes);
$result = $router->match($_SERVER['REQUEST_METHOD'], $_SERVER['REQUEST_URI']);
var_dump($result);
get url by route name and params (reverse)
require_once('Router.php');
$routes = json_decode(file_get_contents('routes_two.json'), true);
$router = new Router($routes);
$result = $router->reverse('GET', 'user.get.all', array('version'=>333, 'id' => 3));
$result = $router->reverse('post', 'user.post', array('version'=>333, 'id' => 3));
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.