dubpub/publisher

View on GitHub
README.md

Summary

Maintainability
Test Coverage
#.publisher

> Package for publishing or linking files from composer's dependencies.

[![Latest Stable Version](https://poser.pugx.org/dubpub/publisher/v/stable)](https://packagist.org/packages/dubpub/publisher)
[![Total Downloads](https://poser.pugx.org/dubpub/publisher/downloads)](https://packagist.org/packages/dubpub/publisher)
[![Latest Unstable Version](https://poser.pugx.org/dubpub/publisher/v/unstable)](https://packagist.org/packages/dubpub/publisher)
[![Build Status](https://travis-ci.org/dubpub/publisher.svg?branch=master)](https://travis-ci.org/dubpub/publisher)
[![Coverage Status](https://coveralls.io/repos/dubpub/publisher/badge.svg?branch=master&service=github)](https://coveralls.io/github/dubpub/publisher?branch=master)
[![Code Climate](https://codeclimate.com/github/dubpub/publisher/badges/gpa.svg)](https://codeclimate.com/github/dubpub/publisher)

- <a href="#install">Install</a>
- <a href="#schemas-and-syntax">Supported schemas and syntax</a>
    - <a href="#php-example">PHP example</a>
    - <a href="#json-example">JSON example</a>
    - <a href="#ini-example">INI example</a>
    - <a href="#ymlyaml-example">YML,YAML example</a>
- <a href="#usage-in-package">Usage in package</a>
- <a href="#usage-in-project">Usage in project</a>
- <a href="#extending">Extending format support</a>

##Install

**.publisher** can be installed from composer: 

```json
{
    "require": {
        "dubpub/publisher": "1.*"
    }
}
```

Once **.publisher** is installed, it's executable is available from <code>vendor/bin</code> folder, simply run command to check 
the installation:

```bash
$> vendor/bin/publisher
```
 
##Schemas and syntax
 
By default publisher supports following formats: *.php, *.json, *.yaml, *.yml.
Schema must consists of 3 levels - package names, which contains group names, which contains file notations.

- package name
    - file group name
        - file notation
   
File notation examples:

<table width="100%">
    <thead>
        <tr>
            <th width="35%">Notation</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>assets</code></td>
            <td>
                Will copy <code>assets/</code> folder, from package's directory and copy it into configured publish 
                folder.
            </td>
        </tr>
            <td><code>assets/styles.css</code></td>
            <td>
                Will copy <code>assets/styles.css</code>, that's located on package's folder 
                and publish it into configured publish folder.
            </td>
        </tr>
        <tr>
            <td><code>assets/ -> public/</code></td>
            <td>
                Will copy <code>assets/</code> folder, from package's directory and copy it into <code>public/</code> directory configured 
                publish folder.
            </td>
        </tr>
        <tr>
            <td><code>assets -> {public,web}/</code></td>
            <td>    
                Will look up for <code>public/</code> or <code>web/</code> path. If neither are available, first from the list will be 
                created. And <code>assets/</code> folder, from package's directory will be copied into resulting directory.
            </td>
        </tr>
        <tr>
            <td><code>assets/styles/* -> {public,web}/css/</code></td>
            <td>
                Will look up for <code>public/</code>" or <code>web/</code> path. If neither are available, first from the list will be 
                created. And all files from folder <code>assets/styles/</code> of package's directory will be copied into 
                `{resulting directory}/css/`.
            </td>
        </tr>
        <tr>
            <td><code>@path/to/my/link</code></td>
            <td>
                Will create link of package's <code>path/to/my/link</code> and place it in configured publish path. 
            </td>
        </tr>
        <tr>
            <td><code>@path/to/my/* -> bin/</code></td>
            <td>
                Will create links of package's every file from <code>path/to/my/</code> folder and place it in 
                <code>bin/</code> of configured publish path. 
            </td>
        </tr>
    </tbody>
</table>

####PHP example
```php
<?php // .publisher.php
return [
    "myvendor/mypackage" => [
        "assets" => [
            "assets/css/* -> {public/web}/assets/styles/"
        ],
        "bin" => [
          "@bin/executableFile -> bin/"
        ]
    ]
];
```
####JSON example
```json
{
  "myvendor/mypackage": {
    "assets": [
      "assets/css/* -> {public/web}/assets/styles/"
    ],
    "bin": [
      "@bin/executableFile -> bin/"
    ]
  }
}
```
####INI example
```ini
[myvendor/mypackage]
assets[] = "assets/css/* -> {public/web}/assets/styles"
bin[] = "@bin/executableFile -> bin/"
```
####YML,YAML example
```yml
myvendor/mypackage:
    assets:
        - 'assets/css/* ->  {public/web}/assets/styles/'
    bin:
        - '@bin/executableFile -> bin/'
```

##Usage in package
Simply initiate .publisher file an fill it with contents you need, according to examples above and place it into folder where your project's **composer.json** is located. 
Note, that .publisher will not work if **composer.json** file or **vendor/** folder don't exists.

##Usage in project
After installing .publisher into your project you need to generate .publisher file or create it manually. Use **init** command to generate .publisher file:

```bash
$MyProject> vendor/bin/publisher init
```

`init` command will generate .publisher file and perform scanning `vendor/` folder for other .publisher files to merge 
them into new generated one.

If you want to generate .publisher file with specific format(default is php), you need to specify it:

```bash
$MyProject> vendor/bin/publisher init
```

Note, that every `init` call does not recreate or overwrite your (project/package)'s file section, .publisher 
simply merges and updates other sections.

After your .publisher file is generated it's ready to use:

For publishing every .publisher dependency:
```bash
$MyProject> vendor/bin/publisher publish
```
or:
```bash
$> vendor/bin/publisher publish "*"
```

For publishing specific package:
```bash
$> vendor/bin/publisher publish acmevendor/acmepackage
```

For publishing specific package's group:
```bash
$> vendor/bin/publisher publish acmevendor/acmepackage assets
```

For publishing specific packages' groups:
```bash
$> vendor/bin/publisher publish acmevendor/acmepackage,acmevendor1/acmepackage1 assets,configs
```