rafrsr / licenser
Automates the prepending of a license header doc block to your source files.
Requires
- php: >=5.6
- symfony/console: ~2.8|~3.0
- symfony/filesystem: ~2.8|^3.1
- symfony/finder: ~2.8|~3.0
- symfony/stopwatch: ~2.8|^3.1
- symfony/yaml: ~2.8|~3.0
- twig/twig: ~1.2
Requires (Dev)
- phpunit/phpunit: ^5.0
- satooshi/php-coveralls: dev-master
README
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:
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.
- Install composer
- Execute:
require rafrsr/licenser --dev
- 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:
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.