From 0cebec29bc7f238766445fc58cdaf6a3217f1a87 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 5 Apr 2017 11:17:33 +0200 Subject: [PATCH] Added an initial documentation for Symfony Flex recipes --- README.rst | 350 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 350 insertions(+) create mode 100644 README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..88e74bff --- /dev/null +++ b/README.rst @@ -0,0 +1,350 @@ +Symfony Flex Recipes +==================== + +`Symfony Flex`_ is the new way to manage dependencies in Symfony applications. +One of its main features is the automatic installation, configuration and +removal of dependencies. This automation is possible thanks to the **Symfony Flex +Recipes**. + +Creating Flex Recipes +--------------------- + +Symfony Flex recipes consist of a ``manifest.json`` config file and, optionally, +any number of files and directories. Recipes must be stored on their own +repositories, outside of your Composer package repository. They must follow the +``vendor/package/version/`` directory structure, where ``version`` is the +minimum version supported by the recipe. + +The following example shows the real directory structure of some Symfony recipes: + +:: + + symfony/ + console/ + 3.3/ + bin/ + manifest.json + framework-bundle/ + 3.3/ + etc/ + src/ + web/ + manifest.json + requirements-checker/ + 1.0/ + manifest.json + +All the ``manifest.json`` file contents are optional and they are divided into +options and configurators. + +Options +------- + +``aliases`` option +~~~~~~~~~~~~~~~~~~ + +This option defines one or more alternative names that can be used to install +the dependency. Its value is an array of strings. For example, if a dependency +is published as ``acme-inc/acme-log-monolog-handler``, it can define one or +more aliases to make it easier to install: + +.. code-block:: json + + { + "aliases": ["acme-log", "acmelog"] + } + +Developers can now install this dependency with ``composer require acme-log``. + +``version_aliases`` option +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This option lists all the additional dependency versions (using the ``x.y`` +format) that work with this very same recipe. This avoids duplicating recipes +when a new version of the package is released: + +.. code-block:: json + + // vendor/package-name/3.2/manifest.json + { + "version_aliases": ["3.3", "3.4", "4.0"] + } + +.. note:: + + When using ``version_aliases``, the directory where the recipe is defined + must be the oldest supported version (``3.2`` in the previous example). + +Configurators +------------- + +Recipes define the different tasks executed when installing a dependency, such +as running commands, copying files or adding new environment variables. Recipes +only contain the tasks needed to install and configure the dependency because +Symfony Flex is smart enough to reverse those tasks when uninstalling and +unconfiguring the dependencies. + +Symfony Flex provides eight types of tasks, which are called **configurators**: +``copy-from-recipe``, ``copy-from-package``, ``bundles``, ``env``, ``makefile``, +``composer-scripts``, ``gitignore``, and ``post-install-output``. + +``bundles`` Configurator +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enables one or more bundles in the Symfony application by appending them to the +``bundles.php`` file. Its value is an associative array where the key is the +bundle class name and the value is an array of environments where it must be +enabled. The supported environments are ``dev``, ``prod``, ``test`` and ``all`` +(which enables the bundle in all environments): + +.. code-block:: json + + { + "bundles": { + "Symfony\\Bundle\\DebugBundle\\DebugBundle": ["dev", "test"], + "Symfony\\Bundle\\MonologBundle\\MonologBundle": ["all"] + } + } + +The previous recipe is transformed by Symfony Flex into the following PHP code: + +.. code-block:: php + + // etc/bundles.php + return [ + 'Symfony\Bundle\DebugBundle\DebugBundle' => ['dev' => true, 'test' => true], + 'Symfony\Bundle\MonologBundle\MonologBundle' => ['all' => true], + ]; + +``copy-from-package`` Configurator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Copies files or directories from the Composer package contents to the Symfony +application. It's defined as an associative array where the key is the original +file/directory and the value is the target file/directory. + +This example copies the ``bin/check.php`` script of the package into the binary +directory of the application: + +.. code-block:: json + + { + "copy-from-package": { + "bin/check.php": "%BIN_DIR%/check.php" + } + } + +The ``%BIN_DIR%`` string is a special value that it's turned into the absolute +path of the binaries directory of the Symfony application. These are the special +variables available: ``%BIN_DIR%``, ``%CONF_DIR%``, ``%ETC_DIR%``, ``%SRC_DIR%`` +and ``%WEB_DIR%``. You can also access to any variable defined in the ``extra`` +section of your ``composer.json`` file: + +.. code-block:: json + + // composer.json + { + "...": "...", + + "extra": { + "my-special-dir": "..." + } + } + +Now you can use ``%MY_SPECIAL_DIR%`` in your Symfony Flex recipes. + +``copy-from-recipe`` Configurator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's identical to ``copy-from-package`` but contents are copied from the recipe +itself instead of from the Composer package contents. It's useful to copy the +initial configuration of the dependency and even a simple initial structure of +files and directories: + +.. code-block:: json + + "copy-from-recipe": { + "etc/": "%ETC_DIR%/", + "src/": "%SRC_DIR%/" + } + +``env`` Configurator +~~~~~~~~~~~~~~~~~~~~ + +Adds the given list of environment variables to the ``.env`` and ``.env.dist`` +files stored in the root of the Symfony project: + +.. code-block:: json + + { + "env": { + "APP_ENV": "dev", + "APP_DEBUG": "1" + } + } + +Symfony Flex turns that recipe into the following content appended to the ``.env`` +and ``.env.dist`` files: + +.. code-block:: bash + + ###> your-recipe-name-here ### + APP_ENV=dev + APP_DEBUG=1 + ###< your-recipe-name-here ### + +The ``###> your-recipe-name-here ###`` section separators are needed by +Symfony Flex to detect the contents added by this dependency in case you +uninstall it later. Don't remove or modify these separators. + +``makefile`` Configurator +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Adds new tasks to the ``Makefile`` file stored in the root of the Symfony project. +The value is a simple array where each element is a new line (Symfony Flex adds +a ``PHP_EOL`` character after each line): + +.. code-block:: json + + { + "makefile": [ + "cache-clear:", + "\t@test -f bin/console && bin/console cache:clear --no-warmup || rm -rf var/cache/*", + ".PHONY: cache-clear", + ] + } + +Similar to the ``env`` configurator, the contents are copied into the ``Makefile`` +file and wrapped with section separators (``###> your-recipe-name-here ###``) +that must not be removed or modified. + +``composer-scripts`` Configurator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Registers scripts in the ``auto-scripts`` section of the ``composer.json`` file +to execute them automatically when running ``composer install`` and ``composer +update``. The value is an associative array where the key is the script to +execute (including all its arguments and options) and the value is the type of +script (``php-script`` for PHP scripts, ``script`` for any shell script and +``symfony-cmd`` for Symfony commands): + +.. code-block:: json + + { + "composer-scripts": { + "vendor/bin/security-checker security:check": "php-script", + "make cache-warmup": "script", + "assets:install --symlink --relative %WEB_DIR%": "symfony-cmd" + } + } + +``gitignore`` Configurator +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Adds patterns to the ``.gitignore`` file of the Symfony project. Define those +patterns as a simple array of strings (Symfony Flex adds a ``PHP_EOL`` character +after each line): + +.. code-block:: json + + { + "gitignore": [ + ".env", + "/var/", + "/vendor/", + "/web/bundles/" + ] + } + +Similar to other configurators, the contents are copied into the ``.gitignore`` +file and wrapped with section separators (``###> your-recipe-name-here ###``) +that must not be removed or modified. + +``post-install-output`` Configurator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Displays contents in the command console after the package has been installed. +Avoid outputting meaningless information and use it only when you need to show +help messages or the next step actions. + +The contents are defined as a simple array of strings (Symfony Flex adds a +``PHP_EOL`` character after each line). `Symfony Console styles and colors`_ +are supported too: + +.. code-block:: json + + { + "post-install-output": [ + " What's next? ", + "", + " * Run your application:", + " 1. Execute the make serve command;", + " 2. Browse to the http://localhost:8000/ URL.", + "", + " * Read the documentation at https://symfony.com/doc" + ] + } + +Full Example +------------ + +Combining all the above configurators you can define powerful recipes, like the +one used by ``symfony/framework-bundle``: + +.. code-block:: json + + { + "bundles": { + "Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle": ["all"] + }, + "copy-from-recipe": { + "etc/": "%ETC_DIR%/", + "src/": "%SRC_DIR%/", + "web/": "%WEB_DIR%/" + }, + "composer-scripts": { + "make cache-warmup": "script", + "assets:install --symlink --relative %WEB_DIR%": "symfony-cmd" + }, + "env": { + "APP_ENV": "dev", + "APP_DEBUG": "1", + "APP_SECRET": "Ju$tChang3it!" + }, + "makefile": [ + "cache-clear:", + "\t@test -f bin/console && bin/console cache:clear --no-warmup || rm -rf var/cache/*", + ".PHONY: cache-clear", + "", + "cache-warmup: cache-clear", + "\t@test -f bin/console && bin/console cache:warmup || echo \"cannot warmup the cache (needs symfony/console)\"", + ".PHONY: cache-warmup", + "", + "serve:", + "\t@echo \"\\033[32;49mServer listening on http://127.0.0.1:8000\\033[39m\"", + "\t@echo \"Quit the server with CTRL-C.\"", + "\t@echo \"Run \\033[32mcomposer require symfony/web-server-bundle\\033[39m for a better web server\"", + "\tphp -S 127.0.0.1:8000 -t web", + ".PHONY: serve" + ], + "gitignore": [ + ".env", + "/var/", + "/vendor/", + "/web/bundles/" + ], + "post-install-output": [ + " ", + " What's next? ", + " ", + "", + " * Run your application:", + " 1. Execute the make serve command;", + " 2. Browse to the http://localhost:8000/ URL.", + "", + " * Read the documentation at https://symfony.com/doc" + ] + } + +.. _`Symfony Flex`: https://github.com/symfony/flex +.. _`Symfony Console styles and colors`: https://symfony.com/doc/current/console/coloring.html