# grunt-phpclassmap

> Generate PHP classmap files using Grunt

Latest version **0.0.13** (published 2016-05-18) · 0 weekly downloads

## Install

```sh
npm install grunt-phpclassmap
pnpm add grunt-phpclassmap
yarn add grunt-phpclassmap
bun add grunt-phpclassmap
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.13 |
| Published | 2016-05-18 |
| First published | 2014-05-06 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.8.0 |
| Dependencies | 4 |
| Known vulnerabilities | 0 (+9 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Maikel van Maurik |
| Maintainers | maikelvanmaurik |
| Keywords | gruntplugin, gruntplugin, grunt task, grunt, generate, php, classmap |

## Links

- npm: https://www.npmjs.com/package/grunt-phpclassmap
- Repository: https://github.com/maikelvanmaurik/grunt-phpclassmap
- Issues: https://github.com/maikelvanmaurik/grunt-phpclassmap/issues
- npm.io page: https://npm.io/package/grunt-phpclassmap

## Dependencies (4)

- [dateformat](https://npm.io/package/dateformat.md) ^1.0.7-1.2.3
- [handlebars](https://npm.io/package/handlebars.md) ^2.0.0-alpha.2
- [underscore](https://npm.io/package/underscore.md) ^1.8.2
- [underscore.string](https://npm.io/package/underscore.string.md) ^3.0.3

## Recent versions

- 0.0.13 (latest) — 2016-05-18
- 0.0.12 — 2015-05-01
- 0.0.11 — 2015-03-05
- 0.0.10 — 2015-03-05
- 0.0.9 — 2015-03-05
- 0.0.8 — 2014-07-16
- 0.0.7 — 2014-05-13
- 0.0.6 — 2014-05-07
- 0.0.5 — 2014-05-07
- 0.0.4 — 2014-05-06
- 0.0.3 — 2014-05-06
- 0.0.2 — 2014-05-06
- 0.0.1 — 2014-05-06

## README

# grunt-phpclassmap

> Generate PHP classmaps

## Getting Started
This plugin requires Grunt `~0.4.4`

If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

```shell
npm install grunt-phpclassmap --save-dev
```

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

```js
grunt.loadNpmTasks('grunt-phpclassmap');
```

## The "phpclassmap" task

### Overview
In your project's Gruntfile, add a section named `phpclassmap` to the data object passed into `grunt.initConfig()`.

```js
grunt.initConfig({
  phpclassmap: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
});
```

### Options

#### options.basedir
Type: `String`
Default value: .

Base directory from which to create the relative paths to class files, defaults to `process.cwd`.

#### options.phpbin
Type: `String`
Default value: 'php'

Path to the php executable

#### options.quote_path
Type: `Boolean`
Default value: true

Wether or not the classes in the classmap should be quoted. There might be some situations where you don't want to do that, for instance in the [filter example](#filter-example).

#### options.dest
Type: `String`
Default value: none

Where to write the classmap file to.

#### options.map
Type: `Function`
Default value: none

Function which maps the entry inside the destination classmap file. The function recieves a item object which in turn has the following properties:

* absolute_path (absolute path to the object)
* relative_path (relative path to the object, which is the absolute_path without the basedir option)
* name (name of the object)
* type (class, interface, trait)

**IMPORTANT** The function should return the resulting item

#### options.filter
Type: `Function`
Default value: none

Function which can be used to filter out unwanted items for the classmap, see the [filter example](#filter-example)

#### options.sort
Type: `Function`
Default value: none

Function which allows you to sort the found classes by providing a function which will be used by the Array.prototype.sort function, see the [sort example](#sort-example)

### Usage Examples

#### Basic usage

The following is a basic example usage of the grunt-phpclassmap. This will scan all files under the directory `src` and will try to find all php classes.

```js
grunt.initConfig({
    phpclassmap: {
        options: {
            dest: './classmap.php'
        },
        files  : {
            src   : [ 'src/**/*.php' ],
            expand: true
        }
    },
});
```

The resulting `classmap.php` will look something like:

```php
<?php
/**
 * Generated by grunt-phpclassmap on {{date}}
 */
return array(
	"Foo" => "/src/foo.class.php",
	"Bar" => "/src/class-bar.php"
);

/* EOF */
```

#### Map items to use a defined constant

In this example, we use override the format function in order to use a defined constant inside the resulting classmap

```js
grunt.initConfig({
    phpclassmap: {
        options: {
			quote_path: false,
            dest: './classmap.php',
            map: function(item) {
                item.relative_path = 'DEFINED_BASE_PATH_CONSTANT . "' + item.relative_path + '"';
                return item;
            }
        },
        files  : {
            src   : [ 'classes/**/*.php' ],
            expand: true
        }
    },
});
```

#### Custom handlebars template

grunt-phpclassmap uses handlebars to render the classmap file, you can specify a custom handlebars template, like so:

```js
grunt.initConfig({
    phpclassmap: {
        options: {
            dest: './classmap.php',
            template: 'my-classmap-template.tpl'
        },
        files  : {
            src   : [ 'classes/**/*.php' ],
            expand: true
        }
    },
});
```

currenty the compiled template recieves data in the form:

```js
{
	quote_path: Boolean,
    items: Array,
    date: String
}
```

#### Custom the render functionality

besides changing the template it's also possible to define you own render function, like so:

```js
grunt.initConfig({
    phpclassmap: {
        options: {
            dest: './classmap.php',
            render: function(objects, cb) {
                var content = '<?php\n' +
                    'return array(' +
                    '%items%' +
                    ');';
                // Build up the item array
                var items = [];
                for(var i=0; i<objects.length;i++) {
                    items.push('"' + objects[i].name + '" => "' + objects[i].absolute_path + '"');
                }
                cb(content.replace('%items%', items.join(',')));
            }
        },
        files  : {
            src   : [ 'classes/**/*.php' ],
            expand: true
        }
    },
});
```

**IMPORTANT**: When you override the render method be sure to call to callback which is provided to the function, as this is the function which writes to results to the classmap.

#### Custom map and render functionality

In this example you can see how you can mix the map and render function to do some custom stuff.
Note that the map allows you to add additional data, which is written in de render function. This could have also been
done by providing a custom template.

```js
grunt.initConfig({
    phpclassmap: {
        options: {
            map: function (item) {
                item.rewritten_path = your_rewrite_function(item);
                return item;
            },
            render: function(objects, cb) {
                    var content = '<?php\n' +
                                'return array(' +
                                '%items%' +
                                ');';
                    // Build up the item array
                    var items = [];
                    for(var i=0; i<objects.length;i++) {
                        items.push('"' + objects[i].name + '" => "' + objects[i].rewritten_path) + '"';
                    }
            cb(content.replace('%items%', items.join(',')));
        }
```

#### Filter example

The filter option can be used to remove unwanted items, the function should return a `Boolean`. It should return true to include the item in the classmap; otherwise, false.

```js
grunt.initConfig({
    phpclassmap: {
        options: {
			dest: 'classmap.php',
            filter: function (item) {
                return item.name != 'My_Unwanted_Class';
            }
        }
	}
});
```

#### Sort example

The sort option can be used to sort the objects before they are written to the classmap file.

```js
grunt.initConfig({
    phpclassmap: {
		options: {
			dest: './classmap.php',
			sort: function(a, b) {
				var aa = a.name.toUpperCase();
				var bb = b.name.toUpperCase();
				return (aa < bb) ? -1 : (aa > bb) ? 1 : 0;
			}
		},
		files  : {
            src   : [ 'src/**/*.php' ],
            expand: true
        }
	}
}
```

#### Combined with grunt-contrib-watch

Example of a nice way to automaticly generate classmaps during development.

```js
grunt.initConfig({
    phpclassmap: {
        options: {
			dest: 'classmap.php',
            filter: function (item) {
                return item.name != 'My_Unwanted_Class';
            }
        },
		files  : {
            src   : [ 'classes/**/*.php' ],
            expand: true
        }
	},
	watch: {
		phpclassmap: {
			files: ['classes/**/*.php' ],
			tasks: [ 'phpclassmap' ]
		}
	}
});
```


## Release History


### Version 0.0.1

Initial release

### Version 0.0.2

Fix: added handlebars as a required dependency

### Version 0.0.3

Fix: added dateformat as a required dependency

### Version 0.0.4

Fix: remove some debug statements
Fix: typo in the default template comments

### Version 0.0.5

Fix: correct stupid mistake of writing the classmap inside a loop
Update: add the quote_path option
Update: the default template to use the quote_path

### Version 0.0.6

Update: add the map option for changing the item
Change: change the existing filter option functionality to filter found entries

### Version 0.0.7

Update: add the sort option
Update: provide better feedback of the found classmap results

### Version 0.0.8

Update: support for bigger projects

### Version 0.0.9

Fix: PHP notice during class map generation

### Version 0.0.10

Fix: Temporary path fix

### Version: 0.0.11

Fix: add underscore and underscore.string as dependencies

### Version: 0.0.12

Update: add support for options per target

### Version: 0.0.13

Fix: relative paths were not generated properly
Fix: many files caused to generator to fail

---
_Source: https://npm.io/package/grunt-phpclassmap · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._