Licenser

Automates the prepending of a license header doc block to your directory(ies) of source files.

• Accept a directory of source files or a path to a single source file to process
• Accept a file path containing your custom license doc block
• Can check your source files for the correct license information
• Support global install with .yml Configuration per project

Install

You can grab a copy of rafrsr/licenser in either of the following ways.

As a phar

You can simply download a pre-compiled and ready-to-use version as a Phar to any directory. Simply download the latest licenser.phar file from our releases page:

Latest release

Verify everything works by running this:

php licenser.phar --version

Now can copy this tool when you need to use in any project

Updating phar

There's no separate update procedure, simply download the latest release again and overwrite the existing phar.

Installation using Composer

Alternatively, you can also install Licenser as part of your development dependencies. You will likely want to use the require-dev section to exclude rafrsr/licenser in your production environment.

1. Install composer
2. Execute: require rafrsr/licenser --dev
3. Run ./vendor/bin/licenser --version

Updating dependency

Just run composer update rafrsr/licenser to update to the latest release.

Usage

Using a built-in license type

Licenser supports the following built-in licenses and headers:

• The Apache 2.0 license (referred to as apache2.0 in Licenser)
• The MIT license (referred to as mit in Licenser)
• Default - Is not a license, is a common header to add to any project (referred to as default in Licenser)
• Symfony - Is a header commonly used in symfony components and bundles (referred to as symfony in Licenser)

To use one of these built-in licenses you just replace the path to your custom licenses file with the name of the built-in license instead. For example if you wanted to use the MIT license then you would run something like:

./bin/licenser run /path/to/files mit

The default header is used when run something like this:

./bin/licenser run /path/to/files

Value replacement in built-in licenses

When using a built-in license the Licenser will replace special placeholders with custom values. Placeholder can vary according to license:

license	placeholders
default	author, package, version
mit	author
apache2.0	author
symfony	author, package

e.g.

./bin/licenser /path/to/files -p author:"Author Name <email@example.com>" -p version:1.0
./bin/licenser /path/to/files mit -p author:"Author Name <email@example.com>"
./bin/licenser /path/to/files apache2.0 -p author:"Author Name <email@example.com>"
./bin/licenser /path/to/files symfony -p author:"Author Name <email@example.com>" -p package:MyPHPPackage

Creating your custom license template

License template can be created using a simple text file. License templates are processed using Twig, then can use any twig feature.

e.g.

This file is part of the {{ package }}.

(c) {{ 'now'|date('Y') }}

@version {{ version }}

For the full copyright and license information, please view the LICENSE
file that was distributed with this source code.

To process this license:

./bin/licenser /path/to/files /path/to/license -p package:MyPHPPackage -p version:1.0

NOTE: parameters passed in the commandline can be used in the license template

Checking files for correct license

Licenser also allows you to check your source files for correct license information. It will warn you if there are any source files that do not have a license header that matches the options you provide.

./bin/licenser /path/to/files mit --only-check

By default the check only return if all files are ok or not, bu can use verbosity levels to view more details.

./bin/licenser /path/to/files mit --only-check -vv

Verbosity levels are available in all actions

Dry-run

Licenser also allows you to verify all available changes using a dry-run. Is a mix between normal process and only-check, verify all changes to see affected files before adding headers.

./bin/licenser /path/to/files mit --dry-run -vv

YML configuration per project

Licenser support create a .yml file for each project with custom settings. Is helpful to use a global installation of Licenser and same commandline for all projects.

Create a yml file under your project directory

e.g:

#.licenser.yml
finder:
  in: 
    - src
    - tests
license: default
parameters:
   author: Rafael SR <https://github.com/rafrsr>
   package: Licenser
   version: '@Rafrsr\Licenser\Licenser::VERSION'

and execute

./bin/licenser --config=.licenser.yml

or

./bin/licenser MyClass.php --config=.licenser.yml

In the second example the finder is overwritten and apply the given config to given file or directory.

YML Settings

• finder: used to create instance of Finder to locate source files
  • in: [array, string] relative dir to find files
  • name: [array, string] name of files to process (default: *.php)
  • exclude: [array, string] Exclude directories
  • path: [array, string] Restrict files and directories by path
  • notPath: [array, string] Exclude files and directories by path
  • size: [array, string] Restrict by a size, e.g. ['>= 1K','<= 2K']
  • date: [array, string] Restrict files by last modified dates

To see all available options and usage refer to: Finder. All options given in this configuration are used to build a instance of Finder.

• finders: [array] array of finders to use multiple finders for different file types or sources
• license: [string] name of build-in license to use or relative filename
• license_content: [string] alternative to create your license inline without reference to any file
• parameters: [array] array of parameters to pass to template

NOTE: can reference to a constant in parameters using @ before the name of the constant, e.g: @Rafrsr\Licenser\Licenser::VERSION

Usage in others files types like javascript source files

By default licenser only find for files named *.php can change this behavior in the finder configuration.

e.g:

#.licenser.yml
finder:
  in: 
    - src
  name:
    - *.php
    - *.js

Muti-finder for each type of file

Licenser support configure more than one finder in order to find different files types on different folders, use finders instead of finder to enable this.

e.g:

#.licenser.yml
finders:
  php:
    in:
      - src
  javascript:
     in:
      - web/js/
     name: '*.js'
     notPath:
      - jquery
      - bootstrap

The above example find for default*.php files in src folder, and *.js files in web/js folder ignoring jquery and bootstrap folders in this location

Caution

It is recommended that you have your source files under version control when running the tool as it is still experimental.

Copyright

This project is licensed under the MIT license.