PHPackages                             williarin/cook - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. williarin/cook

ActiveComposer-plugin[Utility & Helpers](/categories/utility)

williarin/cook
==============

Composer plugin to execute recipes embedded in packages

2.0.0(11mo ago)252.1k↓50%5[2 issues](https://github.com/williarin/cook/issues)3MITPHPPHP >=8.1CI passing

Since Feb 14Pushed 11mo ago2 watchersCompare

[ Source](https://github.com/williarin/cook)[ Packagist](https://packagist.org/packages/williarin/cook)[ RSS](/packages/williarin-cook/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)Dependencies (20)Versions (6)Used By (3)

Cook
====

[](#cook)

Baking recipes for any PHP package.

[![Github Workflow](https://github.com/williarin/cook/workflows/Test/badge.svg)](https://github.com/williarin/cook/actions)

- [Cook](#cook)
    - [Introduction](#introduction)
        - [Features](#features)
    - [Installation](#installation)
    - [Documentation](#documentation)
        - [Creating a recipe](#creating-a-recipe)
            - [Files](#files)
            - [Directories](#directories)
            - [Post install output](#post-install-output)
        - [Mergers](#mergers)
            - [Text](#text)
            - [PHP array](#php-array)
            - [JSON](#json)
            - [YAML](#yaml)
            - [Docker Compose](#docker-compose)
        - [Placeholders](#placeholders)
        - [CLI](#cli)
    - [License](#license)

Introduction
------------

[](#introduction)

Cook is a Composer plugin that executes recipes embedded in packages, in a similar fashion to [Symfony Flex](https://github.com/symfony/flex). It can be used alongside with Flex, or in any other PHP project, as long as Composer is installed.

### Features

[](#features)

- Add new entries to arrays or export new arrays, filter how you want to output it
- Add content to existing files or create them (.env, Makefile, or anything else)
- Copy entire directories from your repository to the project
- Keep existing data by default or overwrite it with a CLI command
- Supports PHP arrays, JSON, YAML, text files
- Output post install instructions
- Process only required packages in the root project
- Uninstall recipe when a package is removed
- CLI commands to install or uninstall recipes

Installation
------------

[](#installation)

```
composer require williarin/cook

```

Make sure to allow the plugin to run. If it's not added automatically, add this in your `composer.json` file:

```
    "config": {
        "allow-plugins": {
            "williarin/cook": true
        }
    },
```

Documentation
-------------

[](#documentation)

### Creating a recipe

[](#creating-a-recipe)

Take a look at [williarin/cook-example](https://github.com/williarin/cook-example) for a working example of a Cook recipe.

To make your package Cook-compatible, you just have to create a valid `cook.yaml` or `cook.json` at the root directory.

The recipe schema must follow this structure:

Top level parameterTypeComments**files**arrayIndividual files to be created or merged.**directories**arrayList of directories to be entirely copied from the package to the project.**post\_install\_output**stringA text to display after installation or update of a package.#### Files

[](#files)

Files are a described as key-value pairs.

- Key is the path to the destination file
- Value is either an array or a string

If a string is given, it must be a path to the source file.

ParameterTypeComments**type**stringType of file.

**Choices:**- `text`
- `php_array`
- `json`
- `yaml`
- `env`
- `docker_compose`

**Default:** `text`
**Optional****destination**stringPath of the destination file in the project that will be created or merged.

**Required****source**stringPath of the source file in the package which content will be used to create or merge in the destination file.

**Required** if **content** isn't defined**content**stringText to merge in the destination file.

**Required** if **source** isn't defined**entries**array<string, mixed>Key-value pairs used to fill a PHP or JSON array.

**Required** if **type** is of type `php_array` or `json`**filters**{keys: array<string>, values: array<string>}Filters for **entries** when **type** is `php_array`.

**Choices:**- `keys`
    - `class_constant` Convert the given string to a class constant. As an example, `'Williarin\Cook'` becomes `Williarin\Cook::class`
- `values`
    - `class_constant` See above
    - `single_line_array` If the value is an array, it will be exported on a single line

**Optional****valid\_sections**array<string>Used if **type** is `yaml` or `json` in order to restrict which top-level parameters need to be merged.

Example: `[parameters, services]`

**Optional****blank\_line\_after**array<string>Used if **type** is `yaml` in order to add a blank line under the merged section.

Example: `[services]`

**Optional****uninstall\_empty\_sections**booleanUsed if **type** is `yaml` in order to remove an empty recipe section when uninstalling the recipe.

**Default:** `false`
**Optional****if\_exists**stringUsed if **type** is `text` or `env`.

**Choices:**- For type `type`
    - `append` Adds content to the end of an existing file, or creates a new one.
    - `overwrite` Overwrites existing content, or creates a new file.
    - `ignore` Doesn't alter an existing file, or creates a new file.
- For type `env`
    - `comment` Comments same name env vars
    - `delete` Delete same name env vars

**Default:** `append` for `text` type. `comment` for `env` type.
**Optional**#### Directories

[](#directories)

Directories are a described as key-value pairs.

- Key is the path to the destination directory that will receive the files
- Value is the path of the source directory in the package that contains the files

#### Post install output

[](#post-install-output)

Maybe you want to display some text to the user after installation.
You can use colors using [Symfony Console](https://symfony.com/doc/current/console/coloring.html) syntax.

### Mergers

[](#mergers)

#### Text

[](#text)

The text merger can be used to extend any text-based file such as:

- .gitignore
- Makefile

As it's the default merger, you can simply use the `destination: source` format in the recipe.

**Example 1:** append to an existing file

Given `yourrepo/recipe/.gitignore` with this content:

```
# Ignore the .env file
.env

```

With this recipe:

```
files:
    .gitignore: recipe/.gitignore
```

The created `.gitignore` file will look like this:

```
###> yourname/yourrepo ###
# Ignore the .env file
.env
###< yourname/yourrepo ###

```

The `###> yourname/yourrepo ###` opening comment and `###< yourname/yourrepo ###` closing comment are used by Cook to identify the recipe in the file. If you're familiar with Symfony Flex, the syntax is the same.

**Example 2:** overwrite an existing file

If you want to overwrite the existing file, you can use the `if_exists` parameter.

```
files:
    .gitignore:
        source: recipe/.gitignore
        if_exists: overwrite
```

This will replace the entire content of the `.gitignore` file with the content of `recipe/.gitignore`.

**Example 3:** ignore an existing file

If you want to ignore the existing file, you can use the `if_exists` parameter.

```
files:
    .gitignore:
        source: recipe/.gitignore
        if_exists: ignore
```

This will not alter the existing `.gitignore` file, and will not create a new one if it doesn't exist.

#### Env

[](#env)

The env merger is used to add new environment variables to an existing `.env` file or create a new one if it doesn't exist.

**Example 1:** merge or create a `.env` file with a given source file

Given `yourrepo/recipe/.env` with this content:

```
SOME_ENV_VARIABLE='hello'
ANOTHER_ENV_VARIABLE='world'
```

And an existing `.env` file in the project with this content:

```
# Existing environment variables
SOME_ENV_VARIABLE='foo'
```

With this recipe:

```
files:
    .env:
        type: env
        source: recipe/.env
```

The created `.env` file will look like this:

```
# Existing environment variables
#SOME_ENV_VARIABLE='foo'

###> yourname/yourrepo ###
SOME_ENV_VARIABLE='hello'
ANOTHER_ENV_VARIABLE='world'
###< yourname/yourrepo ###
```

The existing `SOME_ENV_VARIABLE` is commented out to avoid conflicts with the new value, this is the default behavior of the env merger.

**Example 2:** merge or create a `.env` file with a string input

Alternatively, you can use `content` instead of `source`, to avoid creating a file in your repository.

```
files:
    .env:
        content: |-
            SOME_ENV_VARIABLE='hello'
            ANOTHER_ENV_VARIABLE='world'
```

#### PHP array

[](#php-array)

The PHP array merger adds new entries to existing arrays or creates a file if it doesn't exist.

**Example 1:** without filters

This recipe will create or merge the file `config/bundles.php` in the project.

```
files:
    config/bundles.php:
        type: php_array
        entries:
            Williarin\CookExample\CookExampleBundle:
                dev: true
                test: true
```

The output will look like this:

```