malukenho / docheader

A small tool to check license headers

DocHeader

How much time we have wasted to change copyright years in our project? How much times we forget to update it and then we're in the middle of a new year using last year copyright dated? That's sucks!!one!!

Put doc header check in your build and get it out of your way!

Installing

 composer require --dev --sort-packages malukenho/docheader

Setting up

Put your header in one .docheader file in the directory that you're running the checker/fixer. It file must contain only the dockblock as you want, like following example:

/**
 * Zend Framework (http://framework.zend.com/)
 *
 * @link      http://github.com/zendframework/zf2 for the canonical source repository
 * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
 * @license   http://framework.zend.com/license/new-bsd New BSD License
 */

and then run the checker:

./vendor/bin/docheader check src/

So, you get errors or a message saying that everything is ok!

Docheader file

By default, the docheader search for a .docheader file on the current directory that the command is executed. But you can specify a folder or a file to be used as placeholder using the option --docheader [file-or-path]

Current year placeholder

You can also put %year% on your .docheader file to refer to the current Year, like that:

/**
 * @copyright Copyright (c) 2005-%year% Zend Technologies USA Inc. (http://www.zend.com)
 */

Regexp assertion

If you're using >=0.1.5 version, you can use the %regexp:% placeholder to match some content.

Example:

/**
 * @copyright Copyright (c) 20%regexp:\d{2}%-2016 Zend Technologies USA Inc. (http://www.zend.com)
 */

In this case %regexp:\d{2}% assert that it should be a number of two digits between 20 and -.

docheader's Issues

Feature request: flag to specify .docheader location

Zend Framework uses single package, installed as dev dependency, for its coding style rules.

Ability to specify custom .docheader file location will allow it to force uniform header format across all packages:

 $ docheader check src test --docheader ./vendor/zendframework/zend-coding-standard/.docheader

Feature request: --exclude flag

We often have test assets such as test configuration files that do not and should not have license docblocks. However, because they are PHP files, they are scanned and docheader correctly points out that they are missing license headers.

As such, I request an --exclude flag for the binary, and/or an --exclude-dir flag. The flag(s) should allow multiple invocations:

# Multiple --exclude flags:
$ docheader check test --exclude test/TestAsset/config.php --exclude test/Foo/TestAsset/config.php
# Multiple --exclude-dir flags:
$ docheader check src test --exclude-dir test/TestAsset --exclude-dir test/Foo/TestAsset

Any items matching the flag(s) would then be excluded when performing checks.

Stable release

Would it be an option to have a stable release (V1.0.0.) to eliminate the fact that the composer.json would need a minimum-stability: "dev" as this is unwanted for some production application we are having at our company.

But I do like to have an automated check for the correct headers.

+1 for this package.

Docheader broke Travis tests

I have updated all test for another project and docheader broke the last one.

$ vendor/bin/docheader check src/ tests/
PHP Fatal error:  Class 'Symfony\Component\Console\Application' not found in /home/travis/build/antoine-pous/PHP-Router/vendor/malukenho/docheader/bin/docheader on line 42
PHP Stack trace:
PHP   1. {main}() /home/travis/build/antoine-pous/PHP-Router/vendor/malukenho/docheader/bin/docheader:0
Fatal error: Class 'Symfony\Component\Console\Application' not found in /home/travis/build/antoine-pous/PHP-Router/vendor/malukenho/docheader/bin/docheader on line 42

Travis's full report: https://travis-ci.org/antoine-pous/PHP-Router

Feature request: Add configuration block to .docheader

This package is incredibly usefull, but we can't use configuration from file.

Using another block into .docheader would be awesome :)

/*
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * This software consists of voluntary contributions made by many individuals
 * and is licensed under the MIT license.
 */
// ==DocHeader==
// @include *.php *.js style.css
// @exclude vendor/ *.md hello.jpg
// @path public/css/ public/js/ app/
// ==/DocHeader==

Features:

@include List of included filenames/extensions, other files are ignored
@exclude List of excluded directories/filenames/extensions, these directories and files are ignored
@path List of included paths, other directories are ignored

Using .docheader is the most common way to manage this feature, we don't really need .docheaderconfig or any another file.

Regex patterns

It'd be quite useful to be able to specify placeholders and regex patterns to run.

As an example, in the copyright block, the begin date should be the first year when the specific file was created, not the project. So, it'd be useful to be able to have something like the following in the .docheader:

* @copyright Copyright (c) %re:^20\d{2}$%-%year% Foo Bar. (https://example.com/foo/bar)

I've arbitrarily chose the spec %re:PATTERN%, but I'd be open to other ideas as well. The main thing is that, when encountered, it'd try and match that pattern in order to validate it.

Feature request: apply only to certain file extensions

Hey would it be possible to add a feature to checker license header only for certain file extensions in the projects.
The user could provide the extensions via a flag during script invoking.

Feature request: Support documentation tags

Currently docheader check if the header is strongly identical to the .docheader content.

But this is not really usefull, because we regulary need to add some @tags for the documentation.

Can you support the documentation tags?

/*
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * This software consists of voluntary contributions made by many individuals
 * and is licensed under the MIT license.
 *
 * @category
 * @package
 * @license
 * @author
 */

Manage optional tags like this @tag| would be really usefull 👍

Feature request: auto fix headers

Would be even more useful if when running it can auto fix mismatches :)

Allow multiple directory configuration

I see two different options:

1. allow even more params, f.e.

./vendor/bin/docheader check examples src tests

2. add another config file, f.e.

.docheader - contains a list directories and files to check
.docheaderlicense - contains the sample license

No details when there is an error

I followed the instructions in the documentation and executing the command I had as a message "something went wrong"
there are no details, how could I know where things have gone wrong or what is wrong?