README.md

API Specification

Configuration

Package level

The package level configuration located in extra data. The main target for this configuration is to describe files that can be deleted by Cleaner plugin.

Basic usages

extra:
  dev-files:
  - "/docs/*"
  - "!docs/LICENSE.md"

The example above will be interpreted as the equivalent of below

extra:
  dev-files:
    other: ["/docs/*", "!docs/LICENSE.md"]

All paths are relative to a package root. The other is reserved word.

Advanced usages

extra:
  dev-files:
    bin: ["/bin", "/action/demo.sh"]
    docs: ["/docs", "!docs/LICENSE.md"]
    tests: ["/tests"]
    other: ["/examples/*", "!examples/Bootstrap.md"]

Under the hood

The syntax for paths based on glob function.

Project level

The project level configuration located at config data. The main target for this configuration is to set rules for Cleaner plugin by which it will apply the cleaning.

Default behavior

require:
  # main dependecies
  vendor/package1: *
  vendor/package2: *
  vendor/package3: *
  # you can use the plugin only in current project
  octolab/cleaner: 1.x-dev
  # or you can use it as global `composer global require octolab/cleaner`
config:
  octolab/cleaner:
    clear: ~
    debug: false
    cleaner:    \OctoLab\Cleaner\Util\FileCleaner
    matcher:    \OctoLab\Cleaner\Util\WeightMatcher
    normalizer: \OctoLab\Cleaner\Util\CategoryNormalizer

By default Cleaner plugin do nothing.

Using category

config:
  octolab/cleaner:
    clean:
      vendor/package1: [bin, docs]
      vendor/package2: [tests]
      vendor/package3: [other]

Will be interpreted as

• remove bin and docs categories of dev-files from package vendor/package1
• remove tests category of dev-files from package vendor/package2
• remove other category of dev-files from package vendor/package3

Recommended categories

• bin for command-line related files (for instance, if a project uses Doctrine DBAL only as a library, the bin folder is not needed).

• doc for documentation, manual, readme, etc. (licenses are excluded since they should always stay with packages).

• example for examples, tutorials, etc.

• test for test-related files.

Using asterisk

config:
  octolab/cleaner:
    clean:
      *: *

Will be interpreted as remove all dev-files from all packages.

config:
  octolab/cleaner:
    clean:
      vendor/package1: *

Will be interpreted as remove all dev-files from package vendor/package1.

config:
  octolab/cleaner:
    clean:
      *: [bin]

Will be interpreted as remove bin category of dev-files from all packages.

config:
  octolab/cleaner:
    clean:
      vendor/*: [tests]

Will be interpreted as remove tests category of dev-files from all packages of vendor.

Using denial

config:
  octolab/cleaner:
    clean:
      vendor/package1: [!bin]

Will be interpreted as remove all categories of dev-files except bin from package vendor/package1.

Using combinations

config:
  octolab/cleaner:
    clean:
      *: *
      vendor/package1: [!bin]

Will be interpreted as remove all dev-files from all packages except package vendor/package1 where all categories of dev-files except bin will be removed.

config:
  octolab/cleaner:
    clean:
      *: [bin]
      vendor/package1: [!bin]

Will be interpreted as remove bin category of dev-files from all packages except package vendor/package1 where all categories of dev-files except bin will be removed.

config:
  octolab/cleaner:
    clean:
      *: [!bin]
      vendor/package1: [bin]

Will be interpreted as remove all categories of dev-files except bin from all packages except package vendor/package1 where only category bin of dev-files will be removed.

Weight of operators

1. package: [!]
2. package: [ ]
3. package: *
4. *: [!]
5. *: [ ]
6. *: *

This means that [!docs, docs, *] === [!docs] and [docs, *] === [docs].

Example of usages

Integration test

• vendor/package1 configuration
• vendor/package2 configuration
• vendor/package3 configuration
• project configuration

Extending

You very simply can change the behavior of the plugin by changing classes cleaner, matcher and normalizer. By default, they are represented by the following classes

$default = array(
    ...,
    'cleaner'    => '\OctoLab\Cleaner\Util\FileCleaner',
    'matcher'    => '\OctoLab\Cleaner\Util\WeightMatcher',
    'normalizer' => '\OctoLab\Cleaner\Util\CategoryNormalizer',
);

The main thing that they implement the following interfaces

$interfaces = array(
    'cleaner'    => 'OctoLab\Cleaner\Util\CleanerInterface',
    'matcher'    => 'OctoLab\Cleaner\Util\MatcherInterface',
    'normalizer' => 'OctoLab\Cleaner\Util\NormalizerInterface',
);

The configuration for this looks like

config:
  octolab/cleaner:
    clear: { ... }
    debug: false
    cleaner:    \Your\Cleaner
    matcher:    \Your\Matcher
    normalizer: \Your\Normalizer

Debugging

If you set the debug option to true, then you activate debug mode. In this mode the cleaner option will be ignored and replaced by \OctoLab\Cleaner\Util\FakeCleaner.

The output looks like

You can try this in development installation by the next steps

$ cd tests/integration/project
$ composer install