- {% block body %}{% endblock %}
-
- {% if self.comments()|trim %}
-
- {% block comments %}{% endblock %}
-
- {% endif%}
-
-
- {% trans %}Free document hosting provided by Read the Docs.{% endtrans %} - -
-
-{% endif %}
-
diff --git a/_build/conf.py b/_build/conf.py
index 1d3adf29dce..ffa92d30604 100644
--- a/_build/conf.py
+++ b/_build/conf.py
@@ -16,11 +16,12 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.append(os.path.abspath('_themes/_exts'))
+sys.path.append(os.path.abspath('_exts'))
# adding PhpLexer
from sphinx.highlighting import lexers
from pygments.lexers.compiled import CLexer
+from pygments.lexers.shell import BashLexer
from pygments.lexers.special import TextLexer
from pygments.lexers.text import RstLexer
from pygments.lexers.web import PhpLexer
@@ -29,16 +30,22 @@
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.8.5'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
- 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
- 'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode', 'sensio.sphinx.bestpractice', 'sensio.sphinx.codeblock',
- 'symfonycom.sphinx'
+ 'sphinx.ext.autodoc', 'sphinx.ext.doctest',
+ 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig',
+ 'sphinx.ext.viewcode', 'sphinx.ext.extlinks',
+ 'sensio.sphinx.codeblock', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode', 'sensio.sphinx.bestpractice'
+ #,'sphinxcontrib.spelling'
]
+#spelling_show_sugestions=True
+#spelling_lang='en_US'
+#spelling_word_list_filename='_build/spelling_word_list.txt'
+
# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_theme/_templates']
@@ -93,7 +100,7 @@
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'symfonycom.sphinx.SensioStyle'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
@@ -107,22 +114,27 @@
lexers['php-standalone'] = PhpLexer(startinline=True)
lexers['php-symfony'] = PhpLexer(startinline=True)
lexers['rst'] = RstLexer()
+lexers['varnish2'] = CLexer()
lexers['varnish3'] = CLexer()
lexers['varnish4'] = CLexer()
lexers['terminal'] = TerminalLexer()
+lexers['env'] = BashLexer()
config_block = {
+ 'apache': 'Apache',
'markdown': 'Markdown',
+ 'nginx': 'Nginx',
'rst': 'reStructuredText',
+ 'varnish2': 'Varnish 2',
'varnish3': 'Varnish 3',
'varnish4': 'Varnish 4'
}
-# use PHP as the primary domain
-primary_domain = 'php'
+# don't enable Sphinx Domains
+primary_domain = None
# set url for API links
-api_url = 'http://api.symfony.com/master/%s'
+api_url = 'https://github.com/symfony/symfony/blob/master/src/%s.php'
# -- Options for HTML output ---------------------------------------------------
@@ -130,12 +142,15 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "sphinx_rtd_theme"
-html_theme_path = ["_themes", ]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+html_theme_options = {
+ 'logo_only': True,
+ 'prev_next_buttons_location': None,
+ 'style_nav_header_background': '#f0f0f0'
+}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
@@ -149,7 +164,7 @@
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
-#html_logo = None
+html_logo = '_static/symfony-logo.svg'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -159,7 +174,8 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+html_static_path = ['_static']
+html_css_files = ['rtd_custom.css']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
diff --git a/_build/maintainer_guide.rst b/_build/maintainer_guide.rst
new file mode 100644
index 00000000000..9788fd057f5
--- /dev/null
+++ b/_build/maintainer_guide.rst
@@ -0,0 +1,341 @@
+Symfony Docs Maintainer Guide
+=============================
+
+The `symfony/symfony-docs`_ repository stores the Symfony project documentation
+and is managed by the `Symfony Docs team`_. This article explains in detail some
+of those management tasks, so it's only useful for maintainers and not regular
+readers or Symfony developers.
+
+Reviewing Pull Requests
+-----------------------
+
+All the recommendations of the `Symfony's respectful review comments`_ apply,
+but there are extra things to keep in mind for maintainers:
+
+* Always be nice in all interactions with all contributors.
+* Be extra-patient with new contributors (GitHub shows a special badge for them).
+* Don't assume that contributors know what you think is obvious (e.g. lots of
+ them don't know what to "squash commits" means).
+* Don't use acronyms like IMO, IIRC, etc. or complex English words (most
+ contributors are not native in English and it's intimidating for them).
+* Never engage in a heated discussion. Lock it right away using GitHub.
+* Never discuss non-tech issues. Some PRs are related to our Diversity initiative
+ and some people always try to drag you into politics. Never engage in that and
+ lock the issue/PR as off-topic on GitHub.
+
+Fixing Minor Issues Yourself
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's common for new contributors to make lots of minor mistakes in the syntax
+of the RST format used in the docs. It's also common for non English speakers to
+make minor typos.
+
+Even if your intention is good, if you add lots of comments when reviewing a
+first contribution, that person will probably not contribute again. It's better
+to fix the minor errors and typos yourself while merging. If that person
+contributes again, it's OK to mention some of the minor issues to educate them.
+
+.. code-block:: terminal
+
+ $ gh merge 11059
+
+ Working on symfony/symfony-docs (branch master)
+ Merging Pull Request 11059: dmaicher/patch-3
+
+ ...
+
+ # This is important!! Say NO to push the changes now
+ Push the changes now? (Y/n) n
+ Now, push with: git push gh "master" refs/notes/github-comments
+
+ # Now, open your editor and make the needed changes ...
+
+ $ git commit -a
+ # Use "Minor reword", "Minor tweak", etc. as the commit message
+
+ # now run the 'push' command shown above by 'gh' (it's different each time)
+ $ git push gh "master" refs/notes/github-comments
+
+Merging Pull Requests
+---------------------
+
+Technical Requirements
+~~~~~~~~~~~~~~~~~~~~~~
+
+* `Git`_ installed and properly configured.
+* ``gh`` tool fully installed according to its installation instructions
+ (GitHub token configured, Git remote configured, etc.)
+ This is a proprietary CLI tool which only Symfony team members have access to.
+* Some previous Git experience, specially merging pull requests.
+
+First Setup
+~~~~~~~~~~~
+
+First, fork the -
-
- {{ _('Versions') }} - {% for slug, url in versions %} -
- {{ slug }} - {% endfor %} -
-
-
- {{ _('Downloads') }} - {% for type, url in downloads %} -
- {{ type }} - {% endfor %} -
-
-
- {{ _('On Read the Docs') }} -
- - {{ _('Project Home') }} - -
- - {{ _('Builds') }} - -
- {% trans %}Free document hosting provided by Read the Docs.{% endtrans %} - -
+
This practice is no longer recommended unless the web application is extremely
simple. Hardcoding URLs can be a disadvantage because:
@@ -33,7 +30,7 @@ simple. Hardcoding URLs can be a disadvantage because:
is essential for some applications because it allows you to control how
the assets are cached. The Asset component allows you to define different
versioning strategies for each package;
-* **Moving assets location** is cumbersome and error-prone: it requires you to
+* **Moving assets' location** is cumbersome and error-prone: it requires you to
carefully update the URLs of all assets included in all templates. The Asset
component allows to move assets effortlessly just by changing the base path
value associated with the package of assets;
@@ -47,9 +44,7 @@ Installation
.. code-block:: terminal
- $ composer require symfony/asset
-
-Alternatively, you can clone the `'.$message.'
';
}
@@ -151,6 +151,9 @@ the following API which is intended mainly for internal purposes:
:method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::getName`
Returns the name of the session bag.
+:method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::clear`
+ Clears out data from bag.
+
.. _attribute-bag-interface:
Attributes
@@ -219,12 +222,12 @@ data is an array, for example a set of tokens. In this case, managing the array
becomes a burden because you have to retrieve the array then process it and
store it again::
- $tokens = array(
- 'tokens' => array(
+ $tokens = [
+ 'tokens' => [
'a' => 'a6c1e0b6',
'b' => 'f4a7b1f3',
- ),
- );
+ ],
+ ];
So any processing of this might quickly get ugly, even simply adding a token to
the array::
@@ -278,7 +281,7 @@ has a simple API
Gets flashes by type and clears those flashes from the bag.
:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::setAll`
- Sets all flashes, accepts a keyed array of arrays ``type => array(messages)``.
+ Sets all flashes, accepts a keyed array of arrays ``type => [messages]``.
:method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::all`
Gets all flashes (as a keyed array of arrays) and clears the flashes from the bag.
@@ -324,12 +327,12 @@ Displaying the flash messages might look as follows.
Simple, display one type of message::
// display warnings
- foreach ($session->getFlashBag()->get('warning', array()) as $message) {
+ foreach ($session->getFlashBag()->get('warning', []) as $message) {
echo ''.$message.'
';
}
// display errors
- foreach ($session->getFlashBag()->get('error', array()) as $message) {
+ foreach ($session->getFlashBag()->get('error', []) as $message) {
echo ''.$message.'
';
}
diff --git a/components/http_foundation/trusting_proxies.rst b/components/http_foundation/trusting_proxies.rst
deleted file mode 100644
index 8c9687aeb2a..00000000000
--- a/components/http_foundation/trusting_proxies.rst
+++ /dev/null
@@ -1,67 +0,0 @@
-.. index::
- single: Request; Trusted Proxies
-
-Trusting Proxies
-================
-
-.. tip::
-
- If you're using the Symfony Framework, start by reading
- :doc:`/deployment/proxies`.
-
-If you find yourself behind some sort of proxy - like a load balancer - then
-certain header information may be sent to you using special ``X-Forwarded-*``
-headers or the ``Forwarded`` header. For example, the ``Host`` HTTP header is
-usually used to return the requested host. But when you're behind a proxy,
-the actual host may be stored in an ``X-Forwarded-Host`` header.
-
-Since HTTP headers can be spoofed, Symfony does *not* trust these proxy
-headers by default. If you are behind a proxy, you should manually whitelist
-your proxy as follows::
-
- use Symfony\Component\HttpFoundation\Request;
-
- // put this code as early as possible in your application (e.g. in your
- // front controller) to only trust proxy headers coming from these IP addresses
- Request::setTrustedProxies(array('192.0.0.1', '10.0.0.0/8'));
-
-.. versionadded:: 2.3
- CIDR notation support was introduced in Symfony 2.3, so you can whitelist whole
- subnets (e.g. ``10.0.0.0/8``, ``fc00::/7``).
-
-You should also make sure that your proxy filters unauthorized use of these
-headers, e.g. if a proxy natively uses the ``X-Forwarded-For`` header, it
-should not allow clients to send ``Forwarded`` headers to Symfony.
-
-If your proxy does not filter headers appropriately, you need to configure
-Symfony not to trust the headers your proxy does not filter (see below).
-
-Configuring Header Names
-------------------------
-
-By default, the following proxy headers are trusted:
-
-* ``Forwarded`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
-* ``X-Forwarded-For`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
-* ``X-Forwarded-Host`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getHost`;
-* ``X-Forwarded-Port`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getPort`;
-* ``X-Forwarded-Proto`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getScheme` and :method:`Symfony\\Component\\HttpFoundation\\Request::isSecure`;
-
-If your reverse proxy uses a different header name for any of these, you
-can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\Request::setTrustedHeaderName`::
-
- Request::setTrustedHeaderName(Request::HEADER_FORWARDED, 'X-Forwarded');
- Request::setTrustedHeaderName(Request::HEADER_CLIENT_IP, 'X-Proxy-For');
- Request::setTrustedHeaderName(Request::HEADER_CLIENT_HOST, 'X-Proxy-Host');
- Request::setTrustedHeaderName(Request::HEADER_CLIENT_PORT, 'X-Proxy-Port');
- Request::setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, 'X-Proxy-Proto');
-
-Not Trusting certain Headers
-----------------------------
-
-By default, if you whitelist your proxy's IP address, then all five headers
-listed above are trusted. If you need to trust some of these headers but
-not others, you can do that as well::
-
- // disables trusting the ``Forwarded`` header
- Request::setTrustedHeaderName(Request::HEADER_FORWARDED, null);
diff --git a/components/http_kernel.rst b/components/http_kernel.rst
index a266da33433..5970157680b 100644
--- a/components/http_kernel.rst
+++ b/components/http_kernel.rst
@@ -16,9 +16,7 @@ Installation
.. code-block:: terminal
- $ composer require symfony/http-kernel
-
-Alternatively, you can clone the `The google tracking code is:
+The google tracking code is:
.. caution:: @@ -123,13 +121,13 @@ JavaScript code isn't written out to your page. This will prevent things like XSS attacks. To do this, use the :method:`Symfony\\Component\\Templating\\PhpEngine::escape` method:: - escape($firstname) ?> + escape($firstname) ?> By default, the ``escape()`` method assumes that the variable is outputted within an HTML context. The second argument lets you change the context. For example, to output something inside JavaScript, use the ``js`` context:: - escape($var, 'js') ?> + escape($var, 'js') ?> The component comes with an HTML and JS escaper. You can register your own escaper using the @@ -144,20 +142,18 @@ escaper using the Helpers ------- -The Templating component can be easily extended via helpers. Helpers are PHP objects that -provide features useful in a template context. The component has -2 built-in helpers: +The Templating component can be extended via helpers. Helpers are PHP objects that +provide features useful in a template context. The component has one built-in helper: -* :doc:`/components/templating/assetshelper` * :doc:`/components/templating/slotshelper` Before you can use these helpers, you need to register them using :method:`Symfony\\Component\\Templating\\PhpEngine::set`:: - use Symfony\Component\Templating\Helper\AssetsHelper; + use Symfony\Component\Templating\Helper\SlotsHelper; // ... - $templating->set(new AssetsHelper()); + $templating->set(new SlotsHelper()); Custom Helpers ~~~~~~~~~~~~~~ @@ -179,7 +175,7 @@ using the Templating component. To do that, create a new class which implements the :class:`Symfony\\Component\\Templating\\EngineInterface`. This requires 3 method: -* :method:`render($name, array $parameters = array()) ?>){kind=logo}
-
-The assets helper can then be configured to render paths to a CDN or modify
-the paths in case your assets live in a sub-directory of your host (e.g. ``http://example.com/app``).
-
-Configure Paths
----------------
-
-By default, the assets helper will prefix all paths with a slash. You can
-configure this by passing a base assets path as the first argument of the
-constructor::
-
- use Symfony\Component\Templating\Helper\AssetsHelper;
-
- // ...
- $templateEngine->set(new AssetsHelper('/foo/bar'));
-
-Now, if you use the helper, everything will be prefixed with ``/foo/bar``:
-
-.. code-block:: html+php
-
-
-
-
-Absolute Urls
--------------
-
-You can also specify a URL to use in the second parameter of the constructor::
-
- // ...
- $templateEngine->set(new AssetsHelper(null, 'http://cdn.example.com/'));
-
-Now URLs are rendered like ``http://cdn.example.com/images/logo.png``.
-
-You can also use the third argument of the helper to force an absolute URL:
-
-.. code-block:: html+php
-
-  ?>){kind=logo}
-
-
-.. note::
-
- If you already set a URL in the constructor, using the third argument of
- ``getUrl()`` will not affect the generated URL.
-
-Versioning
-----------
-
-To avoid using the cached resource after updating the old resource, you can
-use versions which you bump every time you release a new project. The version
-can be specified in the third argument::
-
- // ...
- $templateEngine->set(new AssetsHelper(null, null, '328rad75'));
-
-Now, every URL is suffixed with ``?328rad75``. If you want to have a different
-format, you can specify the new format in fourth argument. It's a string that
-is used in :phpfunction:`sprintf`. The first argument is the path and the
-second is the version. For instance, ``%s?v=%s`` will be rendered as
-``/images/logo.png?v=328rad75``.
-
-You can also generate a versioned URL on an asset-by-asset basis using the
-fourth argument of the helper:
-
-.. code-block:: html+php
-
-  ?>){kind=logo}
-
-
-Multiple Packages
------------------
-
-Asset path generation is handled internally by packages. The component provides
-2 packages by default:
-
-* :class:`Symfony\\Component\\Templating\\Asset\\PathPackage`
-* :class:`Symfony\\Component\\Templating\\Asset\\UrlPackage`
-
-You can also use multiple packages::
-
- use Symfony\Component\Templating\Asset\PathPackage;
-
- // ...
- $templateEngine->set(new AssetsHelper());
-
- $templateEngine->get('assets')->addPackage('images', new PathPackage('/images/'));
- $templateEngine->get('assets')->addPackage('scripts', new PathPackage('/scripts/'));
-
-This will setup the assets helper with 3 packages: the default package which
-defaults to ``/`` (set by the constructor), the images package which prefixes
-it with ``/images/`` and the scripts package which prefixes it with
-``/scripts/``.
-
-If you want to set another default package, you can use
-:method:`Symfony\\Component\\Templating\\Helper\\AssetsHelper::setDefaultPackage`.
-
-You can specify which package you want to use in the second argument of
-:method:`Symfony\\Component\\Templating\\Helper\\AssetsHelper::getUrl`:
-
-.. code-block:: html+php
-
-  ?>)
-
-
-Custom Packages
----------------
-
-You can create your own package by extending
-:class:`Symfony\\Component\\Templating\\Asset\\Package`.
diff --git a/components/templating/slotshelper.rst b/components/templating/slotshelper.rst
index e368b83f86a..42c088c9fd9 100644
--- a/components/templating/slotshelper.rst
+++ b/components/templating/slotshelper.rst
@@ -38,7 +38,7 @@ optional second argument, which is the default value to use if the slot is not
available.
The ``_content`` slot is a special slot set by the ``PhpEngine``. It contains
-the content of the subtemplate.
+the content of the sub-template.
.. caution::
@@ -67,10 +67,10 @@ set in a slot is in the ``_content`` slot.
set('title', $page->title) ?>
- title ?> + title ?>
- body ?> + body ?>
.. note:: diff --git a/components/translation.rst b/components/translation.rst deleted file mode 100644 index 4ee67440aef..00000000000 --- a/components/translation.rst +++ /dev/null @@ -1,234 +0,0 @@ -.. index:: - single: Translation - single: Components; Translation - -The Translation Component -========================= - - The Translation component provides tools to internationalize your - application. - -Installation ------------- - -.. code-block:: terminal - - $ composer require symfony/translation - -Alternatively, you can clone the ` HTML tag: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details
diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst
index b90cbb565da..05dff1ebf61 100644
--- a/contributing/code/conventions.rst
+++ b/contributing/code/conventions.rst
@@ -72,15 +72,15 @@ must be used instead (where ``XXX`` is the name of the related thing):
.. note::
- While "setXXX" and "replaceXXX" are very similar, there is one notable
- difference: "setXXX" may replace, or add new elements to the relation.
- "replaceXXX", on the other hand, cannot add new elements. If an unrecognized
- key is passed to "replaceXXX" it must throw an exception.
+ While ``setXXX()`` and ``replaceXXX()`` are very similar, there is one notable
+ difference: ``setXXX()`` may replace, or add new elements to the relation.
+ ``replaceXXX()``, on the other hand, cannot add new elements. If an unrecognized
+ key is passed to ``replaceXXX()`` it must throw an exception.
.. _contributing-code-conventions-deprecations:
-Deprecations
-------------
+Deprecating Code
+----------------
From time to time, some classes and/or methods are deprecated in the
framework; that happens when a feature implementation cannot be changed
@@ -88,22 +88,38 @@ because of backward compatibility issues, but we still want to propose a
"better" alternative. In that case, the old implementation can simply be
**deprecated**.
-A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to
+Deprecations must only be introduced on the next minor version of the impacted
+component (or bundle, or bridge, or contract).
+They can exceptionally be introduced on previous supported versions if they are critical.
+
+A new class (or interface, or trait) cannot be introduced as deprecated, or
+contain deprecated methods.
+
+A new method cannot be introduced as deprecated.
+
+A feature is marked as deprecated by adding a ``@deprecated`` PHPDoc to
relevant classes, methods, properties, ...::
/**
- * @deprecated since version 2.8, to be removed in 3.0. Use XXX instead.
+ * @deprecated since Symfony 2.8.
+ */
+
+The deprecation message must indicate the version in which the feature was deprecated,
+and whenever possible, how it was replaced::
+
+ /**
+ * @deprecated since Symfony 2.8, use Replacement instead.
*/
-The deprecation message should indicate the version when the class/method was
-deprecated, the version when it will be removed, and whenever possible, how
-the feature was replaced.
+When the replacement is in another namespace than the deprecated class, its FQCN must be used::
+
+ /**
+ * @deprecated since Symfony 2.8, use A\B\Replacement instead.
+ */
-A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with
-the migration starting one or two minor versions before the version where the
-feature will be removed (depending on the criticality of the removal)::
+A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with the migration::
- @trigger_error('XXX() is deprecated since version 2.8 and will be removed in 3.0. Use XXX instead.', E_USER_DEPRECATED);
+ @trigger_error(sprintf('The "%s" class is deprecated since Symfony 2.8, use "%s" instead.', Deprecated::class, Replacement::class), E_USER_DEPRECATED);
Without the `@-silencing operator`_, users would need to opt-out from deprecation
notices. Silencing swaps this behavior and allows users to opt-in when they are
@@ -113,20 +129,59 @@ the Web Debug Toolbar or by the PHPUnit bridge).
.. _`@-silencing operator`: https://php.net/manual/en/language.operators.errorcontrol.php
When deprecating a whole class the ``trigger_error()`` call should be placed
-between the namespace and the use declarations, like in this example from
-`ArrayParserCache`_::
+after the use declarations, like in this example from
+`ServiceRouterLoader`_::
- namespace Symfony\Component\ExpressionLanguage\ParserCache;
+ namespace Symfony\Component\Routing\Loader\DependencyInjection;
- @trigger_error('The '.__NAMESPACE__.'\ArrayParserCache class is deprecated since version 3.2 and will be removed in 4.0. Use the Symfony\Component\Cache\Adapter\ArrayAdapter class instead.', E_USER_DEPRECATED);
+ use Symfony\Component\Routing\Loader\ContainerLoader;
- use Symfony\Component\ExpressionLanguage\ParsedExpression;
+ @trigger_error(sprintf('The "%s" class is deprecated since Symfony 4.4, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class), E_USER_DEPRECATED);
/**
- * @author Adrien Brault
- *
- * @deprecated ArrayParserCache class is deprecated since version 3.2 and will be removed in 4.0. Use the Symfony\Component\Cache\Adapter\ArrayAdapter class instead.
+ * @deprecated since Symfony 4.4, use Symfony\Component\Routing\Loader\ContainerLoader instead.
*/
- class ArrayParserCache implements ParserCacheInterface
+ class ServiceRouterLoader extends ObjectRouteLoader
+
+.. _`ServiceRouterLoader`: https://github.com/symfony/symfony/blob/4.4/src/Symfony/Component/Routing/Loader/DependencyInjection/ServiceRouterLoader.php
+
+The deprecation must be added to the ``CHANGELOG.md`` file of the impacted component::
+
+ 4.4.0
+ -----
+
+ * Deprecated the `Deprecated` class, use `Replacement` instead.
+
+It must also be added to the ``UPGRADE.md`` file of the targeted minor version
+(``UPGRADE-4.4.md`` in our example)::
+
+ DependencyInjection
+ -------------------
+
+ * Deprecated the `Deprecated` class, use `Replacement` instead.
+
+Finally, its consequences must be added to the ``UPGRADE.md`` file of the next major version
+(``UPGRADE-5.0.md`` in our example)::
+
+ DependencyInjection
+ -------------------
+
+ * Removed the `Deprecated` class, use `Replacement` instead.
+
+All these tasks are mandatory and must be done in the same pull request.
+
+Removing Deprecated Code
+------------------------
+
+Removing deprecated code can only be done once every 2 years, on the next major version of the
+impacted component (``master`` branch).
+
+When removing deprecated code, the consequences of the deprecation must be added to the ``CHANGELOG.md`` file
+of the impacted component::
+
+ 5.0.0
+ -----
+
+ * Removed the `Deprecated` class, use `Replacement` instead.
-.. _`ArrayParserCache`: https://github.com/symfony/symfony/blob/3.2/src/Symfony/Component/ExpressionLanguage/ParserCache/ArrayParserCache.php
+This task is mandatory and must be done in the same pull request.
diff --git a/contributing/code/core_team.rst b/contributing/code/core_team.rst
index 0ca248fa0be..47fba9c2d94 100644
--- a/contributing/code/core_team.rst
+++ b/contributing/code/core_team.rst
@@ -29,12 +29,7 @@ The Symfony Core groups, in descending order of priority, are as follows:
2. **Mergers Team**
-* Merge pull requests for the component or components on which they have been
- granted privileges.
-
-3. **Deciders Team**
-
-* Decide to merge or reject a pull request.
+* Merge pull requests on the main Symfony repository.
In addition, there are other groups created to manage specific topics:
@@ -43,6 +38,10 @@ In addition, there are other groups created to manage specific topics:
* Manage the whole security process (triaging reported vulnerabilities, fixing
the reported issues, coordinating the release of security fixes, etc.)
+**Recipes Team**
+
+* Manage the recipes in the main and contrib recipe repositories.
+
**Documentation Team**
* Manage the whole `symfony-docs repository`_.
@@ -50,61 +49,40 @@ In addition, there are other groups created to manage specific topics:
Active Core Members
~~~~~~~~~~~~~~~~~~~
-.. role:: leader
-.. role:: merger
-.. role:: decider
-
* **Project Leader**:
* **Fabien Potencier** (`fabpot`_).
* **Mergers Team** (``@symfony/mergers`` on GitHub):
- * **Tobias Schultze** (`Tobion`_) can merge into the Routing_,
- OptionsResolver_ and PropertyAccess_ components;
-
- * **Nicolas Grekas** (`nicolas-grekas`_) can merge into the Cache_, Debug_,
- Process_, PropertyAccess_, VarDumper_ components, PhpUnitBridge_ and
- the DebugBundle_;
-
- * **Christophe Coevoet** (`stof`_) can merge into all components, bridges and
- bundles;
-
- * **Kévin Dunglas** (`dunglas`_) can merge into the PropertyInfo_ and the Serializer_
- component;
-
- * **Jakub Zalas** (`jakzal`_) can merge into the DomCrawler_ and Intl_
- components;
-
- * **Christian Flothmann** (`xabbuh`_) can merge into the Yaml_ component;
-
- * **Javier Eguiluz** (`javiereguiluz`_) can merge into the WebProfilerBundle_;
-
- * **Grégoire Pineau** (`lyrixx`_) can merge into the Workflow_ component;
-
- * **Ryan Weaver** (`weaverryan`_) can merge into the Security_ component and
- the SecurityBundle_;
-
- * **Robin Chalas** (`chalasr`_) can merge into the Console_ and Security_
- components and the SecurityBundle_;
-
- * **Maxime Steinhausser** (`ogizanagi`_) can merge into Config_, Console_,
- Form_, Serializer_, DependencyInjection_, and HttpKernel_ components;
-
- * **Tobias Nyholm** (`Nyholm`_) manages the official and contrib recipes
- repositories;
-
- * **Samuel Rozé** (`sroze`_) can merge into the Messenger_ component.
+ * **Nicolas Grekas** (`nicolas-grekas`_);
+ * **Christophe Coevoet** (`stof`_);
+ * **Christian Flothmann** (`xabbuh`_);
+ * **Tobias Schultze** (`Tobion`_);
+ * **Kévin Dunglas** (`dunglas`_);
+ * **Jakub Zalas** (`jakzal`_);
+ * **Javier Eguiluz** (`javiereguiluz`_);
+ * **Grégoire Pineau** (`lyrixx`_);
+ * **Ryan Weaver** (`weaverryan`_);
+ * **Robin Chalas** (`chalasr`_);
+ * **Maxime Steinhausser** (`ogizanagi`_);
+ * **Samuel Rozé** (`sroze`_);
+ * **Yonel Ceruto** (`yceruto`_);
+ * **Tobias Nyholm** (`Nyholm`_);
+ * **Wouter De Jong** (`wouterj`_);
+ * **Alexander M. Turek** (`derrabus`_);
+ * **Jérémy Derussé** (`jderusse`_).
-* **Deciders Team** (``@symfony/deciders`` on GitHub):
+* **Security Team** (``@symfony/security`` on GitHub):
- * **Jordi Boggiano** (`seldaek`_);
- * **Lukas Kahwe Smith** (`lsmith77`_).
+ * **Fabien Potencier** (`fabpot`_);
+ * **Michael Cullum** (`michaelcullum`_);
+ * **Jérémy Derussé** (`jderusse`_).
-* **Security Team** (``@symfony/security`` on GitHub):
+* **Recipes Team**:
* **Fabien Potencier** (`fabpot`_);
- * **Michael Cullum** (`michaelcullum`_).
+ * **Tobias Nyholm** (`Nyholm`_).
* **Documentation Team** (``@symfony/team-symfony-docs`` on GitHub):
@@ -114,6 +92,7 @@ Active Core Members
* **Wouter De Jong** (`wouterj`_);
* **Jules Pietri** (`HeahDude`_);
* **Javier Eguiluz** (`javiereguiluz`_).
+ * **Oskar Stark** (`OskarStark`_).
Former Core Members
~~~~~~~~~~~~~~~~~~~
@@ -123,7 +102,9 @@ Symfony contributions:
* **Bernhard Schussek** (`webmozart`_);
* **Abdellatif AitBoudad** (`aitboudad`_);
-* **Romain Neutron**.
+* **Romain Neutron** (`romainneutron`_);
+* **Jordi Boggiano** (`Seldaek`_);
+* **Lukas Kahwe Smith** (`lsmith77`_).
Core Membership Application
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -170,11 +151,11 @@ A pull request **can be merged** if:
* It is a minor change [1]_;
-* Enough time was given for peer reviews (at least 2 days for "regular"
- pull requests, and 4 days for pull requests with "a significant impact");
+* Enough time was given for peer reviews;
-* At least the component's **Merger** or two other Core members voted ``+1``
- and no Core member voted ``-1``.
+* At least two **Merger Team** members voted ``+1`` (only one if the submitter
+ is part of the Merger team) and no Core member voted ``-1`` (via GitHub
+ reviews or as comments).
Pull Request Merging Process
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -199,53 +180,15 @@ discretion of the **Project Leader**.
.. [1] Minor changes comprise typos, DocBlock fixes, code standards
violations, and minor CSS, JavaScript and HTML modifications.
-.. _PhpUnitBridge: https://github.com/symfony/phpunit-bridge
-.. _BrowserKit: https://github.com/symfony/browser-kit
-.. _Cache: https://github.com/symfony/cache
-.. _Config: https://github.com/symfony/config
-.. _Console: https://github.com/symfony/console
-.. _Debug: https://github.com/symfony/debug
-.. _DebugBundle: https://github.com/symfony/debug-bundle
-.. _DependencyInjection: https://github.com/symfony/dependency-injection
-.. _DoctrineBridge: https://github.com/symfony/doctrine-bridge
-.. _EventDispatcher: https://github.com/symfony/event-dispatcher
-.. _DomCrawler: https://github.com/symfony/dom-crawler
-.. _Form: https://github.com/symfony/form
-.. _HttpFoundation: https://github.com/symfony/http-foundation
-.. _HttpKernel: https://github.com/symfony/http-kernel
-.. _Icu: https://github.com/symfony/icu
-.. _Intl: https://github.com/symfony/intl
-.. _LDAP: https://github.com/symfony/ldap
-.. _Locale: https://github.com/symfony/locale
-.. _Messenger: https://github.com/symfony/messenger
-.. _MonologBridge: https://github.com/symfony/monolog-bridge
-.. _OptionsResolver: https://github.com/symfony/options-resolver
-.. _Process: https://github.com/symfony/process
-.. _PropertyAccess: https://github.com/symfony/property-access
-.. _PropertyInfo: https://github.com/symfony/property-info
-.. _Routing: https://github.com/symfony/routing
-.. _Serializer: https://github.com/symfony/serializer
-.. _Translation: https://github.com/symfony/translation
-.. _Security: https://github.com/symfony/security
-.. _SecurityBundle: https://github.com/symfony/security-bundle
-.. _Stopwatch: https://github.com/symfony/stopwatch
-.. _TwigBridge: https://github.com/symfony/twig-bridge
-.. _Validator: https://github.com/symfony/validator
-.. _VarDumper: https://github.com/symfony/var-dumper
-.. _Workflow: https://github.com/symfony/workflow
-.. _Yaml: https://github.com/symfony/yaml
-.. _WebProfilerBundle: https://github.com/symfony/web-profiler-bundle
.. _`symfony-docs repository`: https://github.com/symfony/symfony-docs
.. _`fabpot`: https://github.com/fabpot/
.. _`webmozart`: https://github.com/webmozart/
.. _`Tobion`: https://github.com/Tobion/
-.. _`romainneutron`: https://github.com/romainneutron/
.. _`nicolas-grekas`: https://github.com/nicolas-grekas/
.. _`stof`: https://github.com/stof/
.. _`dunglas`: https://github.com/dunglas/
.. _`jakzal`: https://github.com/jakzal/
.. _`Seldaek`: https://github.com/Seldaek/
-.. _`lsmith77`: https://github.com/lsmith77/
.. _`weaverryan`: https://github.com/weaverryan/
.. _`aitboudad`: https://github.com/aitboudad/
.. _`xabbuh`: https://github.com/xabbuh/
@@ -255,6 +198,12 @@ discretion of the **Project Leader**.
.. _`ogizanagi`: https://github.com/ogizanagi/
.. _`Nyholm`: https://github.com/Nyholm
.. _`sroze`: https://github.com/sroze
+.. _`yceruto`: https://github.com/yceruto
.. _`michaelcullum`: https://github.com/michaelcullum
.. _`wouterj`: https://github.com/wouterj
.. _`HeahDude`: https://github.com/HeahDude
+.. _`OskarStark`: https://github.com/OskarStark
+.. _`romainneutron`: https://github.com/romainneutron
+.. _`lsmith77`: https://github.com/lsmith77/
+.. _`derrabus`: https://github.com/derrabus/
+.. _`jderusse`: https://github.com/jderusse/
diff --git a/contributing/code/experimental.rst b/contributing/code/experimental.rst
new file mode 100644
index 00000000000..9081cf5184c
--- /dev/null
+++ b/contributing/code/experimental.rst
@@ -0,0 +1,23 @@
+Experimental Features
+=====================
+
+All Symfony features benefit from our :doc:`Backward Compatibility Promise
+` to give developers the confidence to upgrade to new
+versions safely and more often.
+
+But sometimes, a new feature is controversial. Or finding a good API is not
+easy. In such cases, we prefer to gather feedback from real-world usage, adapt
+the API, or remove it altogether. Doing so is not possible with a no BC-break
+approach.
+
+To avoid being bound to our backward compatibility promise, such features can
+be marked as **experimental** and their classes and methods must be marked with
+the ``@experimental`` tag.
+
+A feature can be marked as being experimental for only one minor version, and
+can never be introduced in an :ref:`LTS version `. The core team
+can decide to extend the experimental period for another minor version on a
+case by case basis.
+
+To ease upgrading projects using experimental features, the changelog must
+explain backward incompatible changes and explain how to upgrade code.
diff --git a/contributing/code/git.rst b/contributing/code/git.rst
index ce0642c5599..59ca5a4a24d 100644
--- a/contributing/code/git.rst
+++ b/contributing/code/git.rst
@@ -10,8 +10,8 @@ Pull Requests
Whenever a pull request is merged, all the information contained in the pull
request (including comments) is saved in the repository.
-You can easily spot pull request merges as the commit message always follows
-this pattern:
+You can spot pull request merges as the commit message always follows this
+pattern:
.. code-block:: text
diff --git a/contributing/code/index.rst b/contributing/code/index.rst
index 37eb3290c87..0bb29d6abc4 100644
--- a/contributing/code/index.rst
+++ b/contributing/code/index.rst
@@ -6,12 +6,13 @@ Contributing Code
bugs
reproducer
- patches
+ pull_requests
maintenance
core_team
security
tests
bc
+ experimental
standards
conventions
git
diff --git a/contributing/code/license.rst b/contributing/code/license.rst
index 916fbd637f4..8c7c2fd19db 100644
--- a/contributing/code/license.rst
+++ b/contributing/code/license.rst
@@ -5,7 +5,7 @@ Symfony Code License
Symfony code is released under `the MIT license`_:
-Copyright (c) 2004-2018 Fabien Potencier
+Copyright (c) 2004-2020 Fabien Potencier
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/contributing/code/maintenance.rst b/contributing/code/maintenance.rst
index bc16a6cf805..854cd74b219 100644
--- a/contributing/code/maintenance.rst
+++ b/contributing/code/maintenance.rst
@@ -13,7 +13,7 @@ acceptable changes.
.. note::
- When documentation (or phpdoc) is not in sync with the code, code behavior
+ When documentation (or PHPDoc) is not in sync with the code, code behavior
should always be considered as being the correct one.
Besides bug fixes, other minor changes can be accepted in a patch version:
@@ -23,8 +23,8 @@ Besides bug fixes, other minor changes can be accepted in a patch version:
issues (any such patches must come with numbers that show a significant
improvement on real-world code);
-* **Newer versions of PHP/HHVM**: Fixes that add support for newer versions of
- PHP or HHVM are acceptable if they don't break the unit test suite;
+* **Newer versions of PHP**: Fixes that add support for newer versions of
+ PHP are acceptable if they don't break the unit test suite;
* **Newer versions of popular OSes**: Fixes that add support for newer versions
of popular OSes (Linux, MacOS and Windows) are acceptable if they don't break
diff --git a/contributing/code/patches.rst b/contributing/code/pull_requests.rst
similarity index 64%
rename from contributing/code/patches.rst
rename to contributing/code/pull_requests.rst
index 1be2547a16e..816130b1168 100644
--- a/contributing/code/patches.rst
+++ b/contributing/code/pull_requests.rst
@@ -1,10 +1,21 @@
-Submitting a Patch
+Proposing a Change
==================
-Patches are the best way to provide a bug fix or to propose enhancements to
-Symfony.
+A pull request, "PR" for short, is the best way to provide a bug fix or to
+propose enhancements to Symfony.
-Step 1: Setup your Environment
+Step 1: Check existing Issues and Pull Requests
+-----------------------------------------------
+
+Before working on a change, check to see if someone else also raised the topic
+or maybe even started working on a PR by `searching on GitHub`_.
+
+If you are unsure or if you have any questions during this entire process,
+please ask your questions on the ``#contribs`` channel on `Symfony Slack`_.
+
+.. _step-1-setup-your-environment:
+
+Step 2: Setup your Environment
------------------------------
Install the Software Stack
@@ -14,7 +25,7 @@ Before working on Symfony, setup a friendly environment with the following
software:
* Git;
-* PHP version 5.3.9 or above.
+* PHP version 5.5.9 or above.
Configure Git
~~~~~~~~~~~~~
@@ -90,58 +101,71 @@ Check that the current Tests Pass
Now that Symfony is installed, check that all unit tests pass for your
environment as explained in the dedicated :doc:`document `.
-Step 2: Work on your Patch
---------------------------
+.. tip::
+
+ If tests are failing, check on `Travis-CI`_ if the same test is
+ failing there as well. In that case you do not need to be concerned
+ about the test failing locally.
+
+.. _step-2-work-on-your-patch:
+
+Step 3: Work on your Pull Request
+---------------------------------
The License
~~~~~~~~~~~
-Before you start, you must know that all the patches you are going to submit
-must be released under the *MIT license*, unless explicitly specified in your
-commits.
+Before you start, you should be aware that all the code you are going to submit
+must be released under the *MIT license*.
Choose the right Branch
~~~~~~~~~~~~~~~~~~~~~~~
-Before working on a patch, you must determine on which branch you need to
+Before working on a PR, you must determine on which branch you need to
work:
-* ``2.8``, if you are fixing a bug for an existing feature or want to make a
+* ``3.4``, if you are fixing a bug for an existing feature or want to make a
change that falls into the :doc:`list of acceptable changes in patch versions
` (you may have to choose a higher branch if
the feature you are fixing was introduced in a later version);
- * ``master``, if you are adding a new feature.
+* ``5.x``, if you are adding a new feature.
+
+ The only exception is when a new :doc:`major Symfony version `
+ (4.0, 5.0, etc.) comes out every two years. Because of the
+ :ref:`special development process ` of those versions,
+ you need to use the previous minor version for the features (e.g. use ``3.4``
+ instead of ``4.0``, use ``4.4`` instead of ``5.0``, etc.)
.. note::
All bug fixes merged into maintenance branches are also merged into more
- recent branches on a regular basis. For instance, if you submit a patch
- for the ``2.8`` branch, the patch will also be applied by the core team on
- the ``master`` branch.
+ recent branches on a regular basis. For instance, if you submit a PR
+ for the ``3.4`` branch, the PR will also be applied by the core team on
+ the ``5.x`` branch.
Create a Topic Branch
~~~~~~~~~~~~~~~~~~~~~
-Each time you want to work on a patch for a bug or on an enhancement, create a
+Each time you want to work on a PR for a bug or on an enhancement, create a
topic branch:
.. code-block:: terminal
- $ git checkout -b BRANCH_NAME master
+ $ git checkout -b BRANCH_NAME 5.x
-Or, if you want to provide a bugfix for the ``2.8`` branch, first track the remote
-``2.8`` branch locally:
+Or, if you want to provide a bug fix for the ``3.4`` branch, first track the remote
+``3.4`` branch locally:
.. code-block:: terminal
- $ git checkout -t origin/2.8
+ $ git checkout --track origin/3.4
-Then create a new branch off the ``2.8`` branch to work on the bugfix:
+Then create a new branch off the ``3.4`` branch to work on the bug fix:
.. code-block:: terminal
- $ git checkout -b BRANCH_NAME 2.8
+ $ git checkout -b BRANCH_NAME 3.4
.. tip::
@@ -167,8 +191,18 @@ uses, and replaces them by symbolic links to the ones in the Git repository.
Before running the ``link`` command, be sure that the dependencies of the project you
want to debug are installed by running ``composer install`` inside it.
-Work on your Patch
-~~~~~~~~~~~~~~~~~~
+.. tip::
+
+ If symlinks to your local Symfony fork cannot be resolved inside your project due to
+ your dev environment (for instance when using Vagrant where only the current project
+ directory is mounted), you can alternatively use the ``--copy`` option.
+ When finishing testing your Symfony code into your project, you can use
+ the ``--rollback`` option to make your project back to its original dependencies.
+
+.. _work-on-your-patch:
+
+Work on your Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~~~
Work on the code as much as you want and commit as much as you want; but keep
in mind the following:
@@ -181,7 +215,7 @@ in mind the following:
actually works;
* Try hard to not break backward compatibility (if you must do so, try to
- provide a compatibility layer to support the old way) -- patches that break
+ provide a compatibility layer to support the old way) -- PRs that break
backward compatibility have less chance to be merged;
* Do atomic and logically separate commits (use the power of ``git rebase`` to
@@ -199,7 +233,7 @@ in mind the following:
as defined in `PSR-1`_ and `PSR-2`_.
A status is posted below the pull request description with a summary
- of any problems it detects or any Travis CI build failures.
+ of any problems it detects or any `Travis-CI`_ build failures.
.. tip::
@@ -210,10 +244,12 @@ in mind the following:
verb (``fixed ...``, ``added ...``, ...) to start the summary and don't
add a period at the end.
-Prepare your Patch for Submission
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _prepare-your-patch-for-submission:
-When your patch is not about a bug fix (when you add a new feature or change
+Prepare your Pull Request for Submission
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When your PR is not about a bug fix (when you add a new feature or change
an existing one for instance), it must also include the following:
* An explanation of the changes in the relevant ``CHANGELOG`` file(s) (the
@@ -223,30 +259,34 @@ an existing one for instance), it must also include the following:
``UPGRADE`` file(s) if the changes break backward compatibility or if you
deprecate something that will ultimately break backward compatibility.
-Step 3: Submit your Patch
--------------------------
+.. _step-4-submit-your-patch:
+
+Step 4: Submit your Pull Request
+--------------------------------
-Whenever you feel that your patch is ready for submission, follow the
+Whenever you feel that your PR is ready for submission, follow the
following steps.
-Rebase your Patch
-~~~~~~~~~~~~~~~~~
+.. _rebase-your-patch:
+
+Rebase your Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~~
-Before submitting your patch, update your branch (needed if it takes you a
+Before submitting your PR, update your branch (needed if it takes you a
while to finish your changes):
.. code-block:: terminal
- $ git checkout master
+ $ git checkout 5.x
$ git fetch upstream
- $ git merge upstream/master
+ $ git merge upstream/5.x
$ git checkout BRANCH_NAME
- $ git rebase master
+ $ git rebase 5.x
.. tip::
- Replace ``master`` with the branch you selected previously (e.g. ``2.8``)
- if you are working on a bugfix
+ Replace ``5.x`` with the branch you selected previously (e.g. ``3.4``)
+ if you are working on a bug fix.
When doing the ``rebase`` command, you might have to fix merge conflicts.
``git status`` will show you the *unmerged* files. Resolve all the conflicts,
@@ -272,8 +312,8 @@ You can now make a pull request on the ``symfony/symfony`` GitHub repository.
.. tip::
- Take care to point your pull request towards ``symfony:2.8`` if you want
- the core team to pull a bugfix based on the ``2.8`` branch.
+ Take care to point your pull request towards ``symfony:3.4`` if you want
+ the core team to pull a bug fix based on the ``3.4`` branch.
To ease the core team work, always include the modified components in your
pull request message, like in:
@@ -296,10 +336,10 @@ Some answers to the questions trigger some more requirements:
* If you answer yes to "New feature?", you must submit a pull request to the
documentation and reference it under the "Doc PR" section;
-* If you answer yes to "BC breaks?", the patch must contain updates to the
+* If you answer yes to "BC breaks?", the PR must contain updates to the
relevant ``CHANGELOG`` and ``UPGRADE`` files;
-* If you answer yes to "Deprecations?", the patch must contain updates to the
+* If you answer yes to "Deprecations?", the PR must contain updates to the
relevant ``CHANGELOG`` and ``UPGRADE`` files;
* If you answer no to "Tests pass", you must add an item to a todo-list with
@@ -326,9 +366,10 @@ because you want early feedback on your work, add an item to todo-list:
- [ ] gather feedback for my changes
As long as you have items in the todo-list, please prefix the pull request
-title with "[WIP]".
+title with "[WIP]". If you do not yet want to trigger the automated tests,
+you can also set the PR to `draft status`_.
-In the pull request description, give as much details as possible about your
+In the pull request description, give as much detail as possible about your
changes (don't hesitate to give code examples to illustrate your points). If
your pull request is about adding a new feature or modifying an existing one,
explain the rationale for the changes. The pull request description helps the
@@ -339,23 +380,41 @@ commit message).
In addition to this "code" pull request, you must also send a pull request to
the `documentation repository`_ to update the documentation when appropriate.
-Rework your Patch
-~~~~~~~~~~~~~~~~~
+Step 5: Receiving Feedback
+--------------------------
+
+We ask all contributors to follow some
+:doc:`best practices `
+to ensure a constructive feedback process.
+
+If you think someone fails to keep this advice in mind and you want another
+perspective, please join the ``#contribs`` channel on `Symfony Slack`_. If you
+receive feedback you find abusive please contact the
+:doc:`CARE team `.
+
+The :doc:`core team ` is responsible for deciding
+which PR gets merged, so their feedback is the most relevant. So do not feel
+pressured to refactor your code immediately when someone provides feedback.
+
+.. _rework-your-patch:
+
+Rework your Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~~
Based on the feedback on the pull request, you might need to rework your
-patch. Before re-submitting the patch, rebase with ``upstream/master`` or
-``upstream/2.8``, don't merge; and force the push to the origin:
+PR. Before re-submitting the PR, rebase with ``upstream/5.x`` or
+``upstream/3.4``, don't merge; and force the push to the origin:
.. code-block:: terminal
- $ git rebase -f upstream/master
+ $ git rebase -f upstream/5.x
$ git push --force origin BRANCH_NAME
.. note::
When doing a ``push --force``, always specify the branch name explicitly
- to avoid messing other branches in the repo (``--force`` tells Git that
- you really want to mess with things so do it carefully).
+ to avoid messing other branches in the repository (``--force`` tells Git
+ that you really want to mess with things so do it carefully).
Moderators earlier asked you to "squash" your commits. This means you will
convert many commits to one commit. This is no longer necessary today, because
@@ -364,13 +423,13 @@ before merging.
.. _ProGit: https://git-scm.com/book
.. _GitHub: https://github.com/join
-.. _`GitHub's Documentation`: https://help.github.com/articles/ignoring-files
+.. _`GitHub's documentation`: https://help.github.com/articles/ignoring-files
.. _Symfony repository: https://github.com/symfony/symfony
-.. _dev mailing-list: https://groups.google.com/group/symfony-devs
-.. _travis-ci.org: https://travis-ci.org/
-.. _`travis-ci.org status icon`: https://about.travis-ci.com/docs/user/status-images/
-.. _`travis-ci.org Getting Started Guide`: https://about.travis-ci.com/docs/user/getting-started/
.. _`documentation repository`: https://github.com/symfony/symfony-docs
.. _`fabbot`: https://fabbot.io
.. _`PSR-1`: https://www.php-fig.org/psr/psr-1/
.. _`PSR-2`: https://www.php-fig.org/psr/psr-2/
+.. _`searching on GitHub`: https://github.com/symfony/symfony/issues?q=+is%3Aopen+
+.. _`Symfony Slack`: https://symfony.com/slack-invite
+.. _`Travis-CI`: https://travis-ci.org/symfony/symfony
+.. _`draft status`: https://help.github.com/en/articles/about-pull-requests#draft-pull-requests
diff --git a/contributing/code/reproducer.rst b/contributing/code/reproducer.rst
index 26049b094c9..f92cf460ea6 100644
--- a/contributing/code/reproducer.rst
+++ b/contributing/code/reproducer.rst
@@ -2,11 +2,11 @@ Creating a Bug Reproducer
=========================
The main Symfony code repository receives thousands of issues reports per year.
-Some of those issues are so obvious or easy to understand, that Symfony Core
-developers can fix them without any other information. However, other issues are
-much harder to understand because developers can't easily reproduce them in their
-computers. That's when we'll ask you to create a "bug reproducer", which is the
-minimum amount of code needed to make the bug appear when executed.
+Some of those issues are easy to understand and the Symfony Core developers can
+fix them without any other information. However, other issues are much harder to
+understand because developers can't reproduce them in their computers. That's
+when we'll ask you to create a "bug reproducer", which is the minimum amount of
+code needed to make the bug appear when executed.
Reproducing Simple Bugs
-----------------------
@@ -37,7 +37,7 @@ a PHP script, it's better to reproduce the bug by forking the Symfony Standard
edition. To do so:
#. Go to https://github.com/symfony/symfony-standard and click on the **Fork**
- button to make a fork of that repository or go to your already forked copy.
+ button to make a fork of that repository or go to your already-forked copy.
#. Clone the forked repository into your computer:
``git clone git://github.com/YOUR-GITHUB-USERNAME/symfony-standard.git``
#. Browse the project and create a new branch (e.g. ``issue_23567``,
diff --git a/contributing/code/security.rst b/contributing/code/security.rst
index e1c95f4f171..557e4c13501 100644
--- a/contributing/code/security.rst
+++ b/contributing/code/security.rst
@@ -1,9 +1,9 @@
Security Issues
===============
-This document explains how Symfony security issues are handled by the Symfony
-core team (Symfony being the code hosted on the main ``symfony/symfony`` `Git
-repository`_).
+This document explains how Symfony security issues are handled by the
+Symfony core team (Symfony being the code hosted on the main ``symfony/symfony``
+`Git repository`_).
Reporting a Security Issue
--------------------------
@@ -19,7 +19,7 @@ Resolving Process
For each report, we first try to confirm the vulnerability. When it is
confirmed, the core team works on a solution following these steps:
-#. Send an acknowledgement to the reporter;
+#. Send an acknowledgment to the reporter;
#. Work on a patch;
#. Get a CVE identifier from `mitre.org`_;
#. Write a security announcement for the official Symfony `blog`_ about the
@@ -38,7 +38,8 @@ confirmed, the core team works on a solution following these steps:
#. Publish the post on the official Symfony `blog`_ (it must also be added to
the "`Security Advisories`_" category);
#. Update the public `security advisories database`_ maintained by the
- FriendsOfPHP organization and which is used by the ``security:check`` command.
+ FriendsOfPHP organization and which is used by
+ :doc:`the check:security command `.
.. note::
@@ -78,7 +79,7 @@ projects. The process works as follows:
date for a joint release (there is no guarantee that all releases will
be at the same time but we will try hard to make them at about the same
time). When the issue is not known to be exploited in the wild, a period
- of two weeks seems like a reasonable amount of time.
+ of two weeks is considered a reasonable amount of time.
The list of downstream projects participating in this process is kept as small
as possible in order to better manage the flow of confidential information
@@ -91,21 +92,92 @@ of the downstream projects included in this process:
* Drupal (releases typically happen on Wednesdays)
* eZPublish
+Issue Severity
+--------------
+
+In order to determine the severity of a security issue we take into account
+the complexity of any potential attack, the impact of the vulnerability and
+also how many projects it is likely to affect. This score out of 15 is then
+converted into a level of: Low, Medium, High, Critical, or Exceptional.
+
+Attack Complexity
+~~~~~~~~~~~~~~~~~
+
+*Score of between 1 and 5 depending on how complex it is to exploit the
+vulnerability*
+
+* 4 - 5 Basic: attacker must follow a set of simple steps
+* 2 - 3 Complex: attacker must follow non-intuitive steps with a high level
+ of dependencies
+* 1 - 2 High: A successful attack depends on conditions beyond the attacker's
+ control. That is, a successful attack cannot be accomplished at will, but
+ requires the attacker to invest in some measurable amount of effort in
+ preparation or execution against the vulnerable component before a successful
+ attack can be expected.
+
+Impact
+~~~~~~
+
+*Scores from the following areas are added together to produce a score. The
+score for Impact is capped at 6. Each area is scored between 0 and 4.*
+
+* Integrity: Does this vulnerability cause non-public data to be accessible?
+ If so, does the attacker have control over the data disclosed? (0-4)
+* Disclosure: Can this exploit allow system data (or data handled by the
+ system) to be compromised? If so, does the attacker have control over
+ modification? (0-4)
+* Code Execution: Does the vulnerability allow arbitrary code to be executed
+ on an end-users system, or the server that it runs on? (0-4)
+* Availability: Is the availability of a service or application affected? Is
+ it reduced availability or total loss of availability of a service /
+ application? Availability includes networked services (e.g., databases) or
+ resources such as consumption of network bandwidth, processor cycles, or
+ disk space. (0-4)
+
+Affected Projects
+~~~~~~~~~~~~~~~~~
+
+*Scores from the following areas are added together to produce a score. The
+score for Affected Projects is capped at 4.*
+
+* Will it affect some or all using a component? (1-2)
+* Is the usage of the component that would cause such a thing already
+ considered bad practice? (0-1)
+* How common/popular is the component (e.g. Console vs HttpFoundation vs
+ Lock)? (0-2)
+* Are a number of well-known open source projects using Symfony affected
+ that requires coordinated releases? (0-1)
+
+Score Totals
+~~~~~~~~~~~~
+
+* Attack Complexity: 1 - 5
+* Impact: 1 - 6
+* Affected Projects: 1 - 4
+
+Severity levels
+~~~~~~~~~~~~~~~
+
+* Low: 1 - 5
+* Medium: 6 - 10
+* High: 11 - 12
+* Critical: 13 - 14
+* Exceptional: 15
+
Security Advisories
-------------------
.. tip::
You can check your Symfony application for known security vulnerabilities
- using the ``security:check`` command (see :doc:`/security/security_checker`).
+ using the ``check:security`` command (see :doc:`/security/security_checker`).
Check the `Security Advisories`_ blog category for a list of all security
vulnerabilities that were fixed in Symfony releases, starting from Symfony
1.0.0.
-.. _Git repository: https://github.com/symfony/symfony
+.. _`Git repository`: https://github.com/symfony/symfony
.. _blog: https://symfony.com/blog/
-.. _Security Advisories: https://symfony.com/blog/category/security-advisories
.. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories
.. _`mitre.org`: https://cveform.mitre.org/
.. _`Security Advisories`: https://symfony.com/blog/category/security-advisories
diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst
index 329d6d83b36..2cf52addf82 100644
--- a/contributing/code/standards.rst
+++ b/contributing/code/standards.rst
@@ -27,11 +27,7 @@ Symfony Coding Standards in Detail
----------------------------------
If you want to learn about the Symfony coding standards in detail, here's a
-short example containing most features described below:
-
-.. code-block:: html+php
-
- fooBar = $this->transformText($dummy);
+ $this->qux = $qux;
}
/**
@@ -71,7 +72,7 @@ short example containing most features described below:
*/
public function someDeprecatedMethod()
{
- @trigger_error(sprintf('The %s() method is deprecated since version 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);
+ @trigger_error(sprintf('The %s() method is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);
return Baz::someMethod();
}
@@ -86,16 +87,16 @@ short example containing most features described below:
*
* @throws \RuntimeException When an invalid option is provided
*/
- private function transformText($dummy, array $options = array())
+ private function transformText($dummy, array $options = [])
{
- $defaultOptions = array(
+ $defaultOptions = [
'some_default' => 'values',
'another_default' => 'more values',
- );
+ ];
- foreach ($options as $option) {
- if (!in_array($option, $defaultOptions)) {
- throw new \RuntimeException(sprintf('Unrecognized option "%s"', $option));
+ foreach ($options as $name => $value) {
+ if (!array_key_exists($name, $defaultOptions)) {
+ throw new \RuntimeException(sprintf('Unrecognized option "%s"', $name));
}
}
@@ -105,33 +106,34 @@ short example containing most features described below:
);
if (true === $dummy) {
- return null;
+ return 'something';
}
- if ('string' === $dummy) {
+ if (is_string($dummy)) {
if ('values' === $mergedOptions['some_default']) {
return substr($dummy, 0, 5);
}
return ucwords($dummy);
}
+
+ return null;
}
/**
- * Performs some basic check for a given value.
+ * Performs some basic operations for a given value.
*
- * @param mixed $value Some value to check against
+ * @param mixed $value Some value to operate against
* @param bool $theSwitch Some switch to control the method's flow
- *
- * @return bool|void The resultant check if $theSwitch isn't false, void otherwise
*/
- private function reverseBoolean($value = null, $theSwitch = false)
+ private function performOperations($value = null, $theSwitch = false)
{
if (!$theSwitch) {
return;
}
- return !$value;
+ $this->qux->doFoo($value);
+ $this->qux->doBar($value);
}
}
@@ -213,7 +215,7 @@ Naming Conventions
* Prefix all abstract classes with ``Abstract`` except PHPUnit ``*TestCase``.
Please note some early Symfony classes do not follow this convention and
- have not been renamed for backward compatibility reasons. However all new
+ have not been renamed for backward compatibility reasons. However, all new
abstract classes must follow this naming convention;
* Suffix interfaces with ``Interface``;
@@ -238,13 +240,19 @@ Naming Conventions
Service Naming Conventions
~~~~~~~~~~~~~~~~~~~~~~~~~~
-* A service name contains groups, separated by dots;
+* A service name must be the same as the fully qualified class name (FQCN) of
+ its class (e.g. ``App\EventSubscriber\UserSubscriber``);
-* The DI alias of the bundle is the first group (e.g. ``fos_user``);
+* If there are multiple services for the same class, use the FQCN for the main
+ service and use lowercase and underscored names for the rest of services.
+ Optionally divide them in groups separated with dots (e.g.
+ ``something.service_name``, ``fos_user.something.service_name``);
-* Use lowercase letters for service and parameter names;
+* Use lowercase letters for parameter names (except when referring
+ to environment variables with the ``%env(VARIABLE_NAME)%`` syntax);
-* A group name uses the underscore notation.
+* Add class aliases for public services (e.g. alias ``Symfony\Component\Something\ClassName``
+ to ``something.service_name``).
Documentation
~~~~~~~~~~~~~
@@ -266,7 +274,7 @@ Documentation
* When adding a new class or when making significant changes to an existing class,
an ``@author`` tag with personal contact information may be added, or expanded.
Please note it is possible to have the personal contact information updated or
- removed per request to the doc:`core team `.
+ removed per request to the :doc:`core team `.
License
~~~~~~~
@@ -274,7 +282,7 @@ License
* Symfony is released under the MIT license, and the license block has to be
present at the top of every PHP file, before the namespace.
-.. _`PHP CS Fixer tool`: http://cs.sensiolabs.org/
+.. _`PHP CS Fixer tool`: https://cs.symfony.com/
.. _`PSR-0`: https://www.php-fig.org/psr/psr-0/
.. _`PSR-1`: https://www.php-fig.org/psr/psr-1/
.. _`PSR-2`: https://www.php-fig.org/psr/psr-2/
diff --git a/contributing/code/tests.rst b/contributing/code/tests.rst
index 968ad1c95cf..75c72e0128d 100644
--- a/contributing/code/tests.rst
+++ b/contributing/code/tests.rst
@@ -4,11 +4,11 @@ Running Symfony Tests
=====================
The Symfony project uses a third-party service which automatically runs tests
-for any submitted :doc:`patch `. If the new code breaks any test,
+for any submitted :doc:`patch `. If the new code breaks any test,
the pull request will show an error message with a link to the full error details.
In any case, it's a good practice to run tests locally before submitting a
-:doc:`patch ` for inclusion, to check that you have not broken anything.
+:doc:`patch ` for inclusion, to check that you have not broken anything.
.. _phpunit:
.. _dependencies_optional:
@@ -18,7 +18,7 @@ Before Running the Tests
To run the Symfony test suite, install the external dependencies used during the
tests, such as Doctrine, Twig and Monolog. To do so,
-:doc:`install Composer ` and execute the following:
+`install Composer`_ and execute the following:
.. code-block:: terminal
@@ -54,6 +54,7 @@ what's going on and if the tests are broken because of the new code.
On Windows, install the `Cmder`_, `ConEmu`_, `ANSICON`_ or `Mintty`_ free applications
to see colored test results.
+.. _`install Composer`: https://getcomposer.org/download/
.. _Cmder: http://cmder.net/
.. _ConEmu: https://conemu.github.io/
.. _ANSICON: https://github.com/adoxa/ansicon/releases
diff --git a/contributing/code_of_conduct/care_team.rst b/contributing/code_of_conduct/care_team.rst
index 04b7fdbad82..ae342b89999 100644
--- a/contributing/code_of_conduct/care_team.rst
+++ b/contributing/code_of_conduct/care_team.rst
@@ -4,22 +4,24 @@ CARE Team
Our Pledge
----------
-In the interest of fostering an open and welcoming environment, the CoC Active Response Ensurers, or CARE,
-pledge to ensure that the spirit of the :doc:`Code of Conduct `
+In the interest of fostering an open and welcoming environment, the "Code of
+Conduct Active Response Ensurers", or CARE team, pledge to ensure that the
+spirit of the :doc:`Code of Conduct `
is respected. Our main priority is to ensure the safety of our community members.
-The second goal is to help educate the community as a whole to be aware of the CoC
-and how to help implement its spirit throughout the community. In case these goals
-conflict, we will prioritize safety of community members over all other goals.
+The second goal is to help educate the community as a whole to be aware of the
+Code of Conduct and how to help implement its spirit throughout the community.
+In case these goals conflict, we will prioritize safety of community members
+over all other goals.
-If you think there is or has been a violation to the code of conduct please contact
+If you think there is or has been a violation to the Code of Conduct please contact
the CARE team or if you prefer contact only individual members of the CARE team.
Members
-------
-Here are all the members of the Code of Conduct CARE team (in alphabetic order).
-You can contact any of them directly using the contact details below or you can
-also contact all of them at once by emailing **coc@symfony.com**:
+Here are all the members of the CARE team (in alphabetic order). You can contact
+any of them directly using the contact details below or you can also contact all
+of them at once by emailing **care@symfony.com**:
* **Emilie Lorenzo**
@@ -29,7 +31,7 @@ also contact all of them at once by emailing **coc@symfony.com**:
* **Michelle Sanver**
- * *E-mail*: hello [at] michellesanver.com
+ * *E-mail*: michelle [at] liip.ch
* *Twitter*: `@michellesanver `_
* *SymfonyConnect*: `michellesanver `_
@@ -46,3 +48,12 @@ The :doc:`Symfony project leader ` appoints the CA
team with candidates they see fit. The CARE team will consist of at least
3 people. The team should be representing as many demographics as possible,
ideally from different employers.
+
+CARE Team Transparency Reports
+------------------------------
+
+The CARE team publishes a transparency report at the end of each year:
+
+* `Symfony Code of Conduct Transparency Report 2018`_.
+
+.. _`Symfony Code of Conduct Transparency Report 2018`: https://symfony.com/blog/symfony-code-of-conduct-transparency-report-2018
diff --git a/contributing/code_of_conduct/code_of_conduct.rst b/contributing/code_of_conduct/code_of_conduct.rst
index 7ecd91e8dbd..857d5437538 100644
--- a/contributing/code_of_conduct/code_of_conduct.rst
+++ b/contributing/code_of_conduct/code_of_conduct.rst
@@ -37,7 +37,7 @@ Examples of unacceptable behavior by participants include:
Our Responsibilities
--------------------
-:doc:`CoC Active Response Ensurers, or CARE`,
+:doc:`CoC Active Response Ensurers, or CARE `,
are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
diff --git a/contributing/code_of_conduct/concrete_example_document.rst b/contributing/code_of_conduct/concrete_example_document.rst
index 6f1277a625a..ddd1c9b84c8 100644
--- a/contributing/code_of_conduct/concrete_example_document.rst
+++ b/contributing/code_of_conduct/concrete_example_document.rst
@@ -2,7 +2,7 @@ Code of Conduct: Concrete Example Document
==========================================
This is a living document that serves to give concrete examples of
-unwanted behaviour. These examples have all taken place somewhere in the
+unwanted behavior. These examples have all taken place somewhere in the
PHP community in the past, and are clear code of conduct violations
according to the Symfony code of conduct.
diff --git a/contributing/code_of_conduct/reporting_guidelines.rst b/contributing/code_of_conduct/reporting_guidelines.rst
index 1766d025e4d..63c4e820ce6 100644
--- a/contributing/code_of_conduct/reporting_guidelines.rst
+++ b/contributing/code_of_conduct/reporting_guidelines.rst
@@ -69,7 +69,7 @@ let them know what action (if any) we'll be taking. We'll take into account feed
from the reporter on the appropriateness of our response, but our response will be
determined by what will be best for community safety.
-The CARE team keeps a private record of all incidents. By default all reports
+The CARE team keeps a private record of all incidents. By default, all reports
are shared with the entire CARE team unless the reporter specifically asks
to exclude specific CARE team members, in which case these CARE team
members will not be included in any communication on the incidents as well as records
diff --git a/contributing/community/index.rst b/contributing/community/index.rst
index 70cb60c740e..4a5aab91265 100644
--- a/contributing/community/index.rst
+++ b/contributing/community/index.rst
@@ -9,4 +9,3 @@ Community
reviews
mentoring
speaker-mentoring
- other
diff --git a/contributing/community/other.rst b/contributing/community/other.rst
deleted file mode 100644
index 2196ccb925c..00000000000
--- a/contributing/community/other.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-Other Resources
-===============
-
-In order to follow what is happening in the community you might find helpful
-these additional resources:
-
-* List of open `pull requests`_
-* List of recent `commits`_
-* List of open `bugs and enhancements`_
-* List of open source `bundles`_
-
-.. _pull requests: https://github.com/symfony/symfony/pulls
-.. _commits: https://github.com/symfony/symfony/commits/master
-.. _bugs and enhancements: https://github.com/symfony/symfony/issues
-.. _bundles: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories
diff --git a/contributing/community/releases.rst b/contributing/community/releases.rst
index 2662af995ec..d2336e21e86 100644
--- a/contributing/community/releases.rst
+++ b/contributing/community/releases.rst
@@ -1,17 +1,25 @@
The Release Process
===================
-This document explains the **release process** of the Symfony project (i.e. the
-code hosted on the main ``symfony/symfony`` `Git repository`_).
+This document explains the process followed by the Symfony project to develop,
+release and maintain its different versions.
-Symfony manages its releases through a *time-based model* and follows the
-`Semantic Versioning`_ strategy:
+Symfony releases follow the `semantic versioning`_ strategy and they are
+published through a *time-based model*:
-* A new Symfony minor version (e.g. 2.8, 3.2, 4.1) comes out every *six months*:
- one in *May* and one in *November*;
-* A new Symfony major version (e.g., 3.0, 4.0) comes out every *two years* and
- it's released at the same time of the last minor version of the previous major
- version.
+* A new **Symfony patch version** (e.g. 2.8.15, 4.1.7) comes out roughly every
+ month. It only contains bug fixes, so you can safely upgrade your applications;
+* A new **Symfony minor version** (e.g. 2.8, 3.2, 4.1) comes out every *six months*:
+ one in *May* and one in *November*. It contains bug fixes and new features, but
+ it doesn't include any breaking change, so you can safely upgrade your applications;
+* A new **Symfony major version** (e.g. 3.0, 4.0) comes out every *two years*.
+ It can contain breaking changes, so you may need to do some changes in your
+ applications before upgrading.
+
+.. tip::
+
+ `Subscribe to Symfony Roadmap notifications`_ to receive an email when a new
+ Symfony version is published or when a Symfony version reaches its end of life.
.. _contributing-release-development:
@@ -32,113 +40,36 @@ During the development phase, any new feature can be reverted if it won't be
finished in time or if it won't be stable enough to be included in the current
final release.
+.. tip::
+
+ Check out the `Symfony Roadmap`_ to learn more about any specific version.
+
.. _contributing-release-maintenance:
+.. _symfony-versions:
+.. _releases-lts:
Maintenance
-----------
-Each Symfony version is maintained for a fixed period of time, depending on the
-type of the release. This maintenance is divided into:
+Starting from the Symfony 3.x branch, the number of minor versions is limited to
+five per branch (X.0, X.1, X.2, X.3 and X.4). The last minor version of a branch
+(e.g. 3.4, 4.4, 5.4) is considered a **long-term support version** and the other
+ones are considered **standard versions**:
-* *Bug fixes and security fixes*: During this period, all issues can be fixed.
- The end of this period is referenced as being the *end of maintenance* of a
- release.
-
-* *Security fixes only*: During this period, only security related issues can
- be fixed. The end of this period is referenced as being the *end of life* of
- a release.
+======================= ===================== ================================
+Version Type Bugs are fixed for... Security issues are fixed for...
+======================= ===================== ================================
+Standard 8 months 14 months
+Long-Term Support (LTS) 3 years 4 years
+======================= ===================== ================================
.. note::
- The :doc:`maintenance document ` describes
- the boundaries of acceptable changes during maintenance.
-
-Symfony Versions
-----------------
-
-Standard Versions
-~~~~~~~~~~~~~~~~~
-
-A **Standard Minor Version** is maintained for an *eight month* period for bug
-fixes, and for a *fourteen month* period for security issue fixes.
-
-In Symfony 2.x branch, the number of minor versions wasn't constrained, so that
-branch ended up with nine minor versions (from 2.0 to 2.8). Starting from
-3.x branch, the number of minor versions is limited to five (from X.0 to X.4).
-
-.. _releases-lts:
-
-Long Term Support Versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Every two years, a new **Long Term Support Version** (usually abbreviated as "LTS")
-is published. Each LTS version is supported for a *three year* period for bug
-fixes, and for a *four year* period for security issue fixes.
-
-.. note::
+ After the active maintenance of a Symfony version has ended, you can get
+ `professional Symfony support`_ from SensioLabs, the company which sponsors
+ the Symfony project.
- Paid support after the three year support provided by the community can
- also be bought from `SensioLabs`_.
-
-In the Symfony 2.x branch, the LTS versions are 2.3, 2.7 and 2.8. Starting from the 3.x
-branch, only the last minor version of each branch is considered LTS (e.g. 3.4,
-4.4, 5.4, etc.)
-
-Schedule
---------
-
-Below is the schedule for the first few versions that use this release model:
-
-.. image:: /_images/contributing/release-process.jpg
- :align: center
-
-* **Yellow** represents the Development phase
-* **Blue** represents the Stabilization phase
-* **Green** represents the Maintenance period
-
-.. tip::
-
- If you want to learn more about the timeline of any given Symfony version,
- use the online `timeline calculator`_.
-
-.. tip::
-
- Whenever an important event related to Symfony versions happens (a version
- reaches end of maintenance or a new patch version is released for
- instance), you can automatically receive an email notification if you
- subscribed on the `roadmap notification`_ page.
-
-.. _version-history:
-
-============ ============== ======= ======================== ===========
-Version Feature Freeze Release End of Maintenance End of Life
-============ ============== ======= ======================== ===========
-`2.0`_ 05/2011 07/2011 03/2013 (20 months) 09/2013
-`2.1`_ 07/2012 09/2012 05/2013 (9 months) 11/2013
-`2.2`_ 01/2013 03/2013 11/2013 (8 months) 05/2014
-`2.3`_ (LTS) 03/2013 05/2013 05/2016 (36 months) 05/2017
-`2.4`_ 09/2013 11/2013 09/2014 (10 months [1]_) 01/2015
-`2.5`_ 03/2014 05/2014 01/2015 (8 months) 07/2015
-`2.6`_ 09/2014 11/2014 07/2015 (8 months) 01/2016
-`2.7`_ (LTS) 03/2015 05/2015 05/2018 (36 months) 05/2019
-`2.8`_ (LTS) 09/2015 11/2015 11/2018 (36 months [2]_) 11/2019
-`3.0`_ 09/2015 11/2015 07/2016 (8 months [3]_) 01/2017
-`3.1`_ 03/2016 05/2016 01/2017 (8 months) 07/2017
-`3.2`_ 09/2016 11/2016 07/2017 (8 months) 01/2018
-`3.3`_ 03/2017 05/2017 01/2018 (8 months) 07/2018
-`3.4`_ (LTS) 09/2017 11/2017 11/2020 (36 months) 11/2021
-`4.0`_ 09/2017 11/2017 07/2018 (8 months) 01/2019
-`4.1`_ 03/2018 05/2018 01/2019 (8 months) 07/2019
-`4.2`_ 09/2018 11/2018 07/2019 (8 months) 01/2020
-`4.3`_ 03/2019 05/2019 01/2020 (8 months) 07/2020
-`4.4`_ (LTS) 09/2019 11/2019 11/2022 (36 months) 11/2023
-`5.0`_ 09/2019 11/2019 07/2020 (8 months) 01/2021
-... ... ... ... ...
-============ ============== ======= ======================== ===========
-
-.. [1] Symfony 2.4 maintenance has been `extended to September 2014`_.
-.. [2] Symfony 2.8 is the last version of the Symfony 2.x branch.
-.. [3] Symfony 3.0 is the first version to use the new release process based on five minor releases.
+.. _deprecations:
Backward Compatibility
----------------------
@@ -147,18 +78,29 @@ Our :doc:`Backward Compatibility Promise ` is very
strict and allows developers to upgrade with confidence from one minor version
of Symfony to the next one.
-Whenever keeping backward compatibility is not possible, the feature, the
-enhancement or the bug fix will be scheduled for the next major version.
-
-Deprecations
-------------
-
When a feature implementation cannot be replaced with a better one without
-breaking backward compatibility, there is still the possibility to deprecate
-the old implementation and add a new preferred one along side. Read the
+breaking backward compatibility, Symfony deprecates the old implementation and
+adds a new preferred one along side. Read the
:ref:`conventions ` document to
learn more about how deprecations are handled in Symfony.
+.. _major-version-development:
+
+This deprecation policy also requires a custom development process for major
+versions (4.0, 5.0, 6.0, etc.) In those cases, Symfony develops at the same time
+two versions: the new major one (e.g. 4.0) and the latest version of the
+previous branch (e.g. 3.4).
+
+Both versions have the same new features, but they differ in the deprecated
+features. The oldest version (3.4 in this example) contains all the deprecated
+features whereas the new version (4.0 in this example) removes all of them.
+
+This allows you to upgrade your projects to the latest minor version (e.g. 3.4),
+see all the deprecation messages and fix them. Once you have fixed all those
+deprecations, you can upgrade to the new major version (e.g. 4.0) without
+effort, because it contains the same features (the only difference are the
+deprecated features, which your project no longer uses).
+
Rationale
---------
@@ -174,7 +116,9 @@ This release process was adopted to give more *predictability* and
* Coordinate the Symfony timeline with popular PHP projects that work well
with Symfony and with projects using Symfony;
* Give time to the Symfony ecosystem to catch up with the new versions
- (bundle authors, documentation writers, translators, ...).
+ (bundle authors, documentation writers, translators, ...);
+* Give companies a strict and predictable timeline they can rely on to plan
+ their own projects development.
The six month period was chosen as two releases fit in a year. It also allows
for plenty of time to work on new features and it allows for non-ready
@@ -187,29 +131,7 @@ version: a new version is published every six months, and there is a two months
period to upgrade. Companies wanting more stability use the LTS versions: a new
version is published every two years and there is a year to upgrade.
-.. _Semantic Versioning: https://semver.org/
-.. _Git repository: https://github.com/symfony/symfony
-.. _SensioLabs: https://sensiolabs.com/
-.. _roadmap notification: https://symfony.com/roadmap
-.. _extended to September 2014: https://symfony.com/blog/extended-maintenance-for-symfony-2-4
-.. _timeline calculator: https://symfony.com/roadmap#checker
-.. _`2.0`: https://symfony.com/roadmap?version=2.0
-.. _`2.1`: https://symfony.com/roadmap?version=2.1
-.. _`2.2`: https://symfony.com/roadmap?version=2.2
-.. _`2.3`: https://symfony.com/roadmap?version=2.3
-.. _`2.4`: https://symfony.com/roadmap?version=2.4
-.. _`2.5`: https://symfony.com/roadmap?version=2.5
-.. _`2.6`: https://symfony.com/roadmap?version=2.6
-.. _`2.7`: https://symfony.com/roadmap?version=2.7
-.. _`2.8`: https://symfony.com/roadmap?version=2.8
-.. _`3.0`: https://symfony.com/roadmap?version=3.0
-.. _`3.1`: https://symfony.com/roadmap?version=3.1
-.. _`3.2`: https://symfony.com/roadmap?version=3.2
-.. _`3.3`: https://symfony.com/roadmap?version=3.3
-.. _`3.4`: https://symfony.com/roadmap?version=3.4
-.. _`4.0`: https://symfony.com/roadmap?version=4.0
-.. _`4.1`: https://symfony.com/roadmap?version=4.1
-.. _`4.2`: https://symfony.com/roadmap?version=4.2
-.. _`4.3`: https://symfony.com/roadmap?version=4.3
-.. _`4.4`: https://symfony.com/roadmap?version=4.4
-.. _`5.0`: https://symfony.com/roadmap?version=5.0
+.. _`semantic versioning`: https://semver.org/
+.. _`Subscribe to Symfony Roadmap notifications`: https://symfony.com/account
+.. _`Symfony Roadmap`: https://symfony.com/roadmap#checker
+.. _`professional Symfony support`: https://sensiolabs.com/
diff --git a/contributing/community/review-comments.rst b/contributing/community/review-comments.rst
index a317c12fa27..6336f92dcbb 100644
--- a/contributing/community/review-comments.rst
+++ b/contributing/community/review-comments.rst
@@ -38,7 +38,7 @@ Tone of Voice
We don't expect you to be completely formal, or to even write error-free
English. Just remember this: don't swear, and be respectful to others.
-Don't reply in anger or with an aggressive tone. You're angry, we understand
+Don't reply in anger or with an aggressive tone. If you're angry, we understand
that, but swearing/cursing and name calling doesn't really encourage anyone to
help you. Take a deep breath, count to 10 and try to *clearly* explain what problems
you encounter.
@@ -74,12 +74,12 @@ Assume everyone is intelligent and well-meaning.
.. tip::
- Good questions avoid judgement and avoid assumptions about the author's perspective.
+ Good questions avoid judgment and avoid assumptions about the author's perspective.
Maybe you can ask for clarification? Suggest an alternative?
Or provide a simple explanation *why* you disagree with their proposal.
- * ``This looks wrong. Are you sure it's correct?`` (eg. typo/syntax error)
+ * ``This looks wrong. Are you sure it's correct?`` (e.g. typo/syntax error)
* ``What do you think of "RequestFactory" instead of RequestCreator?``
@@ -91,34 +91,34 @@ Don't use hyperbole ("always", "never", "endlessly", "nothing", "worst", "horrib
**Don't:** *"I don't like how you wrote this code"* - there is no clear explanation why you
don't like how it's written.
-**Better:** *"I find it hard to read this code as there many nested if statements, can you make it more
-readable? By encapsulating some of it's details or maybe adding some comments to explain the overall logic."* -
+**Better:** *"I find it hard to read this code as there are many nested if statements, can you make it more
+readable? By encapsulating some of the details or maybe adding some comments to explain the overall logic."* -
You explain why you find the code hard to read *and* give some suggestions for improvement.
If a piece of code is in fact wrong, explain why:
-* ``This code doesn't comply with Symfony's CS rules. Please see [...] for details``.
+* "This code doesn't comply with Symfony's CS rules. Please see [...] for details."
-* ``Symfony 3 still uses PHP 5 and doesn't allow the usage scalar type-hints.``.
+* "Symfony 3 still uses PHP 5 and doesn't allow the usage of scalar type-hints."
-* ``I think the code is less readable now`` - careful here, be sure explain why you think
+* "I think the code is less readable now." - careful here, be sure explain why you think
the code is less readable, and maybe give some suggestions?
**Examples of valid reasons to reject:**
- * We tried that in the past (link to the relevant PR) but we needed to revert it for XXX reason.
+* "We tried that in the past (link to the relevant PR) but we needed to revert it for XXX reason."
- * That change would introduce too many merge conflicts when merging up Symfony branches.
- In the past we've always rejected changes like this.
+* "That change would introduce too many merge conflicts when merging up Symfony branches.
+ In the past we've always rejected changes like this."
- * I profiled this change and it hurts performance significantly (if you don't profile, it's an opinion, so we can ignore)
+* "I profiled this change and it hurts performance significantly" - if you don't profile, it's an opinion, so we can ignore
- * Code doesn't match Symfony's CS rules (e.g. ``use array()`` instead of ``[]``)
+* "Code doesn't match Symfony's CS rules (e.g. use ``[]`` instead of ``array()``)"
- * We only provide integration with very popular projects (e.g. we integrate Bootstrap but not your own CSS framework)
+* "We only provide integration with very popular projects (e.g. we integrate Bootstrap but not your own CSS framework)"
- * This would require adding lots of code and making lots of changes for a feature that doesn't look so important.
- That could hurt maintaining in the future.
+* "This would require adding lots of code and making lots of changes for a feature that doesn't look so important.
+ That could hurt maintaining in the future."
Asking for Changes
------------------
@@ -149,6 +149,17 @@ you don't have to use "Please" all the time. But it wouldn't hurt.
It may not seem like much, but saying "Thank you" does make others feel
more welcome.
+
+Preventing Escalations
+----------------------
+
+Sometimes when people receive feedback they may get defensive.
+In that case, it is better to try to approach the discussion in
+a different way, to not escalate further.
+
+If you want someone to mediate, please join the ``#contribs`` channel on `Symfony Slack`_,
+to have a safe environment and keep working together on the common goals.
+
Using Humor
-----------
@@ -176,3 +187,5 @@ But don't say it "just because", if your apology is not really meant
you *will* lose credibility and respect from other developers.
*Do unto others as you would have them do unto you.*
+
+.. _`Symfony Slack`: https://symfony.com/slack-invite
diff --git a/contributing/community/reviews.rst b/contributing/community/reviews.rst
index 2d4a5f125fa..f412e4ecdd2 100644
--- a/contributing/community/reviews.rst
+++ b/contributing/community/reviews.rst
@@ -6,6 +6,13 @@ ready to contribute code or patches, reviewing issues and pull requests (PRs)
can be a great start to get involved and give back. In fact, people who "triage"
issues are the backbone to Symfony's success!
+.. note::
+
+ Communicating in a way where your words come across as intended can be
+ difficult. Please read through the
+ :doc:`Respectful Review Comments `
+ guidelines.
+
Why Reviewing Is Important
--------------------------
@@ -17,7 +24,7 @@ On the `Symfony issue tracker`_, you can find many items in a `Needs Review`_
status:
* **Bug Reports**: Bug reports need to be checked for completeness.
- Is any important information missing? Can the bug be *easily* reproduced?
+ Is any important information missing? Can the bug be reproduced?
* **Pull Requests**: Pull requests contain code that fixes a bug or implements
new functionality. Reviews of pull requests ensure that they are implemented
@@ -38,7 +45,7 @@ next step.
Create a GitHub Account
-----------------------
-Symfony uses GitHub_ to manage bug reports and pull requests. If you want to
+Symfony uses `GitHub`_ to manage bug reports and pull requests. If you want to
do reviews, you need to `create a GitHub account`_ and log in.
The Bug Report Review Process
@@ -60,7 +67,7 @@ The steps for the review are:
Download the reproduction project and test whether the bug can be reproduced
on your system. If the reporter did not provide a reproduction project,
- create one by forking_ the `Symfony Standard Edition`_.
+ create one by `forking`_ the `Symfony Standard Edition`_.
#. **Update the Issue Status**
@@ -139,7 +146,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
* Does the PR stay within scope to address *only* that issue?
* Does the PR contain automated tests? Do those tests cover all relevant
edge cases?
- * Does the PR contain sufficient comments to easily understand its code?
+ * Does the PR contain sufficient comments to understand its code?
* Does the code break backward compatibility? If yes, does the PR header say
so?
* Does the PR contain deprecations? If yes, does the PR header say so? Does
@@ -209,8 +216,6 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
.. _forking: https://help.github.com/articles/fork-a-repo/
.. _bug reports in need of review: https://github.com/symfony/symfony/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22Bug%22+label%3A%22Status%3A+Needs+Review%22+
.. _PRs in need of review: https://github.com/symfony/symfony/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Apr+label%3A%22Status%3A+Needs+Review%22+
-.. _Contribution Guidelines: https://github.com/symfony/symfony/blob/master/CONTRIBUTING.md
-.. _Symfony's Release Schedule: https://symfony.com/doc/current/contributing/community/releases.html#schedule
.. _Symfony Roadmap: https://symfony.com/roadmap
.. _Carson Bot: https://github.com/carsonbot/carsonbot
.. _`Needs Review`: https://github.com/symfony/symfony/labels/Status%3A%20Needs%20Review
diff --git a/contributing/diversity/governance.rst b/contributing/diversity/governance.rst
new file mode 100644
index 00000000000..8dd302ccc0a
--- /dev/null
+++ b/contributing/diversity/governance.rst
@@ -0,0 +1,143 @@
+Diversity Initiative Governance
+===============================
+
+Membership
+----------
+
+Membership of Symfony's Diversity Initiative is open to any member of the
+Symfony community; to avoid the risk of elitism or meritocracy, no requirement
+is needed to be involved. All members, at any time, are invited to put forward
+ideas and suggestions as a proposal for an actionable item.
+
+Guidance
+--------
+
+The project leader, Fabien Potencier, is responsible for publicly appointing
+five (5) members of the initiative to provide guidance and drive it forward,
+but also retains the right to revoke any of the appointed members at any time.
+This guidance team should:
+
+* Be committed to the initiative's cause and have joined because they want to
+ help the initiative to deliver its purpose most effectively for the
+ community's benefit.
+* Recognize that meeting the initiative's purpose is an ongoing effort.
+* Be committed to good governance and want to contribute to the initiative's
+ continued improvement.
+
+The current guidance team is composed of the following people (in alphabetical
+order):
+
+* **Lukas Kahwe Smith** (`lsmith77`_);
+* **Michelle Sanver** (`michellesanver`_);
+* **Nicolas Grekas** (`nicolas-grekas`_);
+* **Timo Bakx** (`TimoBakx`_);
+* **Zan Baldwin** (`zanbaldwin`_).
+
+Veto
+~~~~
+
+The project leader (Fabien Potencier) will have the right to veto any actionable
+item, regardless of the vote of the initiative's guidance team. The project
+leader may, at their discretion, also appoint other people from among the
+initiative's guidance team to also have the right to veto - in such a case these
+people are expected to use appropriate judgment to know when to use a "no" vote
+or a veto. Any single veto will reject an actionable item.
+
+The purpose of having members with the right to veto is to prevent a "people's
+majority" from overruling the core interests of the Symfony project. This will
+encourage communication between proposing members, the initiative's guidance
+team and the Core Team to create realistic proposals, and in return any veto
+will come with a full explanation (not just a justification).
+
+Advice Process
+~~~~~~~~~~~~~~
+
+When a proposal on an actionable item is ready to be decided on, insight from
+the community (advice, general consensus, or non-binding poll) should be
+requested from the wider community - this will aim to include both those who
+will be meaningfully affected and those with meaningful expertise in the matter
+at hand.
+This feedback will enable the guidance team to have the confidence to vote for
+the best possible decision according to the information they have available,
+knowing that the responsibility they accept for said vote is justified.
+
+Voting
+~~~~~~
+
+The guidance team have the right to vote on proposals for actionable items.
+The quorum of "yes" or "no" votes required for a decision to be considered valid
+is at least 75% of active, appointed members of the guidance team - to abstain
+from voting means that vote will not be counted towards the quorum.
+For an actionable item to pass, approval from greater than 50% of the voting
+guidance team members is required. Use or management of finances/donations
+require at least a two-thirds majority to pass.
+
+For transparency and ease-of-understanding, this means only the following
+combinations of votes will result in an actionable item passing:
+
++-----+---------+---------+
+| For | Against | Abstain |
++=====+=========+=========+
+| 5 | 0 | 0 |
++-----+---------+---------+
+| 4 | 1 | 0 |
++-----+---------+---------+
+| 3 | 2 | 0 |
++-----+---------+---------+
+| 4 | 0 | 1 |
++-----+---------+---------+
+| 3 | 1 | 1 |
++-----+---------+---------+
+
+Guidance Principles
+-------------------
+
+Purpose
+~~~~~~~
+
+The initiative should be led by an effective guidance team that provides
+strategic guidance in line with the initiative's aims and values, including a
+shared understanding with fellow initiative members to ensure that these are
+being delivered effectively and sustainably.
+
+Integrity
+~~~~~~~~~
+
+The guidance team should act with integrity: adopting values which help achieve
+the initiative's purposes, even where difficult or unpopular decisions are
+required. Guidance team members should undertake their duties, aware of the
+importance of confidence and trust in the initiative from the wider community,
+and ultimately acknowledges shared responsibility for the reputation of the
+Symfony project like the Core Team.
+
+Decision-making Effectiveness
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Guidance members should work as an effective team, using the appropriate balance
+of skills, experience, backgrounds and knowledge to make sure its
+decision-making processes are informed and equitable. Risk assessment and
+management systems should be set up and monitored.
+
+Openness and Accountability
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The behavior and conduct of the initiative's guidance team sets the tone for
+the rest of the community. The guidance team should lead by example to create a
+culture that enables members to feel it is safe to suggest, question and
+challenge - rather than avoid - difficult ideas and topics. The team should
+guide the initiative in being transparent, accountable and open.
+
+Adaptability
+~~~~~~~~~~~~
+
+The initiative should establish processes that do not require any one person to
+hold specific positions while being adaptable to accommodate unforeseen needs of
+the community, especially as membership and involvement grows over time (changes
+to guidance team member appointment will have to be approved by the current
+system, which is Fabien Potencier).
+
+.. _`lsmith77`: https://github.com/lsmith77/
+.. _`michellesanver`: https://github.com/michellesanver/
+.. _`nicolas-grekas`: https://github.com/nicolas-grekas/
+.. _`TimoBakx`: https://github.com/TimoBakx/
+.. _`zanbaldwin`: https://github.com/zanbaldwin/
diff --git a/contributing/diversity/index.rst b/contributing/diversity/index.rst
new file mode 100644
index 00000000000..a932c27648b
--- /dev/null
+++ b/contributing/diversity/index.rst
@@ -0,0 +1,7 @@
+Diversity Initiative
+====================
+
+.. toctree::
+ :maxdepth: 2
+
+ governance
diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst
index 56fcbba574d..875ae836c96 100644
--- a/contributing/documentation/format.rst
+++ b/contributing/documentation/format.rst
@@ -8,7 +8,7 @@ such as HTML and PDF.
reStructuredText
----------------
-reStructuredText is a plaintext markup syntax similar to Markdown, but much
+reStructuredText is a plain text markup syntax similar to Markdown, but much
stricter with its syntax. If you are new to reStructuredText, take some time to
familiarize with this format by reading the existing `Symfony documentation`_
source code.
@@ -29,7 +29,7 @@ Sphinx
Sphinx_ is a build system that provides tools to create documentation from
reStructuredText documents. As such, it adds new directives and interpreted text
-roles to the standard reST markup. Read more about the `Sphinx Markup Constructs`_.
+roles to the standard reStructuredText markup. Read more about the `Sphinx Markup Constructs`_.
Syntax Highlighting
~~~~~~~~~~~~~~~~~~~
@@ -74,7 +74,7 @@ directive to show the configuration in all supported configuration formats
// Configuration in PHP
-The previous reST snippet renders as follow:
+The previous reStructuredText snippet renders as follow:
.. configuration-block::
@@ -148,12 +148,10 @@ If you want to modify that title, use this alternative syntax:
:doc:`environments`
**Links to the API** follow a different syntax, where you must specify the type
-of the linked resource (``namespace``, ``class`` or ``method``):
+of the linked resource (``class`` or ``method``):
.. code-block:: rst
- :namespace:`Symfony\\Component\\BrowserKit`
-
:class:`Symfony\\Component\\Routing\\Matcher\\ApacheUrlMatcher`
:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`
@@ -168,40 +166,52 @@ of the linked resource (``namespace``, ``class`` or ``method``):
:phpfunction:`iterator_to_array`
-New Features or Behavior Changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+New Features, Behavior Changes or Deprecations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are documenting a brand new feature, a change or a deprecation that's
+been made in Symfony, you should precede your description of the change with
+the corresponding directive and a short description:
+
+For a new feature or a behavior change use the ``.. versionadded:: 3.x``
+directive:
+
+.. code-block:: rst
+
+ .. versionadded:: 3.4
-If you're documenting a brand new feature or a change that's been made in
-Symfony, you should precede your description of the change with a
-``.. versionadded:: 2.X`` directive and a short description:
+ The special ``!`` template prefix was introduced in Symfony 3.4.
+
+If you are documenting a behavior change, it may be helpful to *briefly*
+describe how the behavior has changed:
.. code-block:: rst
- .. versionadded:: 2.7
- The ``askHiddenResponse()`` method was introduced in Symfony 2.7.
+ .. versionadded:: 3.4
- You can also ask a question and hide the response. This is particularly [...]
+ Support for annotation routing without an external bundle was introduced
+ in Symfony 3.4. Prior, you needed to install the SensioFrameworkExtraBundle.
-If you're documenting a behavior change, it may be helpful to *briefly* describe
-how the behavior has changed:
+For a deprecation use the ``.. deprecated:: 3.x`` directive:
.. code-block:: rst
- .. versionadded:: 2.7
- The ``include()`` function is a new Twig feature that's available in
- Symfony 2.7. Prior, the ``{% include %}`` tag was used.
+ .. deprecated:: 3.3
+
+ This technique is discouraged and the ``addClassesToCompile()`` method was
+ deprecated in Symfony 3.3 because modern PHP versions make it unnecessary.
-Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc),
+Whenever a new major version of Symfony is released (e.g. 3.0, 4.0, etc),
a new branch of the documentation is created from the ``master`` branch.
-At this point, all the ``versionadded`` tags for Symfony versions that have
-reached end-of-maintenance will be removed. For example, if Symfony 2.5 were
-released today, and 2.2 had recently reached its end-of-maintenance, the 2.2
-``versionadded`` tags would be removed from the new ``2.5`` branch.
+At this point, all the ``versionadded`` and ``deprecated`` tags for Symfony
+versions that have a lower major version will be removed. For example, if
+Symfony 4.0 were released today, 3.0 to 3.4 ``versionadded`` and ``deprecated``
+tags would be removed from the new ``4.0`` branch.
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _Sphinx: http://sphinx-doc.org/
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html
+.. _Sphinx: https://www.sphinx-doc.org/
.. _`Symfony documentation`: https://github.com/symfony/symfony-docs
-.. _`reStructuredText Primer`: http://sphinx-doc.org/rest.html
-.. _`reStructuredText Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
-.. _`Sphinx Markup Constructs`: http://sphinx-doc.org/markup/
+.. _`reStructuredText Primer`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _`reStructuredText Reference`: https://docutils.sourceforge.io/docs/user/rst/quickref.html
+.. _`Sphinx Markup Constructs`: https://www.sphinx-doc.org/en/1.7/markup/index.html
.. _`supported languages`: http://pygments.org/languages/
diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst
index d4ccfe74310..f16f4e32cc7 100644
--- a/contributing/documentation/index.rst
+++ b/contributing/documentation/index.rst
@@ -5,21 +5,21 @@ These short articles explain everything you need to contribute to the Symfony
documentation:
:doc:`The Contribution Process `
- Explains the steps to follow to contribute fixes and new contents. It's the
- same contribution process followed by most open source projects, so you may
- already know everything that is needed.
+ Explains the steps to follow to contribute fixes and new contents. It's the
+ same contribution process followed by most open source projects, so you may
+ already know everything that is needed.
:doc:`Documentation Formats `
- Explains the technical details of the reStructuredText format that is used to
- write the docs. Skip it if you are already familiar with this format.
+ Explains the technical details of the reStructuredText format that is used to
+ write the docs. Skip it if you are already familiar with this format.
:doc:`Documentation Standards `
- Explains how to write docs and code examples to match the style and tone of
- the rest of the existing documentation.
+ Explains how to write docs and code examples to match the style and tone of
+ the rest of the existing documentation.
:doc:`License `
- Explains the details of the Creative Commons BY-SA 3.0 license used for the
- Symfony Documentation.
+ Explains the details of the Creative Commons BY-SA 3.0 license used for the
+ Symfony Documentation.
.. toctree::
:hidden:
diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst
index 5fdca2428c7..e7cbfea9bf3 100644
--- a/contributing/documentation/overview.rst
+++ b/contributing/documentation/overview.rst
@@ -65,9 +65,9 @@ Let's imagine that you want to improve the Setup guide. In order to make your
changes, follow these steps:
**Step 1.** Go to the official Symfony documentation repository located at
-`github.com/symfony/symfony-docs`_ and click on the **Fork** button to `fork the
-repository`_ to your personal account. This is only needed the first time you
-contribute to Symfony.
+`github.com/symfony/symfony-docs`_ and click on the **Fork** button to
+`fork the repository`_ to your personal account. This is only needed the first
+time you contribute to Symfony.
**Step 2.** **Clone** the forked repository to your local machine (this example
uses the ``projects/symfony-docs/`` directory to store the documentation; change
@@ -112,16 +112,16 @@ memorable name for the new branch (if you are fixing a reported issue, use
.. code-block:: terminal
- $ git checkout -b improve_install_article upstream/2.8
+ $ git checkout -b improve_install_article upstream/3.4
In this example, the name of the branch is ``improve_install_article`` and the
-``upstream/2.8`` value tells Git to create this branch based on the ``2.8``
+``upstream/3.4`` value tells Git to create this branch based on the ``3.4``
branch of the ``upstream`` remote, which is the original Symfony Docs repository.
Fixes should always be based on the **oldest maintained branch** which contains
-the error. Nowadays this is the ``2.8`` branch. If you are instead documenting a
+the error. Nowadays this is the ``3.4`` branch. If you are instead documenting a
new feature, switch to the first Symfony version that included it, e.g.
-``upstream/3.1``. Not sure? That's ok! Just use the ``upstream/master`` branch.
+``upstream/3.1``. Not sure? That's OK! Just use the ``upstream/master`` branch.
**Step 5.** Now make your changes in the documentation. Add, tweak, reword and
even remove any content and do your best to comply with the
@@ -155,7 +155,7 @@ changes should be applied:
:align: center
In this example, the **base fork** should be ``symfony/symfony-docs`` and
-the **base** branch should be the ``2.8``, which is the branch that you selected
+the **base** branch should be the ``3.4``, which is the branch that you selected
to base your changes on. The **head fork** should be your forked copy
of ``symfony-docs`` and the **compare** branch should be ``improve_install_article``,
which is the name of the branch you created and where you made your changes.
@@ -205,7 +205,7 @@ contribution to the Symfony docs:
# create a new branch based on the oldest maintained version
$ cd projects/symfony-docs/
$ git fetch upstream
- $ git checkout -b my_changes upstream/2.8
+ $ git checkout -b my_changes upstream/3.4
# ... do your changes
@@ -229,28 +229,42 @@ this hard work, it's **time to celebrate again!**
Review your changes
-------------------
-Every GitHub Pull Request is automatically built and deployed by `Platform.sh`_
-on a single environment that you can access on your browser to review your
-changes.
+Every GitHub Pull Request is automatically built and deployed by
+`SymfonyCloud`_ on a single environment that you can access on your browser to
+review your changes.
-.. image:: /_images/contributing/docs-pull-request-platformsh.png
+.. image:: /_images/contributing/docs-pull-request-symfonycloud.png
:align: center
- :alt: Platform.sh Pull Request Deployment
+ :alt: SymfonyCloud Pull Request Deployment
-To access the `Platform.sh`_ environment URL, go to your Pull Request page on
-GitHub, click on the **Show all checks** link and finally, click on the ``Details``
-link displayed for Platform.sh service.
+To access the `SymfonyCloud`_ environment URL, go to your Pull Request page on
+GitHub, click on the **Show all checks** link and finally, click on the
+``Details`` link displayed for SymfonyCloud service.
.. note::
Only Pull Requests to maintained branches are automatically built by
- Platform.sh. Check the `roadmap`_ for maintained branches.
+ SymfonyCloud. Check the `roadmap`_ for maintained branches.
Build the Documentation Locally
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Alternatively you can build the documentation on your own computer for testing
-purposes following these steps:
+If you have Docker installed on your machine, run these commands to build the
+docs:
+
+.. code-block:: terminal
+
+ # build the image...
+ $ docker build . -t symfony-docs
+
+ # ...and start the local web server
+ # (if it's already in use, change the '8080' port by any other port)
+ $ docker run --rm -p 8080:80 symfony-docs
+
+You can now read the docs at ``http://127.0.0.1:8080`` (if you use a virtual
+machine, browse its IP instead of localhost; e.g. ``http://192.168.99.100:8080``).
+
+If you don't use Docker, follow these steps to build the docs locally:
#. Install `pip`_ as explained in the `pip installation`_ article;
@@ -278,7 +292,7 @@ Why Do my Changes Take so Long to Be Reviewed and/or Merged?
Please be patient. It can take up to several days before your pull request can
be fully reviewed. After merging the changes, it could take again several hours
-before your changes appear on the symfony.com website.
+before your changes appear on the Symfony website.
Why Should I Use the Oldest Maintained Branch Instead of the Master Branch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -288,8 +302,8 @@ into multiple branches, corresponding to the different versions of Symfony itsel
The ``master`` branch holds the documentation for the development branch of
the code.
-Unless you're documenting a feature that was introduced after Symfony 2.8,
-your changes should always be based on the ``2.8`` branch. Documentation managers
+Unless you're documenting a feature that was introduced after Symfony 3.4,
+your changes should always be based on the ``3.4`` branch. Documentation managers
will use the necessary Git-magic to also apply your changes to all the active
branches of the documentation.
@@ -319,16 +333,15 @@ your proposal after you put all that hard work into making the changes. We
definitely don't want you to waste your time!
.. _`github.com/symfony/symfony-docs`: https://github.com/symfony/symfony-docs
-.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
+.. _`reStructuredText`: https://docutils.sourceforge.io/rst.html
.. _`GitHub`: https://github.com/
.. _`fork the repository`: https://help.github.com/articles/fork-a-repo
.. _`Symfony Documentation Contributors`: https://symfony.com/contributors/doc
.. _`SymfonyConnect`: https://connect.symfony.com/
.. _`Symfony Documentation Badge`: https://connect.symfony.com/badge/36/symfony-documentation-contributor
-.. _`sync your fork`: https://help.github.com/articles/syncing-a-fork
-.. _`Platform.sh`: https://platform.sh
+.. _`SymfonyCloud`: https://symfony.com/cloud
.. _`roadmap`: https://symfony.com/roadmap
.. _`pip`: https://pip.pypa.io/en/stable/
.. _`pip installation`: https://pip.pypa.io/en/stable/installing/
-.. _`Sphinx`: http://sphinx-doc.org/
+.. _`Sphinx`: https://www.sphinx-doc.org/
.. _`Sphinx Extensions for PHP and Symfony`: https://github.com/fabpot/sphinx-php
diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst
index 05083334eb9..08787eb0331 100644
--- a/contributing/documentation/standards.rst
+++ b/contributing/documentation/standards.rst
@@ -63,8 +63,8 @@ Code Examples
* To avoid horizontal scrolling on code blocks, we prefer to break a line
correctly if it crosses the 85th character;
* When you fold one or more lines of code, place ``...`` in a comment at the point
- of the fold. These comments are: ``// ...`` (php), ``# ...`` (yaml/bash), ``{# ... #}``
- (twig), ```` (xml/html), ``; ...`` (ini), ``...`` (text);
+ of the fold. These comments are: ``// ...`` (PHP), ``# ...`` (Yaml/bash), ``{# ... #}``
+ (Twig), ```` (XML/HTML), ``; ...`` (INI), ``...`` (text);
* When you fold a part of a line, e.g. a variable value, put ``...`` (without comment)
at the place of the fold;
* Description of the folded code: (optional)
@@ -137,7 +137,7 @@ Files and Directories
* When referencing file extensions explicitly, you should include a leading dot
for every extension (e.g. "XML files use the ``.xml`` extension").
* When you list a Symfony file/directory hierarchy, use ``your-project/`` as the
- top level directory. E.g.
+ top-level directory. E.g.
.. code-block:: text
@@ -175,6 +175,23 @@ In addition, documentation follows these rules:
* his or hers, use theirs
* himself or herself, use themselves
+* **Avoid belittling words**: Things that seem "obvious" or "simple" for the
+ person documenting it, can be the exact opposite for the reader. To make sure
+ everybody feels comfortable when reading the documentation, try to avoid words
+ like:
+
+ * basically
+ * clearly
+ * easy/easily
+ * just
+ * logically
+ * merely
+ * obviously
+ * of course
+ * quick/quickly
+ * simply
+ * trivial
+
.. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
.. _`Twig Coding Standards`: https://twig.symfony.com/doc/2.x/coding_standards.html
.. _`reserved by the IANA`: http://tools.ietf.org/html/rfc2606#section-3
diff --git a/contributing/index.rst b/contributing/index.rst
index ee61fb73bd2..923a4e48ed4 100644
--- a/contributing/index.rst
+++ b/contributing/index.rst
@@ -8,6 +8,6 @@ Contributing
code/index
documentation/index
community/index
- code_of_conduct/index
+ diversity/index
.. include:: /contributing/map.rst.inc
diff --git a/contributing/map.rst.inc b/contributing/map.rst.inc
index 15775643c62..b495a0d76d0 100644
--- a/contributing/map.rst.inc
+++ b/contributing/map.rst.inc
@@ -8,16 +8,16 @@
* **Code**
* :doc:`Bugs `
- * :doc:`Patches `
- * :doc:`Reviewing Issues and Patches `
+ * :doc:`Pull Requests `
+ * :doc:`Reviewing Issues and Pull Requests `
* :doc:`Maintenance `
* :doc:`The Core Team `
* :doc:`Security `
* :doc:`Tests `
* :doc:`Backward Compatibility `
- * :doc:`Coding Standards`
- * :doc:`Code Conventions`
- * :doc:`Git`
+ * :doc:`Coding Standards `
+ * :doc:`Code Conventions `
+ * :doc:`Git `
* :doc:`License `
* **Documentation**
@@ -32,4 +32,7 @@
* :doc:`Release Process `
* :doc:`Respectful Review comments `
* :doc:`Community Reviews `
- * :doc:`Other Resources `
+
+* **Diversity**
+
+ * :doc:`Governance `
diff --git a/controller.rst b/controller.rst
index 77883db9d93..5c2ae3421d9 100644
--- a/controller.rst
+++ b/controller.rst
@@ -16,8 +16,8 @@ This renders a page that prints a lucky (random) number::
// src/AppBundle/Controller/LuckyController.php
namespace AppBundle\Controller;
- use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Routing\Annotation\Route;
class LuckyController
{
@@ -59,7 +59,7 @@ class::
namespace AppBundle\Controller;
use Symfony\Component\HttpFoundation\Response;
- use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+ use Symfony\Component\Routing\Annotation\Route;
class LuckyController
{
@@ -116,18 +116,15 @@ For more information on routing, see :doc:`/routing`.
.. index::
single: Controller; Base controller class
-The Base Controller Class & Services
-------------------------------------
+.. _the-base-controller-class-services:
-For convenience, Symfony comes with an optional base
-:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class.
-If you extend it, this won't change anything about how your controller
-works, but you'll get access to a number of **helper methods** and the
-**service container** (see :ref:`controller-accessing-services`): an
-array-like object that gives you access to every useful object in the
-system. These useful objects are called **services**, and Symfony ships
-with a service object that can render Twig templates, another that can
-log messages and many more.
+The Base Controller Classes & Services
+--------------------------------------
+
+For convenience, Symfony comes with two optional base
+:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` and
+:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`
+classes. You can extend either to get access to a number of helper methods.
Add the ``use`` statement atop the ``Controller`` class and then modify
``LuckyController`` to extend it::
@@ -142,11 +139,25 @@ Add the ``use`` statement atop the ``Controller`` class and then modify
// ...
}
-Helper methods are just shortcuts to using core Symfony functionality
-that's available to you with or without the use of the base
-``Controller`` class. A great way to see the core functionality in
-action is to look in the
-:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class.
+That's it! You now have access to methods like :ref:`$this->render() `
+and many others that you'll learn about next.
+
+.. _controller-abstract-versus-controller:
+
+.. tip::
+
+ You can extend either ``Controller`` or ``AbstractController``. The difference
+ is that when you extend ``AbstractController``, you can't access your services
+ via ``$this->get()`` or ``$this->container->get()``, only to a set of common
+ Symfony services. This forces you to write more robust code to access services.
+
+ Moreover, in Symfony 4.2 ``Controller`` was deprecated in favor of
+ ``AbstractController``, so using the latter will make your applications
+ future-proof.
+
+.. versionadded:: 3.3
+
+ The ``AbstractController`` class was introduced in Symfony 3.3.
.. index::
single: Controller; Redirecting
@@ -157,7 +168,7 @@ Generating URLs
The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::generateUrl`
method is just a helper method that generates the URL for a given route::
- $url = $this->generateUrl('blog_show', array('slug' => 'slug-value'));
+ $url = $this->generateUrl('blog_show', ['slug' => 'slug-value']);
Redirecting
~~~~~~~~~~~
@@ -171,22 +182,18 @@ and ``redirect()`` methods::
return $this->redirectToRoute('homepage');
// does a permanent - 301 redirect
- return $this->redirectToRoute('homepage', array(), 301);
+ return $this->redirectToRoute('homepage', [], 301);
// redirects to a route with parameters
- return $this->redirectToRoute('blog_show', array('slug' => 'my-page'));
+ return $this->redirectToRoute('blog_show', ['slug' => 'my-page']);
- // redirects to a route and mantains the original query string parameters
+ // redirects to a route and maintains the original query string parameters
return $this->redirectToRoute('blog_show', $request->query->all());
// redirects externally
return $this->redirect('http://symfony.com/doc');
}
-.. versionadded:: 2.6
- The ``redirectToRoute()`` method was introduced in Symfony 2.6. Previously (and still now), you
- could use ``redirect()`` and ``generateUrl()`` together for this.
-
For more information, see the :doc:`Routing article `.
.. caution::
@@ -221,15 +228,15 @@ method renders a template **and** puts that content into a ``Response``
object for you::
// renders app/Resources/views/lucky/number.html.twig
- return $this->render('lucky/number.html.twig', array('number' => $number));
+ return $this->render('lucky/number.html.twig', ['number' => $number]);
Templates can also live in deeper sub-directories. Just try to avoid
creating unnecessarily deep structures::
// renders app/Resources/views/lottery/lucky/number.html.twig
- return $this->render('lottery/lucky/number.html.twig', array(
+ return $this->render('lottery/lucky/number.html.twig', [
'number' => $number,
- ));
+ ]);
The Symfony templating system and Twig are explained more in the
:doc:`Creating and Using Templates article `.
@@ -239,46 +246,150 @@ The Symfony templating system and Twig are explained more in the
.. _controller-accessing-services:
-Accessing Other Services
-~~~~~~~~~~~~~~~~~~~~~~~~
+Fetching Services as Controller Arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Symfony comes packed with a lot of useful objects, called *services*. These
-are used for rendering templates, sending emails, querying the database and
-any other "work" you can think of. When you install a new bundle, it probably
-brings in even *more* services.
+.. versionadded:: 3.3
-When extending the base controller class, you can access any Symfony service
-via the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::get`
-method of the ``Controller`` class. Here are several common services you might
-need::
+ The ability to type-hint a controller argument in order to receive a service
+ was introduced in Symfony 3.3.
- $templating = $this->get('templating');
+Symfony comes *packed* with a lot of useful classes and functionalities, called :doc:`services `.
+These are used for rendering templates, sending emails, querying the database and
+any other "work" you can think of.
- $router = $this->get('router');
+If you need a service in a controller, just type-hint an argument with its class
+(or interface) name. Symfony will automatically pass you the service you need::
- $mailer = $this->get('mailer');
+ use Psr\Log\LoggerInterface;
+ // ...
+
+ /**
+ * @Route("/lucky/number/{max}")
+ */
+ public function numberAction($max, LoggerInterface $logger)
+ {
+ $logger->info('We are logging!');
+ // ...
+ }
+
+Awesome!
-What other services exist? To list all services, use the ``debug:container``
-console command:
+What other services can you type-hint? To see them, use the ``debug:autowiring`` console
+command:
.. code-block:: terminal
- $ php app/console debug:container
+ $ php bin/console debug:autowiring
-For more information, see the :doc:`/service_container` article.
+If you need control over the *exact* value of an argument, you can :ref:`bind `
+the argument by its name:
-.. tip::
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/services.yml
+ services:
+ # ...
+
+ # explicitly configure the service
+ AppBundle\Controller\LuckyController:
+ tags: [controller.service_arguments]
+ bind:
+ # for any $logger argument, pass this specific service
+ $logger: '@monolog.logger.doctrine'
+
+ .. code-block:: xml
+
+
+
+
- To get a :ref:`container configuration parameter `,
- use the
- :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getParameter`
- method::
+
+
- $from = $this->getParameter('app.mailer.from');
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/services.php
+ use AppBundle\Controller\LuckyController;
+ use Symfony\Component\DependencyInjection\Reference;
+
+ $container->register(LuckyController::class)
+ ->addTag('controller.service_arguments')
+ ->setBindings([
+ '$logger' => new Reference('monolog.logger.doctrine'),
+ ])
+ ;
+
+You can also use normal :ref:`constructor injection `
+in your controllers.
+
+.. caution::
+
+ You can *only* pass *services* to your controller arguments in this way. It's not
+ possible, for example, to pass a config parameter as a controller argument,
+ even by using ``bind``. If you need a parameter, use the ``$this->getParameter('kernel.debug')``
+ shortcut or pass the value through your controller's ``__construct()`` method
+ and specify its value with ``bind``.
+
+For more information about services, see the :doc:`/service_container` article.
+
+.. _controller-service-arguments-tag:
+
+.. note::
+
+ If this isn't working, make sure your controller is registered as a service,
+ is :ref:`autoconfigured ` and extends either
+ :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` or
+ :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`. If
+ you use the :ref:`services.yml configuration from the Symfony Standard Edition `,
+ then your controllers are already registered as services and autoconfigured.
+
+ If you're not using the default configuration, you can tag your service manually
+ with ``controller.service_arguments``.
+
+.. _accessing-other-services:
+.. _controller-access-services-directly:
+
+Accessing the Container Directly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you extend the base ``Controller`` class, you can access any Symfony service
+via the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::get`
+method. Here are several common services you might need::
+
+ $templating = $this->get('templating');
+
+ $router = $this->get('router');
+
+ $mailer = $this->get('mailer');
- .. versionadded:: 2.7
- The ``Controller::getParameter()`` method was introduced in Symfony
- 2.7. Use ``$this->container->getParameter()`` in versions prior to 2.7.
+ // you can also fetch parameters
+ $someParameter = $this->getParameter('some_parameter');
+
+If you receive an error like:
+
+.. code-block:: text
+
+ You have requested a non-existent service "my_service_id"
+
+Check to make sure the service exists (use :ref:`debug:container `)
+and that it's :ref:`public `.
.. index::
single: Controller; Managing errors
@@ -289,7 +400,8 @@ Managing Errors and 404 Pages
When things are not found, you should play well with the HTTP protocol and
return a 404 response. To do this, you'll throw a special type of exception.
-If you're extending the base ``Controller`` class, do the following::
+If you're extending the base ``Controller`` or the base ``AbstractController``
+class, do the following::
public function indexAction()
{
@@ -355,18 +467,18 @@ Symfony provides a nice session object that you can use to store information
about the user between requests. By default, Symfony stores the token in a
cookie and writes the attributes to a file by using native PHP sessions.
-To retrieve the session, call
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getSession`
-method on the ``Request`` object. This method returns a
-:class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface` with easy
-methods for storing and fetching things from the session::
+.. versionadded:: 3.3
- use Symfony\Component\HttpFoundation\Request;
+ The ability to request a ``Session`` instance in controllers was introduced
+ in Symfony 3.3.
- public function indexAction(Request $request)
- {
- $session = $request->getSession();
+To retrieve the session, add the :class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface`
+type-hint to your argument and Symfony will provide you with a session::
+
+ use Symfony\Component\HttpFoundation\Session\SessionInterface;
+ public function indexAction(SessionInterface $session)
+ {
// stores an attribute for reuse during a later user request
$session->set('foo', 'bar');
@@ -374,11 +486,16 @@ methods for storing and fetching things from the session::
$foobar = $session->get('foobar');
// uses a default value if the attribute doesn't exist
- $filters = $session->get('filters', array());
+ $filters = $session->get('filters', []);
}
Stored attributes remain in the session for the remainder of that user's session.
+.. tip::
+
+ Every ``SessionInterface`` implementation is supported. If you have your
+ own implementation, type-hint this in the arguments instead.
+
.. index::
single: Session; Flash messages
@@ -418,28 +535,42 @@ and then redirects. The message key (``notice`` in this example) can be anything
you'll use this key to retrieve the message.
In the template of the next page (or even better, in your base layout template),
-read any flash messages from the session:
+read any flash messages from the session using ``app.flashes()``:
.. code-block:: html+twig
{# app/Resources/views/base.html.twig #}
- {# you can read and display just one flash message type... #}
- {% for flash_message in app.session.flashBag.get('notice') %}
+ {# read and display just one flash message type #}
+ {% for message in app.flashes('notice') %}
- {{ flash_message }}
+ {{ message }}
{% endfor %}
- {# ...or you can read and display every flash message available #}
- {% for type, flash_messages in app.session.flashBag.all %}
- {% for flash_message in flash_messages %}
-
- {{ flash_message }}
+ {# read and display several types of flash messages #}
+ {% for label, messages in app.flashes(['success', 'warning']) %}
+ {% for message in messages %}
+ `.
+JSON Helper
+~~~~~~~~~~~
+
+To return JSON from a controller, use the ``json()`` helper method on the base controller.
+This returns a special ``JsonResponse`` object that encodes the data automatically::
+
+ // ...
+ public function indexAction()
+ {
+ // returns '{"username":"jane.doe"}' and sets the proper Content-Type header
+ return $this->json(['username' => 'jane.doe']);
+
+ // the shortcut defines three optional arguments
+ // return $this->json($data, $status = 200, $headers = [], $context = []);
+ }
+
+If the :doc:`serializer service ` is enabled in your
+application, contents passed to ``json()`` are encoded with it. Otherwise,
+the :phpfunction:`json_encode` function is used.
+
+File helper
+~~~~~~~~~~~
+
+.. versionadded:: 3.2
+
+ The ``file()`` helper was introduced in Symfony 3.2.
+
+You can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::file`
+helper to serve a file from inside a controller::
+
+ public function fileAction()
+ {
+ // send the file contents and force the browser to download it
+ return $this->file('/path/to/some_file.pdf');
+ }
+
+The ``file()`` helper provides some arguments to configure its behavior::
+
+ use Symfony\Component\HttpFoundation\File\File;
+ use Symfony\Component\HttpFoundation\ResponseHeaderBag;
+
+ public function fileAction()
+ {
+ // load the file from the filesystem
+ $file = new File('/path/to/some_file.pdf');
+
+ return $this->file($file);
+
+ // rename the downloaded file
+ return $this->file($file, 'custom_name.pdf');
+
+ // display the file contents in the browser instead of downloading it
+ return $this->file('invoice_3241.pdf', 'my_invoice.pdf', ResponseHeaderBag::DISPOSITION_INLINE);
+ }
+
Final Thoughts
--------------
@@ -541,12 +723,7 @@ and it's a PHP function where you can do anything in order to return the
final ``Response`` object that will be returned to the user.
To make life easier, you'll probably extend the base ``Controller`` class because
-this gives two things:
-
-A) Shortcut methods (like ``render()`` and ``redirectToRoute()``);
-
-B) Access to *all* of the useful objects (services) in the system via the
- :ref:`get() ` method.
+this gives access to shortcut methods (like ``render()`` and ``redirectToRoute()``).
In other articles, you'll learn how to use specific services from inside your controller
that will help you persist and fetch objects from a database, process form submissions,
diff --git a/controller/argument_value_resolver.rst b/controller/argument_value_resolver.rst
new file mode 100644
index 00000000000..70f0ea58610
--- /dev/null
+++ b/controller/argument_value_resolver.rst
@@ -0,0 +1,250 @@
+.. index::
+ single: Controller; Argument Value Resolvers
+
+Extending Action Argument Resolving
+===================================
+
+In the :doc:`controller guide `, you've learned that you can get the
+:class:`Symfony\\Component\\HttpFoundation\\Request` object via an argument in
+your controller. This argument has to be type-hinted by the ``Request`` class
+in order to be recognized. This is done via the
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver`. By
+creating and registering custom argument value resolvers, you can extend this
+functionality.
+
+.. _functionality-shipped-with-the-httpkernel:
+
+Built-In Value Resolvers
+------------------------
+
+Symfony ships with the following value resolvers in the
+:doc:`HttpKernel component `:
+
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\RequestAttributeValueResolver`
+ Attempts to find a request attribute that matches the name of the argument.
+
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\RequestValueResolver`
+ Injects the current ``Request`` if type-hinted with ``Request`` or a class
+ extending ``Request``.
+
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\ServiceValueResolver`
+ Injects a service if type-hinted with a valid service class or interface. This
+ works like :doc:`autowiring `.
+
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\SessionValueResolver`
+ Injects the configured session class extending ``SessionInterface`` if
+ type-hinted with ``SessionInterface`` or a class extending
+ ``SessionInterface``.
+
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\DefaultValueResolver`
+ Will set the default value of the argument if present and the argument
+ is optional.
+
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\VariadicValueResolver`
+ Verifies if the request data is an array and will add all of them to the
+ argument list. When the action is called, the last (variadic) argument will
+ contain all the values of this array.
+
+In addition, some official bundles provide other value resolvers:
+
+:class:`Symfony\\Bundle\\SecurityBundle\\SecurityUserValueResolver`
+ Injects the object that represents the current logged in user if type-hinted
+ with ``UserInterface``. Default value can be set to ``null`` in case
+ the controller can be accessed by anonymous users. It requires installing
+ the `SecurityBundle`_.
+
+``Psr7ServerRequestResolver``
+ Injects a `PSR-7`_ compliant version of the current request if type-hinted
+ with ``RequestInterface``, ``MessageInterface`` or ``ServerRequestInterface``.
+ It requires installing the `SensioFrameworkExtraBundle`_.
+
+Adding a Custom Value Resolver
+------------------------------
+
+In the next example, you'll create a value resolver to inject the object that
+represents the current user whenever a controller method type-hints an argument
+with the ``User`` class::
+
+ namespace AppBundle\Controller;
+
+ use AppBundle\Entity\User;
+ use Symfony\Component\HttpFoundation\Response;
+
+ class UserController
+ {
+ public function indexAction(User $user)
+ {
+ return new Response('Hello '.$user->getUsername().'!');
+ }
+ }
+
+Beware that this feature is already provided by the `@ParamConverter`_
+annotation from the SensioFrameworkExtraBundle. If you have that bundle
+installed in your project, add this config to disable the auto-conversion of
+type-hinted method arguments:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ sensio_framework_extra:
+ request:
+ converters: true
+ auto_convert: false
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/config.php
+ $container->loadFromExtension('sensio_framework_extra', [
+ 'request' => [
+ 'converters' => true,
+ 'auto_convert' => false,
+ ],
+ ]);
+
+Adding a new value resolver requires creating a class that implements
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentValueResolverInterface`
+and defining a service for it. The interface defines two methods:
+
+``supports()``
+ This method is used to check whether the value resolver supports the
+ given argument. ``resolve()`` will only be executed when this returns ``true``.
+``resolve()``
+ This method will resolve the actual value for the argument. Once the value
+ is resolved, you must `yield`_ the value to the ``ArgumentResolver``.
+
+Both methods get the ``Request`` object, which is the current request, and an
+:class:`Symfony\\Component\\HttpKernel\\ControllerMetadata\\ArgumentMetadata`
+instance. This object contains all information retrieved from the method signature
+for the current argument.
+
+Now that you know what to do, you can implement this interface. To get the
+current ``User``, you need the current security token. This token can be
+retrieved from the token storage::
+
+ // src/AppBundle/ArgumentResolver/UserValueResolver.php
+ namespace AppBundle\ArgumentResolver;
+
+ use AppBundle\Entity\User;
+ use Symfony\Component\HttpFoundation\Request;
+ use Symfony\Component\HttpKernel\Controller\ArgumentValueResolverInterface;
+ use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
+ use Symfony\Component\Security\Core\Security;
+
+ class UserValueResolver implements ArgumentValueResolverInterface
+ {
+ private $security;
+
+ public function __construct(Security $security)
+ {
+ $this->security = $security;
+ }
+
+ public function supports(Request $request, ArgumentMetadata $argument)
+ {
+ if (User::class !== $argument->getType()) {
+ return false;
+ }
+
+ return $this->security->getUser() instanceof User;
+ }
+
+ public function resolve(Request $request, ArgumentMetadata $argument)
+ {
+ yield $this->security->getUser();
+ }
+ }
+
+In order to get the actual ``User`` object in your argument, the given value
+must fulfill the following requirements:
+
+* An argument must be type-hinted as ``User`` in your action method signature;
+* The value must be an instance of the ``User`` class.
+
+When all those requirements are met and ``true`` is returned, the
+``ArgumentResolver`` calls ``resolve()`` with the same values as it called
+``supports()``.
+
+That's it! Now all you have to do is add the configuration for the service
+container. This can be done by tagging the service with ``controller.argument_value_resolver``
+and adding a priority.
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/services.yml
+ services:
+ AppBundle\ArgumentResolver\UserValueResolver:
+ autowire: true
+ tags:
+ - { name: controller.argument_value_resolver, priority: 50 }
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/services.php
+ use AppBundle\ArgumentResolver\UserValueResolver;
+
+ $container->autowire(UserValueResolver::class)
+ ->addTag('controller.argument_value_resolver', ['priority' => 50])
+ ;
+
+While adding a priority is optional, it's recommended to add one to make sure
+the expected value is injected. The ``RequestAttributeValueResolver`` has a
+priority of 100. As this one is responsible for fetching attributes from the
+``Request``, it's recommended to trigger your custom value resolver with a
+lower priority. This makes sure the argument resolvers are not triggered when
+the attribute is present. For instance, when passing the user along a
+sub-requests.
+
+.. tip::
+
+ As you can see in the ``UserValueResolver::supports()`` method, the user
+ may not be available (e.g. when the controller is not behind a firewall).
+ In these cases, the resolver will not be executed. If no argument value
+ is resolved, an exception will be thrown.
+
+ To prevent this, you can add a default value in the controller (e.g. ``User
+ $user = null``). The ``DefaultValueResolver`` is executed as the last
+ resolver and will use the default value if no value was already resolved.
+
+.. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`yield`: http://php.net/manual/en/language.generators.syntax.php
+.. _`SecurityBundle`: https://github.com/symfony/security-bundle
+.. _`PSR-7`: https://www.php-fig.org/psr/psr-7/
+.. _`SensioFrameworkExtraBundle`: https://github.com/sensiolabs/SensioFrameworkExtraBundle
diff --git a/controller/csrf_token_validation.rst b/controller/csrf_token_validation.rst
index 5bf60980925..3bc49401b15 100644
--- a/controller/csrf_token_validation.rst
+++ b/controller/csrf_token_validation.rst
@@ -9,20 +9,11 @@ want to use the Symfony Form component. If, for example, you are implementing
a DELETE action, you can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isCsrfTokenValid`
method to check the validity of a CSRF token::
- public function deleteAction()
+ use Symfony\Component\HttpFoundation\Request;
+
+ public function deleteAction(Request $request)
{
- if ($this->isCsrfTokenValid('token_id', $submittedToken)) {
+ if ($this->isCsrfTokenValid('token_id', $request->request->get('token_param'))) {
// ... do something, like deleting an object
}
}
-
-.. versionadded:: 2.6
- The ``isCsrfTokenValid()`` shortcut method was introduced in Symfony 2.6.
- It is equivalent to executing the following code:
-
- .. code-block:: php
-
- use Symfony\Component\Security\Csrf\CsrfToken;
-
- $this->get('security.csrf.token_manager')
- ->isTokenValid(new CsrfToken('token_id', 'TOKEN'));
diff --git a/controller/error_pages.rst b/controller/error_pages.rst
index d9cef3786a5..7be7c6f4dad 100644
--- a/controller/error_pages.rst
+++ b/controller/error_pages.rst
@@ -154,10 +154,10 @@ To use this feature, you need to have a definition in your
+ https://symfony.com/schema/routing/routing-1.0.xsd">
.. code-block:: php
@@ -207,7 +207,7 @@ configuration option to point to it:
# app/config/config.yml
twig:
- exception_controller: AppBundle:Exception:showException
+ exception_controller: AppBundle:Exception:showAction
.. code-block:: xml
@@ -217,12 +217,12 @@ configuration option to point to it:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:twig="http://symfony.com/schema/dic/twig"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/twig
- http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+ https://symfony.com/schema/dic/twig/twig-1.0.xsd">
- AppBundle:Exception:showException
+ AppBundle:Exception:showAction
@@ -230,10 +230,10 @@ configuration option to point to it:
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('twig', array(
- 'exception_controller' => 'AppBundle:Exception:showException',
+ $container->loadFromExtension('twig', [
+ 'exception_controller' => 'AppBundle:Exception:showAction',
// ...
- ));
+ ]);
The :class:`Symfony\\Component\\HttpKernel\\EventListener\\ExceptionListener`
class used by the TwigBundle as a listener of the ``kernel.exception`` event creates
@@ -248,8 +248,8 @@ will be passed two parameters:
A :class:`\\Symfony\\Component\\HttpKernel\\Log\\DebugLoggerInterface`
instance which may be ``null`` in some circumstances.
-Instead of creating a new exception controller from scratch you can, of course,
-also extend the default :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`.
+Instead of creating a new exception controller from scratch you can also extend
+the default :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`.
In that case, you might want to override one or both of the ``showAction()`` and
``findTemplate()`` methods. The latter one locates the template to be used.
@@ -266,9 +266,15 @@ In that case, you might want to override one or both of the ``showAction()`` and
# app/config/services.yml
services:
- app.exception_controller:
- class: AppBundle\Controller\CustomExceptionController
- arguments: ['@twig', '%kernel.debug%']
+ _defaults:
+ # ... be sure autowiring is enabled
+ autowire: true
+ # ...
+
+ AppBundle\Controller\CustomExceptionController:
+ public: true
+ arguments:
+ $debug: '%kernel.debug%'
.. code-block:: xml
@@ -277,14 +283,15 @@ In that case, you might want to override one or both of the ``showAction()`` and
+ https://symfony.com/schema/dic/services/services-1.0.xsd">
-
- %kernel.debug%
+
+
+ %kernel.debug%
@@ -294,16 +301,9 @@ In that case, you might want to override one or both of the ``showAction()`` and
// app/config/services.php
use AppBundle\Controller\CustomExceptionController;
- use Symfony\Component\DependencyInjection\Reference;
-
- $container->register('app.exception_controller', CustomExceptionController::class)
- ->setArguments(array(
- new Reference('twig'),
- '%kernel.debug%',
- ));
- And then configure ``twig.exception_controller`` using the controller as
- services syntax (e.g. ``app.exception_controller:showAction``).
+ $container->autowire(CustomExceptionController::class)
+ ->setArgument('$debug', '%kernel.debug%');
.. tip::
@@ -350,6 +350,4 @@ time and again, you can have just one (or several) listeners deal with them.
and takes measures like redirecting the user to the login page, logging them
out and other things.
-.. _`WebfactoryExceptionsBundle`: https://github.com/webfactory/exceptions-bundle
.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard/
-.. _`ExceptionListener`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Security/Http/Firewall/ExceptionListener.php
diff --git a/controller/forwarding.rst b/controller/forwarding.rst
index df8a4c685b1..cf727128436 100644
--- a/controller/forwarding.rst
+++ b/controller/forwarding.rst
@@ -13,10 +13,10 @@ from *that* controller::
public function indexAction($name)
{
- $response = $this->forward('AppBundle:Something:fancy', array(
+ $response = $this->forward('AppBundle:Something:fancy', [
'name' => $name,
'color' => 'green',
- ));
+ ]);
// ... further modify the response or return it directly
diff --git a/controller/service.rst b/controller/service.rst
index 11328734b51..1254b44383a 100644
--- a/controller/service.rst
+++ b/controller/service.rst
@@ -4,121 +4,109 @@
How to Define Controllers as Services
=====================================
-.. caution::
+In Symfony, a controller does *not* need to be registered as a service. But if you're
+using the :ref:`default services.yml configuration `,
+your controllers *are* already registered as services. This means you can use dependency
+injection like any other normal service.
- Defining controllers as services is **not officially recommended** by Symfony.
- They are used by some developers for very specific use cases, such as
- DDD (*domain-driven design*) and Hexagonal Architecture applications.
+Referencing your Service from Routing
+-------------------------------------
-In the :doc:`/controller` guide, you've learned how easily a controller can be
-used when it extends the base
-:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class. While
-this works fine, controllers can also be specified as services. Even if you don't
-specify your controllers as services, you might see them being used in some
-open-source Symfony bundles, so it may be useful to understand both approaches.
+Registering your controller as a service is great, but you also need to make sure
+that your routing references the service properly, so that Symfony knows to use it.
-These are the main **advantages** of defining controllers as services:
+If the service id is the fully-qualified class name (FQCN) of your controller, you're
+done! You can use the normal ``AppBundle:Hello:index`` syntax in your routing and
+it will find your service.
-* The entire controller and any service passed to it can be modified via the
- service container configuration. This is useful when developing reusable bundles;
-* Your controllers are more "sandboxed". By looking at the constructor arguments,
- it's easy to see what types of things this controller may or may not do;
-* If you're not passing some required dependencies or if you are injecting some
- non-existent services, you'll get errors during the container compilation
- instead of during runtime execution;
-* Since dependencies must be injected manually, it's more obvious when your
- controller is becoming too big (i.e. if you have many constructor arguments).
+But, if your service has a different id, you can use a special ``SERVICEID:METHOD``
+syntax:
-These are the main **drawbacks** of defining controllers as services:
-
-* It takes more work to create the controllers and they become more verbose
- because they don't have automatic access to the services and the base
- controller shortcuts;
-* The constructor of the controllers can rapidly become too complex because you
- must inject every single dependency needed by them.
-
-The recommendation from the :doc:`best practices `
-is also valid for controllers defined as services: avoid putting your business
-logic into the controllers. Instead, inject services that do the bulk of the work.
-
-Defining the Controller as a Service
-------------------------------------
+.. configuration-block::
-A controller can be defined as a service in the same way as any other class.
-For example, if you have the following simple controller::
+ .. code-block:: php-annotations
- // src/AppBundle/Controller/HelloController.php
- namespace AppBundle\Controller;
+ // src/AppBundle/Controller/HelloController.php
- use Symfony\Component\HttpFoundation\Response;
+ // You need to use Sensio's annotation to specify a service id
+ use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
- class HelloController
- {
- public function indexAction($name)
+ /**
+ * @Route(service="app.hello_controller")
+ */
+ class HelloController
{
- return new Response('Hello '.$name.'!');
+ // ...
}
- }
-
-Then you can define it as a service as follows:
-
-.. configuration-block::
.. code-block:: yaml
- # app/config/services.yml
- services:
- app.hello_controller:
- class: AppBundle\Controller\HelloController
+ # app/config/routing.yml
+ hello:
+ path: /hello
+ defaults: { _controller: app.hello_controller:indexAction }
.. code-block:: xml
-
+
-
+ xsi:schemaLocation="http://symfony.com/schema/routing
+ https://symfony.com/schema/routing/routing-1.0.xsd">
-
-
+
+ app.hello_controller:indexAction
+
-
+
.. code-block:: php
- // app/config/services.php
- use AppBundle\Controller\HelloController;
+ // app/config/routing.php
+ $collection->add('hello', new Route('/hello', [
+ '_controller' => 'app.hello_controller:indexAction',
+ ]));
- $container->register('app.hello_controller', HelloController::class);
+.. note::
-Referring to the Service
-------------------------
+ You cannot drop the ``Action`` part of the method name when using the
+ single colon notation.
-To refer to a controller that's defined as a service, use the single colon (:)
-notation. For example, to forward to the ``indexAction()`` method of the service
-defined above with the id ``app.hello_controller``::
+.. _controller-service-invoke:
- $this->forward('app.hello_controller:indexAction', array('name' => $name));
+Invokable Controllers
+---------------------
-.. note::
+Controllers can also define a single action using the ``__invoke()`` method,
+which is a common practice when following the `ADR pattern`_
+(Action-Domain-Responder):
- Make sure the method name in your route (e.g. ``indexAction``) matches the
- method name exactly. Unlike the traditional ``Bundle:Controller:method``
- notation, the ``Action`` suffix is not automatically added for you.
+.. configuration-block::
-You can also route to the service by using the same notation when defining
-the route ``_controller`` value:
+ .. code-block:: php-annotations
-.. configuration-block::
+ // src/AppBundle/Controller/Hello.php
+ use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Routing\Annotation\Route;
+
+ /**
+ * @Route("/hello/{name}", name="hello")
+ */
+ class Hello
+ {
+ public function __invoke($name = 'World')
+ {
+ return new Response(sprintf('Hello %s!', $name));
+ }
+ }
.. code-block:: yaml
# app/config/routing.yml
hello:
- path: /hello
- defaults: { _controller: app.hello_controller:indexAction }
+ path: /hello/{name}
+ defaults: { _controller: app.hello_controller }
.. code-block:: xml
@@ -127,10 +115,10 @@ the route ``_controller`` value:
+ https://symfony.com/schema/routing/routing-1.0.xsd">
-
- app.hello_controller:indexAction
+
+ app.hello_controller
@@ -138,59 +126,21 @@ the route ``_controller`` value:
.. code-block:: php
// app/config/routing.php
- $collection->add('hello', new Route('/hello', array(
- '_controller' => 'app.hello_controller:indexAction',
- )));
-
-.. tip::
-
- You can also use annotations to configure routing using a controller
- defined as a service. Make sure you specify the service ID in the
- ``@Route`` annotation. See the `FrameworkExtraBundle documentation`_ for
- details.
-
-.. tip::
-
- If your controller implements the ``__invoke()`` method, you can simply
- refer to the service id (``app.hello_controller``).
+ $collection->add('hello', new Route('/hello', [
+ '_controller' => 'app.hello_controller',
+ ]));
Alternatives to base Controller Methods
---------------------------------------
-When using a controller defined as a service, it will most likely not extend
-the base ``Controller`` class. Instead of relying on its shortcut methods,
-you'll interact directly with the services that you need. Fortunately, this is
-usually pretty easy and the base `Controller class source code`_ is a great
-source on how to perform many common tasks.
-
-For example, if you want to render a template instead of creating the ``Response``
-object directly, then your code would look like this if you were extending
-Symfony's base controller::
-
- // src/AppBundle/Controller/HelloController.php
- namespace AppBundle\Controller;
-
- use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+When using a controller defined as a service, you can still extend any of the
+:ref:`normal base controller ` classes and
+use their shortcuts. But, you don't need to! You can choose to extend *nothing*,
+and use dependency injection to access different services.
- class HelloController extends Controller
- {
- public function indexAction($name)
- {
- return $this->render(
- 'hello/index.html.twig',
- array('name' => $name)
- );
- }
- }
-
-If you look at the source code for the ``render()`` function in Symfony's
-`base Controller class`_, you'll see that this method actually uses the
-``templating`` service::
-
- public function render($view, array $parameters = array(), Response $response = null)
- {
- return $this->container->get('templating')->renderResponse($view, $parameters, $response);
- }
+The base `Controller class source code`_ is a great way to see how to accomplish
+common tasks. For example, ``$this->render()`` is usually used to render a Twig
+template and return a Response. But, you can also do this directly:
In a controller that's defined as a service, you can instead inject the ``templating``
service and use it directly::
@@ -198,174 +148,42 @@ service and use it directly::
// src/AppBundle/Controller/HelloController.php
namespace AppBundle\Controller;
- use Symfony\Bundle\FrameworkBundle\Templating\EngineInterface;
use Symfony\Component\HttpFoundation\Response;
+ use Twig\Environment;
class HelloController
{
- private $templating;
+ private $twig;
- public function __construct(EngineInterface $templating)
+ public function __construct(Environment $twig)
{
- $this->templating = $templating;
+ $this->twig = $twig;
}
public function indexAction($name)
{
- return $this->templating->renderResponse(
+ $content = $this->twig->render(
'hello/index.html.twig',
- array('name' => $name)
+ ['name' => $name]
);
+
+ return new Response($content);
}
}
-The service definition also needs modifying to specify the constructor
-argument:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/services.yml
- services:
- app.hello_controller:
- class: AppBundle\Controller\HelloController
- arguments: ['@templating']
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/services.php
- use AppBundle\Controller\HelloController;
- use Symfony\Component\DependencyInjection\Reference;
-
- $container->register('app.hello_controller', HelloController::class)
- ->addArgument(new Reference('templating'));
-
-Rather than fetching the ``templating`` service from the container, you can
-inject *only* the exact service(s) that you need directly into the controller.
-
-.. note::
-
- This does not mean that you cannot extend these controllers from your own
- base controller. The move away from the standard base controller is because
- its helper methods rely on having the container available which is not
- the case for controllers that are defined as services. It may be a good
- idea to extract common code into a service that's injected rather than
- place that code into a base controller that you extend. Both approaches
- are valid, exactly how you want to organize your reusable code is up to
- you.
+You can also use a special :ref:`action-based dependency injection `
+to receive services as arguments to your controller action methods.
Base Controller Methods and Their Service Replacements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This list explains how to replace the convenience methods of the base
-controller:
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createForm` (service: ``form.factory``)
- .. code-block:: php
-
- $formFactory->create($type, $data, $options);
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createFormBuilder` (service: ``form.factory``)
- .. code-block:: php
-
- $formFactory->createBuilder('form', $data, $options);
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createNotFoundException`
- .. code-block:: php
-
- new NotFoundHttpException($message, $previous);
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::forward` (service: ``http_kernel``)
- .. code-block:: php
-
- use Symfony\Component\HttpKernel\HttpKernelInterface;
- // ...
-
- $request = ...;
- $attributes = array_merge($path, array('_controller' => $controller));
- $subRequest = $request->duplicate($query, null, $attributes);
- $httpKernel->handle($subRequest, HttpKernelInterface::SUB_REQUEST);
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::generateUrl` (service: ``router``)
- .. code-block:: php
-
- $router->generate($route, $params, $referenceType);
-
- .. note::
-
- The ``$referenceType`` argument must be one of the constants defined
- in the :class:`Symfony\\Component\\Routing\\Generator\\UrlGeneratorInterface`.
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` (service: ``doctrine``)
- *Simply inject doctrine instead of fetching it from the container.*
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getUser` (service: ``security.token_storage``)
- .. code-block:: php
-
- $user = null;
- $token = $tokenStorage->getToken();
- if (null !== $token && is_object($token->getUser())) {
- $user = $token->getUser();
- }
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isGranted` (service: ``security.authorization_checker``)
- .. code-block:: php
-
- $authChecker->isGranted($attributes, $object);
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::redirect`
- .. code-block:: php
-
- use Symfony\Component\HttpFoundation\RedirectResponse;
-
- return new RedirectResponse($url, $status);
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::render` (service: ``templating``)
- .. code-block:: php
-
- $templating->renderResponse($view, $parameters, $response);
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::renderView` (service: ``templating``)
- .. code-block:: php
-
- $templating->render($view, $parameters);
-
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::stream` (service: ``templating``)
- .. code-block:: php
-
- use Symfony\Component\HttpFoundation\StreamedResponse;
-
- $templating = $this->templating;
- $callback = function () use ($templating, $view, $parameters) {
- $templating->stream($view, $parameters);
- };
-
- return new StreamedResponse($callback);
-
-.. tip::
+The best way to see how to replace base ``Controller`` convenience methods is to
+look at the `ControllerTrait`_ that holds its logic.
- ``getRequest()`` has been deprecated. Instead, have an argument to your
- controller action method called ``Request $request``. The order of the
- parameters is not important, but the typehint must be provided.
+If you want to know what type-hints to use for each service, see the
+``getSubscribedServices()`` method in `AbstractController`_.
-.. _`Controller class source code`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php
-.. _`base Controller class`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php
-.. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/routing.html#controller-as-service
+.. _`Controller class source code`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php
+.. _`ControllerTrait`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php
+.. _`AbstractController`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/AbstractController.php
+.. _`ADR pattern`: https://en.wikipedia.org/wiki/Action%E2%80%93domain%E2%80%93responder
diff --git a/controller/soap_web_service.rst b/controller/soap_web_service.rst
index 5a253a0c1b8..4bbda5f2db6 100644
--- a/controller/soap_web_service.rst
+++ b/controller/soap_web_service.rst
@@ -6,10 +6,10 @@
How to Create a SOAP Web Service in a Symfony Controller
========================================================
-Setting up a controller to act as a SOAP server is simple with a couple
-tools. You must, of course, have the `PHP SOAP`_ extension installed.
-As the PHP SOAP extension cannot currently generate a WSDL, you must either
-create one from scratch or use a 3rd party generator.
+Setting up a controller to act as a SOAP server is simple with a couple tools.
+You must have the `PHP SOAP`_ extension installed. As the PHP SOAP extension
+cannot currently generate a WSDL, you must either create one from scratch or use
+a 3rd party generator.
.. note::
@@ -24,8 +24,8 @@ which represents the functionality that you'll expose in your SOAP service.
In this case, the SOAP service will allow the client to call a method called
``hello``, which happens to send an email::
- // src/Acme/SoapBundle/Services/HelloService.php
- namespace Acme\SoapBundle\Services;
+ // src/AppBundle/Service/HelloService.php
+ namespace AppBundle\Service;
class HelloService
{
@@ -49,62 +49,30 @@ In this case, the SOAP service will allow the client to call a method called
}
}
-Next, you can train Symfony to be able to create an instance of this class.
-Since the class sends an email, it's been designed to accept a ``Swift_Mailer``
-instance. Using the Service Container, you can configure Symfony to construct
-a ``HelloService`` object properly:
+Next, make sure that your new class is registered as a service. If you're using
+the :ref:`default services configuration `,
+you don't need to do anything!
-.. configuration-block::
+Finally, below is an example of a controller that is capable of handling a SOAP
+request. Because ``indexAction()`` is accessible via ``/soap``, the WSDL document
+can be retrieved via ``/soap?wsdl``::
- .. code-block:: yaml
-
- # app/config/services.yml
- services:
- hello_service:
- class: Acme\SoapBundle\Services\HelloService
- arguments: ['@mailer']
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/services.php
- use Acme\SoapBundle\Services\HelloService;
-
- $container
- ->register('hello_service', HelloService::class)
- ->addArgument(new Reference('mailer'));
-
-Below is an example of a controller that is capable of handling a SOAP
-request. If ``indexAction()`` is accessible via the route ``/soap``, then the
-WSDL document can be retrieved via ``/soap?wsdl``::
-
- namespace Acme\SoapBundle\Controller;
+ namespace AppBundle\Controller;
+ use AppBundle\Service\HelloService;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Routing\Annotation\Route;
class HelloServiceController extends Controller
{
- public function indexAction()
+ /**
+ * @Route("/soap")
+ */
+ public function indexAction(HelloService $helloService)
{
$soapServer = new \SoapServer('/path/to/hello.wsdl');
- $soapServer->setObject($this->get('hello_service'));
+ $soapServer->setObject($helloService);
$response = new Response();
$response->headers->set('Content-Type', 'text/xml; charset=ISO-8859-1');
@@ -121,7 +89,7 @@ Take note of the calls to ``ob_start()`` and ``ob_get_clean()``. These
methods control `output buffering`_ which allows you to "trap" the echoed
output of ``$server->handle()``. This is necessary because Symfony expects
your controller to return a ``Response`` object with the output as its "content".
-You must also remember to set the "Content-Type" header to "text/xml", as
+You must also remember to set the ``"Content-Type"`` header to ``"text/xml"``, as
this is what the client will expect. So, you use ``ob_start()`` to start
buffering the STDOUT and use ``ob_get_clean()`` to dump the echoed output
into the content of the Response and clear the output buffer. Finally, you're
@@ -133,7 +101,7 @@ route ``/soap``::
$soapClient = new \SoapClient('http://example.com/app.php/soap?wsdl');
- $result = $soapClient->call('hello', array('name' => 'Scott'));
+ $result = $soapClient->call('hello', ['name' => 'Scott']);
An example WSDL is below.
@@ -144,7 +112,7 @@ An example WSDL is below.
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
- xmlns:tns="urn:arnleadservicewsdl"
+ xmlns:tns="urn:helloservicewsdl"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://schemas.xmlsoap.org/wsdl/"
@@ -152,17 +120,17 @@ An example WSDL is below.
-
-
-
@@ -192,7 +160,7 @@ An example WSDL is below.
-
diff --git a/controller/upload_file.rst b/controller/upload_file.rst
index 3cbd3e83265..8b16bc7c499 100644
--- a/controller/upload_file.rst
+++ b/controller/upload_file.rst
@@ -12,14 +12,13 @@ How to Upload Files
integrated with Doctrine ORM, MongoDB ODM, PHPCR ODM and Propel.
Imagine that you have a ``Product`` entity in your application and you want to
-add a PDF brochure for each product. To do so, add a new property called ``brochure``
-in the ``Product`` entity::
+add a PDF brochure for each product. To do so, add a new property called
+``brochureFilename`` in the ``Product`` entity::
// src/AppBundle/Entity/Product.php
namespace AppBundle\Entity;
use Doctrine\ORM\Mapping as ORM;
- use Symfony\Component\Validator\Constraints as Assert;
class Product
{
@@ -27,38 +26,40 @@ in the ``Product`` entity::
/**
* @ORM\Column(type="string")
- *
- * @Assert\NotBlank(message="Please, upload the product brochure as a PDF file.")
- * @Assert\File(mimeTypes={ "application/pdf" })
*/
- private $brochure;
+ private $brochureFilename;
- public function getBrochure()
+ public function getBrochureFilename()
{
- return $this->brochure;
+ return $this->brochureFilename;
}
- public function setBrochure($brochure)
+ public function setBrochureFilename($brochureFilename)
{
- $this->brochure = $brochure;
+ $this->brochureFilename = $brochureFilename;
return $this;
}
}
-Note that the type of the ``brochure`` column is ``string`` instead of ``binary``
-or ``blob`` because it just stores the PDF file name instead of the file contents.
+Note that the type of the ``brochureFilename`` column is ``string`` instead of
+``binary`` or ``blob`` because it only stores the PDF file name instead of the
+file contents.
-Then, add a new ``brochure`` field to the form that manages the ``Product`` entity::
+The next step is to add a new field to the form that manages the ``Product``
+entity. This must be a ``FileType`` field so the browsers can display the file
+upload widget. The trick to make it work is to add the form field as "unmapped",
+so Symfony doesn't try to get/set its value from the related entity::
// src/AppBundle/Form/ProductType.php
namespace AppBundle\Form;
use AppBundle\Entity\Product;
use Symfony\Component\Form\AbstractType;
+ use Symfony\Component\Form\Extension\Core\Type\FileType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
- use Symfony\Component\Form\Extension\Core\Type\FileType;
+ use Symfony\Component\Validator\Constraints\File;
class ProductType extends AbstractType
{
@@ -66,16 +67,38 @@ Then, add a new ``brochure`` field to the form that manages the ``Product`` enti
{
$builder
// ...
- ->add('brochure', FileType::class, array('label' => 'Brochure (PDF file)'))
+ ->add('brochure', FileType::class, [
+ 'label' => 'Brochure (PDF file)',
+
+ // unmapped means that this field is not associated to any entity property
+ 'mapped' => false,
+
+ // make it optional so you don't have to re-upload the PDF file
+ // every time you edit the Product details
+ 'required' => false,
+
+ // unmapped fields can't define their validation using annotations
+ // in the associated entity, so you can use the PHP constraint classes
+ 'constraints' => [
+ new File([
+ 'maxSize' => '1024k',
+ 'mimeTypes' => [
+ 'application/pdf',
+ 'application/x-pdf',
+ ],
+ 'mimeTypesMessage' => 'Please upload a valid PDF document',
+ ])
+ ],
+ ])
// ...
;
}
public function configureOptions(OptionsResolver $resolver)
{
- $resolver->setDefaults(array(
+ $resolver->setDefaults([
'data_class' => Product::class,
- ));
+ ]);
}
}
@@ -99,12 +122,13 @@ Finally, you need to update the code of the controller that handles the form::
// src/AppBundle/Controller/ProductController.php
namespace AppBundle\Controller;
- use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+ use AppBundle\Entity\Product;
+ use AppBundle\Form\ProductType;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\File\Exception\FileException;
+ use Symfony\Component\HttpFoundation\File\UploadedFile;
use Symfony\Component\HttpFoundation\Request;
- use AppBundle\Entity\Product;
- use AppBundle\Form\ProductType;
+ use Symfony\Component\Routing\Annotation\Route;
class ProductController extends Controller
{
@@ -118,44 +142,40 @@ Finally, you need to update the code of the controller that handles the form::
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
- // $file stores the uploaded PDF file
- /** @var Symfony\Component\HttpFoundation\File\UploadedFile $file */
- $file = $product->getBrochure();
-
- $fileName = $this->generateUniqueFileName().'.'.$file->guessExtension();
-
- // Move the file to the directory where brochures are stored
- try {
- $file->move(
- $this->getParameter('brochures_directory'),
- $fileName
- );
- } catch (FileException $e) {
- // ... handle exception if something happens during file upload
+ /** @var UploadedFile $brochureFile */
+ $brochureFile = $form->get('brochure')->getData();
+
+ // this condition is needed because the 'brochure' field is not required
+ // so the PDF file must be processed only when a file is uploaded
+ if ($brochureFile) {
+ $originalFilename = pathinfo($brochureFile->getClientOriginalName(), PATHINFO_FILENAME);
+ // this is needed to safely include the file name as part of the URL
+ $safeFilename = transliterator_transliterate('Any-Latin; Latin-ASCII; [^A-Za-z0-9_] remove; Lower()', $originalFilename);
+ $newFilename = $safeFilename.'-'.uniqid().'.'.$brochureFile->guessExtension();
+
+ // Move the file to the directory where brochures are stored
+ try {
+ $brochureFile->move(
+ $this->getParameter('brochures_directory'),
+ $newFilename
+ );
+ } catch (FileException $e) {
+ // ... handle exception if something happens during file upload
+ }
+
+ // updates the 'brochureFilename' property to store the PDF file name
+ // instead of its contents
+ $product->setBrochureFilename($newFilename);
}
- // updates the 'brochure' property to store the PDF file name
- // instead of its contents
- $product->setBrochure($fileName);
-
// ... persist the $product variable or any other work
- return $this->redirect($this->generateUrl('app_product_list'));
+ return $this->redirectToRoute('app_product_list');
}
- return $this->render('product/new.html.twig', array(
+ return $this->render('product/new.html.twig', [
'form' => $form->createView(),
- ));
- }
-
- /**
- * @return string
- */
- private function generateUniqueFileName()
- {
- // md5() reduces the similarity of the file names generated by
- // uniqid(), which is based on timestamps
- return md5(uniqid());
+ ]);
}
}
@@ -168,13 +188,10 @@ controller to specify the directory in which the brochures should be stored:
# ...
parameters:
- brochures_directory: '%kernel.root_dir%/../web/uploads/brochures'
+ brochures_directory: '%kernel.project_dir%/web/uploads/brochures'
There are some important things to consider in the code of the above controller:
-#. When the form is uploaded, the ``brochure`` property contains the whole PDF
- file contents. Since this property stores just the file name, you must set
- its new value before persisting the changes of the entity;
#. In Symfony applications, uploaded files are objects of the
:class:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile` class. This class
provides methods for the most common operations when dealing with uploaded files;
@@ -193,7 +210,7 @@ You can use the following code to link to the PDF brochure of a product:
.. code-block:: html+twig
- View brochure (PDF)
+ View brochure (PDF)
.. tip::
@@ -206,8 +223,8 @@ You can use the following code to link to the PDF brochure of a product:
use Symfony\Component\HttpFoundation\File\File;
// ...
- $product->setBrochure(
- new File($this->getParameter('brochures_directory').'/'.$product->getBrochure())
+ $product->setBrochureFilename(
+ new File($this->getParameter('brochures_directory').'/'.$product->getBrochureFilename())
);
Creating an Uploader Service
@@ -216,8 +233,8 @@ Creating an Uploader Service
To avoid logic in controllers, making them big, you can extract the upload
logic to a separate service::
- // src/AppBundle/FileUploader.php
- namespace AppBundle;
+ // src/AppBundle/Service/FileUploader.php
+ namespace AppBundle\Service;
use Symfony\Component\HttpFoundation\File\Exception\FileException;
use Symfony\Component\HttpFoundation\File\UploadedFile;
@@ -233,7 +250,9 @@ logic to a separate service::
public function upload(UploadedFile $file)
{
- $fileName = md5(uniqid()).'.'.$file->guessExtension();
+ $originalFilename = pathinfo($file->getClientOriginalName(), PATHINFO_FILENAME);
+ $safeFilename = transliterator_transliterate('Any-Latin; Latin-ASCII; [^A-Za-z0-9_] remove; Lower()', $originalFilename);
+ $fileName = $safeFilename.'-'.uniqid().'.'.$file->guessExtension();
try {
$file->move($this->getTargetDirectory(), $fileName);
@@ -259,49 +278,52 @@ Then, define a service for this class:
# app/config/services.yml
services:
# ...
- app.brochure_uploader:
- class: AppBundle\FileUploader
- arguments: ['%brochures_directory%']
+
+ AppBundle\Service\FileUploader:
+ arguments:
+ $targetDirectory: '%brochures_directory%'
.. code-block:: xml
-
+
+ https://symfony.com/schema/dic/services/services-1.0.xsd">
-
+
%brochures_directory%
-
.. code-block:: php
// app/config/services.php
- use AppBundle\FileUploader;
+ use AppBundle\Service\FileUploader;
- // ...
- $container->register('app.brochure_uploader', FileUploader::class)
- ->addArgument('%brochures_directory%');
+ $container->autowire(FileUploader::class)
+ ->setArgument('$targetDirectory', '%brochures_directory%');
Now you're ready to use this service in the controller::
// src/AppBundle/Controller/ProductController.php
+ use AppBundle\Service\FileUploader;
+ use Symfony\Component\HttpFoundation\Request;
// ...
- public function newAction(Request $request)
+ public function newAction(Request $request, FileUploader $fileUploader)
{
// ...
if ($form->isSubmitted() && $form->isValid()) {
- $file = $product->getBrochure();
- $fileName = $this->get('app.brochure_uploader')->upload($file);
-
- $product->setBrochure($fileName);
+ /** @var UploadedFile $brochureFile */
+ $brochureFile = $form->get('brochure')->getData();
+ if ($brochureFile) {
+ $brochureFileName = $fileUploader->upload($brochureFile);
+ $product->setBrochureFilename($brochureFileName);
+ }
// ...
}
@@ -312,150 +334,16 @@ Now you're ready to use this service in the controller::
Using a Doctrine Listener
-------------------------
-If you are using Doctrine to store the Product entity, you can create a
-:doc:`Doctrine listener ` to
-automatically upload the file when persisting the entity::
-
- // src/AppBundle/EventListener/BrochureUploadListener.php
- namespace AppBundle\EventListener;
-
- use Symfony\Component\HttpFoundation\File\UploadedFile;
- use Symfony\Component\HttpFoundation\File\File;
- use Doctrine\ORM\Event\LifecycleEventArgs;
- use Doctrine\ORM\Event\PreUpdateEventArgs;
- use AppBundle\Entity\Product;
- use AppBundle\FileUploader;
-
- class BrochureUploadListener
- {
- private $uploader;
-
- public function __construct(FileUploader $uploader)
- {
- $this->uploader = $uploader;
- }
-
- public function prePersist(LifecycleEventArgs $args)
- {
- $entity = $args->getEntity();
-
- $this->uploadFile($entity);
- }
-
- public function preUpdate(PreUpdateEventArgs $args)
- {
- $entity = $args->getEntity();
-
- $this->uploadFile($entity);
- }
-
- private function uploadFile($entity)
- {
- // upload only works for Product entities
- if (!$entity instanceof Product) {
- return;
- }
-
- $file = $entity->getBrochure();
-
- // only upload new files
- if ($file instanceof UploadedFile) {
- $fileName = $this->uploader->upload($file);
- $entity->setBrochure($fileName);
- } elseif ($file instanceof File) {
- // prevents the full file path being saved on updates
- // as the path is set on the postLoad listener
- $entity->setBrochure($file->getFilename());
- }
- }
- }
-
-Now, register this class as a Doctrine listener:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/services.yml
- services:
- # ...
- app.doctrine_brochure_listener:
- class: AppBundle\EventListener\BrochureUploadListener
- arguments: ['@app.brochure_uploader']
- tags:
- - { name: doctrine.event_listener, event: prePersist }
- - { name: doctrine.event_listener, event: preUpdate }
-
- .. code-block:: xml
+The previous versions of this article explained how to handle file uploads using
+:doc:`Doctrine listeners `. However, this
+is no longer recommended, because Doctrine events shouldn't be used for your
+domain logic.
-
-
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/services.php
- use AppBundle\EventListener\BrochureUploaderListener;
- use Symfony\Component\DependencyInjection\Reference;
-
- // ...
- $container->register('app.doctrine_brochure_listener', BrochureUploaderListener::class)
- ->addArgument(new Reference('app.brochure_uploader'))
- ->addTag('doctrine.event_listener', array(
- 'event' => 'prePersist',
- ))
- ->addTag('doctrine.event_listener', array(
- 'event' => 'prePersist',
- ));
-
-This listener is now automatically executed when persisting a new Product
-entity. This way, you can remove everything related to uploading from the
-controller.
-
-.. tip::
-
- This listener can also create the ``File`` instance based on the path when
- fetching entities from the database::
-
- // ...
- use Symfony\Component\HttpFoundation\File\File;
-
- // ...
- class BrochureUploadListener
- {
- // ...
-
- public function postLoad(LifecycleEventArgs $args)
- {
- $entity = $args->getEntity();
-
- if (!$entity instanceof Product) {
- return;
- }
-
- if ($fileName = $entity->getBrochure()) {
- $entity->setBrochure(new File($this->uploader->getTargetDir().'/'.$fileName));
- }
- }
- }
+Moreover, Doctrine listeners are often dependent on internal Doctrine behavior
+which may change in future versions. Also, they can introduce performance issues
+unwillingly (because your listener persists entities which cause other entities to
+be changed and persisted).
- After adding these lines, configure the listener to also listen for the
- ``postLoad`` event.
+As an alternative, you can use :doc:`Symfony events, listeners and subscribers `.
.. _`VichUploaderBundle`: https://github.com/dustin10/VichUploaderBundle
diff --git a/create_framework/dependency_injection.rst b/create_framework/dependency_injection.rst
index b4bbf19a703..97292d22843 100644
--- a/create_framework/dependency_injection.rst
+++ b/create_framework/dependency_injection.rst
@@ -9,9 +9,11 @@ to it::
// example.com/src/Simplex/Framework.php
namespace Simplex;
- use Symfony\Component\Routing;
- use Symfony\Component\HttpKernel;
use Symfony\Component\EventDispatcher\EventDispatcher;
+ use Symfony\Component\HttpFoundation;
+ use Symfony\Component\HttpFoundation\RequestStack;
+ use Symfony\Component\HttpKernel;
+ use Symfony\Component\Routing;
class Framework extends HttpKernel\HttpKernel
{
@@ -19,13 +21,16 @@ to it::
{
$context = new Routing\RequestContext();
$matcher = new Routing\Matcher\UrlMatcher($routes, $context);
- $resolver = new HttpKernel\Controller\ControllerResolver();
+ $requestStack = new RequestStack();
+
+ $controllerResolver = new HttpKernel\Controller\ControllerResolver();
+ $argumentResolver = new HttpKernel\Controller\ArgumentResolver();
$dispatcher = new EventDispatcher();
- $dispatcher->addSubscriber(new HttpKernel\EventListener\RouterListener($matcher));
+ $dispatcher->addSubscriber(new HttpKernel\EventListener\RouterListener($matcher, $requestStack));
$dispatcher->addSubscriber(new HttpKernel\EventListener\ResponseListener('UTF-8'));
- parent::__construct($dispatcher, $resolver);
+ parent::__construct($dispatcher, $controllerResolver, $requestStack, $argumentResolver);
}
}
@@ -61,15 +66,15 @@ framework more configurable, but at the same time, it introduces a lot of
issues:
* We are not able to register custom listeners anymore as the dispatcher is
- not available outside the Framework class (an easy workaround could be the
+ not available outside the Framework class (a workaround could be the
adding of a ``Framework::getEventDispatcher()`` method);
* We have lost the flexibility we had before; you cannot change the
implementation of the ``UrlMatcher`` or of the ``ControllerResolver``
anymore;
-* Related to the previous point, we cannot test our framework easily anymore
- as it's impossible to mock internal objects;
+* Related to the previous point, we cannot test our framework without much
+ effort anymore as it's impossible to mock internal objects;
* We cannot change the charset passed to ``ResponseListener`` anymore (a
workaround could be to pass it as a constructor argument).
@@ -92,38 +97,44 @@ container:
Create a new file to host the dependency injection container configuration::
// example.com/src/container.php
+ use Simplex\Framework;
use Symfony\Component\DependencyInjection;
use Symfony\Component\DependencyInjection\Reference;
+ use Symfony\Component\EventDispatcher;
use Symfony\Component\HttpFoundation;
use Symfony\Component\HttpKernel;
use Symfony\Component\Routing;
- use Symfony\Component\EventDispatcher;
- use Simplex\Framework;
$containerBuilder = new DependencyInjection\ContainerBuilder();
$containerBuilder->register('context', Routing\RequestContext::class);
$containerBuilder->register('matcher', Routing\Matcher\UrlMatcher::class)
- ->setArguments(array($routes, new Reference('context')))
+ ->setArguments([$routes, new Reference('context')])
;
$containerBuilder->register('request_stack', HttpFoundation\RequestStack::class);
- $containerBuilder->register('resolver', HttpKernel\Controller\ControllerResolver::class);
+ $containerBuilder->register('controller_resolver', HttpKernel\Controller\ControllerResolver::class);
+ $containerBuilder->register('argument_resolver', HttpKernel\Controller\ArgumentResolver::class);
$containerBuilder->register('listener.router', HttpKernel\EventListener\RouterListener::class)
- ->setArguments(array(new Reference('matcher'), new Reference('request_stack')))
+ ->setArguments([new Reference('matcher'), new Reference('request_stack')])
;
$containerBuilder->register('listener.response', HttpKernel\EventListener\ResponseListener::class)
- ->setArguments(array('UTF-8'))
+ ->setArguments(['UTF-8'])
;
$containerBuilder->register('listener.exception', HttpKernel\EventListener\ExceptionListener::class)
- ->setArguments(array('Calendar\Controller\ErrorController::exceptionAction'))
+ ->setArguments(['Calendar\Controller\ErrorController::exceptionAction'])
;
$containerBuilder->register('dispatcher', EventDispatcher\EventDispatcher::class)
- ->addMethodCall('addSubscriber', array(new Reference('listener.router')))
- ->addMethodCall('addSubscriber', array(new Reference('listener.response')))
- ->addMethodCall('addSubscriber', array(new Reference('listener.exception')))
+ ->addMethodCall('addSubscriber', [new Reference('listener.router')])
+ ->addMethodCall('addSubscriber', [new Reference('listener.response')])
+ ->addMethodCall('addSubscriber', [new Reference('listener.exception')])
;
$containerBuilder->register('framework', Framework::class)
- ->setArguments(array(new Reference('dispatcher'), new Reference('resolver')))
+ ->setArguments([
+ new Reference('dispatcher'),
+ new Reference('controller_resolver'),
+ new Reference('request_stack'),
+ new Reference('argument_resolver'),
+ ])
;
return $containerBuilder;
@@ -187,7 +198,7 @@ Now, here is how you can register a custom listener in the front controller::
$container->register('listener.string_response', StringResponseListener::class);
$container->getDefinition('dispatcher')
- ->addMethodCall('addSubscriber', array(new Reference('listener.string_response')))
+ ->addMethodCall('addSubscriber', [new Reference('listener.string_response')])
;
Beside describing your objects, the dependency injection container can also be
@@ -203,7 +214,7 @@ charset configurable::
// ...
$container->register('listener.response', HttpKernel\EventListener\ResponseListener::class)
- ->setArguments(array('%charset%'))
+ ->setArguments(['%charset%'])
;
After this change, you must set the charset before using the response listener
@@ -216,16 +227,16 @@ Instead of relying on the convention that the routes are defined by the
// ...
$container->register('matcher', Routing\Matcher\UrlMatcher::class)
- ->setArguments(array('%routes%', new Reference('context')))
+ ->setArguments(['%routes%', new Reference('context')])
;
And the related change in the front controller::
$container->setParameter('routes', include __DIR__.'/../src/app.php');
-We have obviously barely scratched the surface of what you can do with the
+We have barely scratched the surface of what you can do with the
container: from class names as parameters, to overriding existing object
-definitions, from scope support to dumping a container to a plain PHP class,
+definitions, from shared service support to dumping a container to a plain PHP class,
and much more. The Symfony dependency injection container is really powerful
and is able to manage any kind of PHP class.
@@ -242,4 +253,3 @@ internally.
Have fun!
.. _`Pimple`: https://github.com/silexphp/Pimple
-.. _`Application`: https://github.com/silexphp/Silex/blob/master/src/Silex/Application.php
diff --git a/create_framework/event_dispatcher.rst b/create_framework/event_dispatcher.rst
index f740a8d39a6..4adea3cd058 100644
--- a/create_framework/event_dispatcher.rst
+++ b/create_framework/event_dispatcher.rst
@@ -3,8 +3,7 @@ The EventDispatcher Component
Our framework is still missing a major characteristic of any good framework:
*extensibility*. Being extensible means that the developer should be able to
-easily hook into the framework life cycle to modify the way the request is
-handled.
+hook into the framework life cycle to modify the way the request is handled.
What kind of hooks are we talking about? Authentication or caching for
instance. To be flexible, hooks must be plug-and-play; the ones you "register"
@@ -36,24 +35,27 @@ the Response instance::
// example.com/src/Simplex/Framework.php
namespace Simplex;
+ use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
- use Symfony\Component\Routing\Matcher\UrlMatcherInterface;
- use Symfony\Component\Routing\Exception\ResourceNotFoundException;
+ use Symfony\Component\HttpKernel\Controller\ArgumentResolverInterface;
use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
- use Symfony\Component\EventDispatcher\EventDispatcher;
+ use Symfony\Component\Routing\Exception\ResourceNotFoundException;
+ use Symfony\Component\Routing\Matcher\UrlMatcherInterface;
class Framework
{
- private $matcher;
- private $resolver;
private $dispatcher;
+ private $matcher;
+ private $controllerResolver;
+ private $argumentResolver;
- public function __construct(EventDispatcher $dispatcher, UrlMatcherInterface $matcher, ControllerResolverInterface $resolver)
+ public function __construct(EventDispatcher $dispatcher, UrlMatcherInterface $matcher, ControllerResolverInterface $controllerResolver, ArgumentResolverInterface $argumentResolver)
{
- $this->matcher = $matcher;
- $this->resolver = $resolver;
$this->dispatcher = $dispatcher;
+ $this->matcher = $matcher;
+ $this->controllerResolver = $controllerResolver;
+ $this->argumentResolver = $argumentResolver;
}
public function handle(Request $request)
@@ -63,8 +65,8 @@ the Response instance::
try {
$request->attributes->add($this->matcher->match($request->getPathInfo()));
- $controller = $this->resolver->getController($request);
- $arguments = $this->resolver->getArguments($request, $controller);
+ $controller = $this->controllerResolver->getController($request);
+ $arguments = $this->argumentResolver->getArguments($request, $controller);
$response = call_user_func_array($controller, $arguments);
} catch (ResourceNotFoundException $exception) {
@@ -86,9 +88,9 @@ now dispatched::
// example.com/src/Simplex/ResponseEvent.php
namespace Simplex;
+ use Symfony\Component\EventDispatcher\Event;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
- use Symfony\Component\EventDispatcher\Event;
class ResponseEvent extends Event
{
@@ -136,7 +138,10 @@ the registration of a listener for the ``response`` event::
$response->setContent($response->getContent().'GA CODE');
});
- $framework = new Simplex\Framework($dispatcher, $matcher, $resolver);
+ $controllerResolver = new ControllerResolver();
+ $argumentResolver = new ArgumentResolver();
+
+ $framework = new Simplex\Framework($dispatcher, $matcher, $controllerResolver, $argumentResolver);
$response = $framework->handle($request);
$response->send();
@@ -234,16 +239,16 @@ And do the same with the other listener::
Our front controller should now look like the following::
$dispatcher = new EventDispatcher();
- $dispatcher->addListener('response', array(new Simplex\ContentLengthListener(), 'onResponse'), -255);
- $dispatcher->addListener('response', array(new Simplex\GoogleListener(), 'onResponse'));
+ $dispatcher->addListener('response', [new Simplex\ContentLengthListener(), 'onResponse'], -255);
+ $dispatcher->addListener('response', [new Simplex\GoogleListener(), 'onResponse']);
Even if the code is now nicely wrapped in classes, there is still a slight
issue: the knowledge of the priorities is "hardcoded" in the front controller,
instead of being in the listeners themselves. For each application, you have
to remember to set the appropriate priorities. Moreover, the listener method
names are also exposed here, which means that refactoring our listeners would
-mean changing all the applications that rely on those listeners. Of course,
-there is a solution: use subscribers instead of listeners::
+mean changing all the applications that rely on those listeners. But there is a
+solution: use subscribers instead of listeners::
$dispatcher = new EventDispatcher();
$dispatcher->addSubscriber(new Simplex\ContentLengthListener());
@@ -264,7 +269,7 @@ look at the new version of the ``GoogleListener``::
public static function getSubscribedEvents()
{
- return array('response' => 'onResponse');
+ return ['response' => 'onResponse'];
}
}
@@ -281,7 +286,7 @@ And here is the new version of ``ContentLengthListener``::
public static function getSubscribedEvents()
{
- return array('response' => array('onResponse', -255));
+ return ['response' => ['onResponse', -255]];
}
}
@@ -296,4 +301,4 @@ is not about creating a generic framework, but one that is tailored to your
needs. Stop whenever you see fit, and further evolve the code from there.
.. _`WSGI`: https://www.python.org/dev/peps/pep-0333/#middleware-components-that-play-both-sides
-.. _`Rack`: http://rack.rubyforge.org/
+.. _`Rack`: https://github.com/rack/rack
diff --git a/create_framework/front_controller.rst b/create_framework/front_controller.rst
index f11e8fde69b..39286ba8c16 100644
--- a/create_framework/front_controller.rst
+++ b/create_framework/front_controller.rst
@@ -61,8 +61,8 @@ which name is exposed to the end user via the URL
(``http://127.0.0.1:4321/bye.php``): there is a direct mapping between the PHP
script name and the client URL. This is because the dispatching of the request
is done by the web server directly. It might be a good idea to move this
-dispatching to our code for better flexibility. This can be easily achieved by
-routing all client requests to a single PHP script.
+dispatching to our code for better flexibility. This can be achieved by routing
+all client requests to a single PHP script.
.. tip::
@@ -80,10 +80,10 @@ Such a script might look like the following::
$request = Request::createFromGlobals();
$response = new Response();
- $map = array(
+ $map = [
'/hello' => __DIR__.'/hello.php',
'/bye' => __DIR__.'/bye.php',
- );
+ ];
$path = $request->getPathInfo();
if (isset($map[$path])) {
@@ -153,12 +153,12 @@ web root directory:
Now, configure your web server root directory to point to ``web/`` and all
other files won't be accessible from the client anymore.
-To test your changes in a browser (``http://localhost:4321/hello?name=Fabien``), run
-the PHP built-in server:
+To test your changes in a browser (``http://localhost:4321/hello?name=Fabien``),
+run the :doc:`Symfony Local Web Server `:
.. code-block:: terminal
- $ php -S 127.0.0.1:4321 -t web/ web/front.php
+ $ symfony server:start --port=4321 --passthru=front.php
.. note::
@@ -190,7 +190,7 @@ And the ``hello.php`` script can now be converted to a template::
get('name', 'World') ?>
- Hello
+ Hello
We have the first version of our framework::
@@ -203,10 +203,10 @@ We have the first version of our framework::
$request = Request::createFromGlobals();
$response = new Response();
- $map = array(
+ $map = [
'/hello' => __DIR__.'/../src/pages/hello.php',
'/bye' => __DIR__.'/../src/pages/bye.php',
- );
+ ];
$path = $request->getPathInfo();
if (isset($map[$path])) {
@@ -220,7 +220,7 @@ We have the first version of our framework::
$response->send();
-Adding a new page is a two step process: add an entry in the map and create a
+Adding a new page is a two-step process: add an entry in the map and create a
PHP template in ``src/pages/``. From a template, get the Request data via the
``$request`` variable and tweak the Response headers via the ``$response``
variable.
diff --git a/create_framework/http_foundation.rst b/create_framework/http_foundation.rst
index d54990def79..b86ac80ada5 100644
--- a/create_framework/http_foundation.rst
+++ b/create_framework/http_foundation.rst
@@ -9,10 +9,9 @@ top of the Symfony components is better than creating a framework from scratch.
.. note::
- We won't talk about the obvious and traditional benefits of using a
- framework when working on big applications with more than a few
- developers; the Internet has already plenty of good resources on that
- topic.
+ We won't talk about the traditional benefits of using a framework when
+ working on big applications with more than a few developers; the Internet
+ has already plenty of good resources on that topic.
Even if the "application" we wrote in the previous chapter was simple enough,
it suffers from a few problems::
@@ -52,7 +51,7 @@ As you can see for yourself, the simple code we had written first is not that
simple anymore if we want to avoid PHP warnings/notices and make the code
more secure.
-Beyond security, this code is not even easily testable. Even if there is not
+Beyond security, this code can be complex to test. Even if there is not
much to test, it strikes me that writing unit tests for the simplest possible
snippet of PHP code is not natural and feels ugly. Here is a tentative PHPUnit
unit test for the above code::
@@ -78,7 +77,7 @@ unit test for the above code::
If our application were just slightly bigger, we would have been able to
find even more problems. If you are curious about them, read the
- :doc:`/introduction/from_flat_php_to_symfony2` chapter of the book.
+ :doc:`/introduction/from_flat_php_to_symfony` chapter of the book.
At this point, if you are not convinced that security and testing are indeed
two very good reasons to stop writing code the old way and adopt a framework
@@ -87,9 +86,9 @@ reading this book now and go back to whatever code you were working on before.
.. note::
- Of course, using a framework should give you more than just security and
- testability, but the more important thing to keep in mind is that the
- framework you choose must allow you to write better code faster.
+ Using a framework should give you more than just security and testability,
+ but the more important thing to keep in mind is that the framework you
+ choose must allow you to write better code faster.
Going OOP with the HttpFoundation Component
-------------------------------------------
@@ -126,10 +125,10 @@ containing the new requirement.
.. sidebar:: Class Autoloading
When installing a new dependency, Composer also generates a
- ``vendor/autoload.php`` file that allows any class to be easily
- `autoloaded`_. Without autoloading, you would need to require the file
- where a class is defined before being able to use it. But thanks to
- `PSR-4`_, we can just let Composer and PHP do the hard work for us.
+ ``vendor/autoload.php`` file that allows any class to be `autoloaded`_.
+ Without autoloading, you would need to require the file where a class
+ is defined before being able to use it. But thanks to `PSR-4`_,
+ we can just let Composer and PHP do the hard work for us.
Now, let's rewrite our application by using the ``Request`` and the
``Response`` classes::
@@ -201,7 +200,7 @@ You can also simulate a request::
$request = Request::create('/index.php?name=Fabien');
-With the ``Response`` class, you can easily tweak the response::
+With the ``Response`` class, you can tweak the response::
$response = new Response();
@@ -256,7 +255,7 @@ code in production without a proxy, it becomes trivially easy to abuse your
system. That's not the case with the ``getClientIp()`` method as you must
explicitly trust your reverse proxies by calling ``setTrustedProxies()``::
- Request::setTrustedProxies(array('10.0.0.1'));
+ Request::setTrustedProxies(['10.0.0.1']);
if ($myIp === $request->getClientIp()) {
// the client is a known one, so give it some more privilege
@@ -271,7 +270,7 @@ cases by yourself. Why not using a technology that already works?
.. note::
If you want to learn more about the HttpFoundation component, you can have
- a look at the :namespace:`Symfony\\Component\\HttpFoundation` API or read
+ a look at the ``Symfony\Component\HttpFoundation`` API or read
its dedicated :doc:`documentation `.
Believe or not but we have our first framework. You can stop now if you want.
@@ -285,8 +284,8 @@ the wheel.
I've almost forgot to talk about one added benefit: using the HttpFoundation
component is the start of better interoperability between all frameworks and
-`applications using it`_ (like `Symfony`_, `Drupal 8`_, `phpBB 3`_, `ezPublish
-5`_, `Laravel`_ and `more`_).
+`applications using it`_ (like `Symfony`_, `Drupal 8`_, `phpBB 3`_, `Laravel`_
+and `ezPublish 5`_, and `more`_).
.. _`Twig`: https://twig.symfony.com/
.. _`HTTP specification`: https://tools.ietf.org/wg/httpbis/
@@ -297,8 +296,6 @@ component is the start of better interoperability between all frameworks and
.. _`phpBB 3`: https://www.phpbb.com/
.. _`ezPublish 5`: https://ez.no/
.. _`Laravel`: https://laravel.com/
-.. _`Midgard CMS`: http://www.midgard-project.org/
-.. _`Zikula`: https://zikula.org/
.. _`autoloaded`: https://php.net/autoload
.. _`PSR-4`: https://www.php-fig.org/psr/psr-4/
.. _`more`: https://symfony.com/components/HttpFoundation
diff --git a/create_framework/http_kernel_controller_resolver.rst b/create_framework/http_kernel_controller_resolver.rst
index 8c0e5a041cb..20c7e6ff399 100644
--- a/create_framework/http_kernel_controller_resolver.rst
+++ b/create_framework/http_kernel_controller_resolver.rst
@@ -22,13 +22,13 @@ class::
Update the route definition accordingly::
- $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', array(
+ $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', [
'year' => null,
- '_controller' => array(new LeapYearController(), 'indexAction'),
- )));
+ '_controller' => [new LeapYearController(), 'indexAction'],
+ ]));
The move is pretty straightforward and makes a lot of sense as soon as you
-create more pages but you might have noticed a non-desirable side-effect...
+create more pages but you might have noticed a non-desirable side effect...
The ``LeapYearController`` class is *always* instantiated, even if the
requested URL does not match the ``leap_year`` route. This is bad for one main
reason: performance wise, all controllers for all routes must now be
@@ -43,10 +43,10 @@ component:
$ composer require symfony/http-kernel
-The HttpKernel component has many interesting features, but the one we need
-right now is the *controller resolver*. A controller resolver knows how to
-determine the controller to execute and the arguments to pass to it, based on
-a Request object. All controller resolvers implement the following interface::
+The HttpKernel component has many interesting features, but the ones we need
+right now are the *controller resolver* and *argument resolver*. A controller resolver knows how to
+determine the controller to execute and the argument resolver determines the arguments to pass to it,
+based on a Request object. All controller resolvers implement the following interface::
namespace Symfony\Component\HttpKernel\Controller;
@@ -58,26 +58,35 @@ a Request object. All controller resolvers implement the following interface::
function getArguments(Request $request, $controller);
}
+.. caution::
+
+ The ``getArguments()`` method is deprecated as of Symfony 3.1. and will be
+ removed in 4.0. You can use the
+ :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver` which
+ uses the :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolverInterface`
+ instead.
+
The ``getController()`` method relies on the same convention as the one we
have defined earlier: the ``_controller`` request attribute must contain the
controller associated with the Request. Besides the built-in PHP callbacks,
``getController()`` also supports strings composed of a class name followed by
two colons and a method name as a valid callback, like 'class::method'::
- $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', array(
+ $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', [
'year' => null,
'_controller' => 'LeapYearController::indexAction',
- )));
+ ]));
To make this code work, modify the framework code to use the controller
resolver from HttpKernel::
use Symfony\Component\HttpKernel;
- $resolver = new HttpKernel\Controller\ControllerResolver();
+ $controllerResolver = new HttpKernel\Controller\ControllerResolver();
+ $argumentResolver = new HttpKernel\Controller\ArgumentResolver();
- $controller = $resolver->getController($request);
- $arguments = $resolver->getArguments($request, $controller);
+ $controller = $controllerResolver->getController($request);
+ $arguments = $argumentResolver->getArguments($request, $controller);
$response = call_user_func_array($controller, $arguments);
@@ -133,21 +142,19 @@ Let's just inject the ``$year`` request attribute for our controller::
}
}
-The controller resolver also takes care of validating the controller callable
-and its arguments. In case of a problem, it throws an exception with a nice
-message explaining the problem (the controller class does not exist, the
-method is not defined, an argument has no matching attribute, ...).
+The resolvers also take care of validating the controller callable and its
+arguments. In case of a problem, it throws an exception with a nice message
+explaining the problem (the controller class does not exist, the method is not
+defined, an argument has no matching attribute, ...).
.. note::
- With the great flexibility of the default controller resolver, you might
- wonder why someone would want to create another one (why would there be an
- interface if not?). Two examples: in Symfony, ``getController()`` is
- enhanced to support
- :doc:`controllers as services `; and in
- `FrameworkExtraBundle`_, ``getArguments()`` is enhanced to support
- parameter converters, where request attributes are converted to objects
- automatically.
+ With the great flexibility of the default controller resolver and argument
+ resolver, you might wonder why someone would want to create another one
+ (why would there be an interface if not?). Two examples: in Symfony,
+ ``getController()`` is enhanced to support :doc:`controllers as services `;
+ and ``getArguments()`` provides an extension point to alter or enhance
+ the resolving of arguments.
Let's conclude with the new version of our framework::
@@ -156,8 +163,8 @@ Let's conclude with the new version of our framework::
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
- use Symfony\Component\Routing;
use Symfony\Component\HttpKernel;
+ use Symfony\Component\Routing;
function render_template(Request $request)
{
@@ -174,13 +181,15 @@ Let's conclude with the new version of our framework::
$context = new Routing\RequestContext();
$context->fromRequest($request);
$matcher = new Routing\Matcher\UrlMatcher($routes, $context);
- $resolver = new HttpKernel\Controller\ControllerResolver();
+
+ $controllerResolver = new HttpKernel\Controller\ControllerResolver();
+ $argumentResolver = new HttpKernel\Controller\ArgumentResolver();
try {
$request->attributes->add($matcher->match($request->getPathInfo()));
- $controller = $resolver->getController($request);
- $arguments = $resolver->getArguments($request, $controller);
+ $controller = $controllerResolver->getController($request);
+ $arguments = $argumentResolver->getArguments($request, $controller);
$response = call_user_func_array($controller, $arguments);
} catch (Routing\Exception\ResourceNotFoundException $exception) {
@@ -192,7 +201,6 @@ Let's conclude with the new version of our framework::
$response->send();
Think about it once more: our framework is more robust and more flexible than
-ever and it still has less than 40 lines of code.
+ever and it still has less than 50 lines of code.
.. _`reflection`: https://php.net/reflection
-.. _`FrameworkExtraBundle`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
diff --git a/create_framework/http_kernel_httpkernel_class.rst b/create_framework/http_kernel_httpkernel_class.rst
index 05d289a619a..056ec134802 100644
--- a/create_framework/http_kernel_httpkernel_class.rst
+++ b/create_framework/http_kernel_httpkernel_class.rst
@@ -4,7 +4,7 @@ The HttpKernel Component: The HttpKernel Class
If you were to use our framework right now, you would probably have to add
support for custom error messages. We do have 404 and 500 error support but
the responses are hardcoded in the framework itself. Making them customizable
-is easy enough though: dispatch a new event and listen to it. Doing it right
+is straightforward though: dispatch a new event and listen to it. Doing it right
means that the listener has to call a regular controller. But what if the
error controller throws an exception? You will end up in an infinite loop.
There should be an easier way, right?
@@ -36,24 +36,27 @@ And the new front controller::
// example.com/web/front.php
require_once __DIR__.'/../vendor/autoload.php';
+ use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\HttpFoundation\Request;
+ use Symfony\Component\HttpFoundation\RequestStack;
use Symfony\Component\HttpFoundation\Response;
- use Symfony\Component\Routing;
use Symfony\Component\HttpKernel;
- use Symfony\Component\EventDispatcher\EventDispatcher;
- use Symfony\Component\HttpFoundation\RequestStack;
+ use Symfony\Component\Routing;
$request = Request::createFromGlobals();
+ $requestStack = new RequestStack();
$routes = include __DIR__.'/../src/app.php';
$context = new Routing\RequestContext();
$matcher = new Routing\Matcher\UrlMatcher($routes, $context);
- $resolver = new HttpKernel\Controller\ControllerResolver();
+
+ $controllerResolver = new HttpKernel\Controller\ControllerResolver();
+ $argumentResolver = new HttpKernel\Controller\ArgumentResolver();
$dispatcher = new EventDispatcher();
- $dispatcher->addSubscriber(new HttpKernel\EventListener\RouterListener($matcher, new RequestStack()));
+ $dispatcher->addSubscriber(new HttpKernel\EventListener\RouterListener($matcher, $requestStack));
- $framework = new Simplex\Framework($dispatcher, $resolver);
+ $framework = new Simplex\Framework($dispatcher, $controllerResolver, $requestStack, $argumentResolver);
$response = $framework->handle($request);
$response->send();
@@ -88,8 +91,8 @@ The error controller reads as follows::
// example.com/src/Calendar/Controller/ErrorController.php
namespace Calendar\Controller;
- use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Debug\Exception\FlattenException;
+ use Symfony\Component\HttpFoundation\Response;
class ErrorController
{
@@ -101,8 +104,8 @@ The error controller reads as follows::
}
}
-Voilà! Clean and customizable error management without efforts. And of course,
-if your controller throws an exception, HttpKernel will handle it nicely.
+*Voilà!* Clean and customizable error management without efforts. And if your
+controller throws an exception, HttpKernel will handle it nicely.
In chapter two, we talked about the ``Response::prepare()`` method, which
ensures that a Response is compliant with the HTTP specification. It is
@@ -111,9 +114,8 @@ client; that's what the ``ResponseListener`` does::
$dispatcher->addSubscriber(new HttpKernel\EventListener\ResponseListener('UTF-8'));
-This one was easy too! Let's take another one: do you want out of the box
-support for streamed responses? Just subscribe to
-``StreamedResponseListener``::
+If you want out of the box support for streamed responses, subscribe
+to ``StreamedResponseListener``::
$dispatcher->addSubscriber(new HttpKernel\EventListener\StreamedResponseListener());
@@ -153,7 +155,6 @@ only if needed::
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
- use Symfony\Component\HttpKernel\KernelEvents;
class StringResponseListener implements EventSubscriberInterface
{
@@ -168,7 +169,7 @@ only if needed::
public static function getSubscribedEvents()
{
- return array(KernelEvents::VIEW => 'onView');
+ return ['kernel.view' => 'onView'];
}
}
diff --git a/create_framework/http_kernel_httpkernelinterface.rst b/create_framework/http_kernel_httpkernelinterface.rst
index 310f4619a1a..3ec76549b2e 100644
--- a/create_framework/http_kernel_httpkernelinterface.rst
+++ b/create_framework/http_kernel_httpkernelinterface.rst
@@ -46,7 +46,7 @@ Update your framework so that it implements this interface::
}
}
-Even if this change looks trivial, it brings us a lot! Let's talk about one of
+Even if this change looks not too complex, it brings us a lot! Let's talk about one of
the most impressive one: transparent :doc:`HTTP caching ` support.
The ``HttpCache`` class implements a fully-featured reverse proxy, written in
@@ -54,7 +54,11 @@ PHP; it implements ``HttpKernelInterface`` and wraps another
``HttpKernelInterface`` instance::
// example.com/web/front.php
- $framework = new Simplex\Framework($dispatcher, $matcher, $resolver);
+
+ // ...
+ use Symfony\Component\HttpKernel;
+
+ $framework = new Simplex\Framework($dispatcher, $matcher, $controllerResolver, $argumentResolver);
$framework = new HttpKernel\HttpCache\HttpCache(
$framework,
new HttpKernel\HttpCache\Store(__DIR__.'/../cache')
@@ -87,11 +91,10 @@ to cache a response for 10 seconds, use the ``Response::setTtl()`` method::
.. tip::
- If, like me, you are running your framework from the command line by
- simulating requests (``Request::create('/is_leap_year/2012')``), you can
- easily debug Response instances by dumping their string representation
- (``echo $response;``) as it displays all headers as well as the response
- content.
+ If you are running your framework from the command line by simulating
+ requests (``Request::create('/is_leap_year/2012')``), you can debug
+ Response instances by dumping their string representation (``echo $response;``)
+ as it displays all headers as well as the response content.
To validate that it works correctly, add a random number to the response
content and check that the number only changes every 10 seconds::
@@ -111,18 +114,18 @@ comfortable with these concepts, read the `HTTP caching`_ chapter of the
Symfony documentation.
The Response class contains many other methods that let you configure the
-HTTP cache very easily. One of the most powerful is ``setCache()`` as it
-abstracts the most frequently used caching strategies into one simple array::
+HTTP cache. One of the most powerful is ``setCache()`` as it abstracts the
+most frequently used caching strategies into one array::
$date = date_create_from_format('Y-m-d H:i:s', '2005-10-15 10:00:00');
- $response->setCache(array(
+ $response->setCache([
'public' => true,
'etag' => 'abcde',
'last_modified' => $date,
'max_age' => 10,
's_maxage' => 10,
- ));
+ ]);
// it is equivalent to the following code
$response->setPublic();
@@ -132,8 +135,8 @@ abstracts the most frequently used caching strategies into one simple array::
$response->setSharedMaxAge(10);
When using the validation model, the ``isNotModified()`` method allows you to
-easily cut on the response time by short-circuiting the response generation as
-early as possible::
+cut on the response time by short-circuiting the response generation as early
+as possible::
$response->setETag('whatever_you_compute_as_an_etag');
@@ -155,7 +158,7 @@ page as being the content of a sub-request call:
This is the content of your page
- Is 2012 a leap year?
+ Is 2012 a leap year?
Some other content
@@ -183,7 +186,7 @@ ease debugging, you can enable the debug mode::
$framework,
new HttpKernel\HttpCache\Store(__DIR__.'/../cache'),
new HttpKernel\HttpCache\Esi(),
- array('debug' => true)
+ ['debug' => true]
);
The debug mode adds a ``X-Symfony-Cache`` header to each response that
diff --git a/create_framework/introduction.rst b/create_framework/introduction.rst
index e761ae5de13..11948890bba 100644
--- a/create_framework/introduction.rst
+++ b/create_framework/introduction.rst
@@ -38,10 +38,9 @@ you can use as is or as a start for your very own. It will start with a simple
framework and more features will be added with time. Eventually, you will have
a fully-featured full-stack web framework.
-And of course, each step will be the occasion to learn more about some of the
-Symfony Components.
+Each step will be the occasion to learn more about some of the Symfony Components.
-Many modern web frameworks advertize themselves as being MVC frameworks. This
+Many modern web frameworks advertise themselves as being MVC frameworks. This
tutorial won't talk about the MVC pattern, as the Symfony Components are able to
create any type of frameworks, not just the ones that follow the MVC
architecture. Anyway, if you have a look at the MVC semantics, this book is
@@ -62,8 +61,8 @@ Before You Start
Reading about how to create a framework is not enough. You will have to follow
along and actually type all the examples included in this tutorial. For that,
-you need a recent version of PHP (5.3.9 or later is good enough), a web server
-(like Apache, NGinx or PHP's built-in web server), a good knowledge of PHP and
+you need a recent version of PHP (5.5.9 or later is good enough), a web server
+(like Apache, nginx or PHP's built-in web server), a good knowledge of PHP and
an understanding of Object Oriented programming.
Ready to go? Read on!
@@ -87,7 +86,7 @@ Dependency Management
To install the Symfony Components that you need for your framework, you are going
to use `Composer`_, a project dependency manager for PHP. If you don't have it
-yet, :doc:`download and install Composer ` now.
+yet, `download and install Composer`_ now.
Our Project
-----------
@@ -101,17 +100,17 @@ start with the simplest web application we can think of in PHP::
printf('Hello %s', $name);
-If you have PHP 5.4, you can use the PHP built-in server to test this great
-application in a browser (``http://localhost:4321/index.php?name=Fabien``):
+You can use the :doc:`Symfony Local Web Server ` to test
+this great application in a browser
+(``http://localhost:8000/index.php?name=Fabien``):
.. code-block:: terminal
- $ php -S 127.0.0.1:4321
-
-Otherwise, you can always use your own server (Apache, Nginx, etc.).
+ $ symfony server:start
In the :doc:`next chapter `, we are going to
introduce the HttpFoundation Component and see what it brings us.
.. _`Symfony`: https://symfony.com/
.. _`Composer`: http://packagist.org/about-composer
+.. _`download and install Composer`: https://getcomposer.org/download/
diff --git a/create_framework/routing.rst b/create_framework/routing.rst
index deaf9a02420..717ed1068fb 100644
--- a/create_framework/routing.rst
+++ b/create_framework/routing.rst
@@ -12,10 +12,10 @@ framework just a little to make templates even more readable::
$request = Request::createFromGlobals();
- $map = array(
+ $map = [
'/hello' => 'hello',
'/bye' => 'bye',
- );
+ ];
$path = $request->getPathInfo();
if (isset($map[$path])) {
@@ -33,7 +33,7 @@ As we now extract the request query parameters, simplify the ``hello.php``
template as follows::
- Hello
+ Hello
Now, we are in good shape to add new features.
@@ -61,27 +61,27 @@ one for the simple ``/bye`` one::
use Symfony\Component\Routing\Route;
- $routes->add('hello', new Route('/hello/{name}', array('name' => 'World')));
+ $routes->add('hello', new Route('/hello/{name}', ['name' => 'World']));
$routes->add('bye', new Route('/bye'));
Each entry in the collection is defined by a name (``hello``) and a ``Route``
instance, which is defined by a route pattern (``/hello/{name}``) and an array
-of default values for route attributes (``array('name' => 'World')``).
+of default values for route attributes (``['name' => 'World']``).
.. note::
Read the
:doc:`Routing component documentation ` to
learn more about its many features like URL generation, attribute
- requirements, HTTP method enforcements, loaders for YAML or XML files,
+ requirements, HTTP method enforcement, loaders for YAML or XML files,
dumpers to PHP or Apache rewrite rules for enhanced performance and much
more.
Based on the information stored in the ``RouteCollection`` instance, a
``UrlMatcher`` instance can match URL paths::
- use Symfony\Component\Routing\RequestContext;
use Symfony\Component\Routing\Matcher\UrlMatcher;
+ use Symfony\Component\Routing\RequestContext;
$context = new RequestContext();
$context->fromRequest($request);
@@ -93,27 +93,27 @@ The ``match()`` method takes a request path and returns an array of attributes
(notice that the matched route is automatically stored under the special
``_route`` attribute)::
- print_r($matcher->match('/bye'));
- /* Gives:
- array (
- '_route' => 'bye',
- );
+ $matcher->match('/bye');
+ /* Result:
+ [
+ '_route' => 'bye',
+ ];
*/
- print_r($matcher->match('/hello/Fabien'));
- /* Gives:
- array (
- 'name' => 'Fabien',
- '_route' => 'hello',
- );
+ $matcher->match('/hello/Fabien');
+ /* Result:
+ [
+ 'name' => 'Fabien',
+ '_route' => 'hello',
+ ];
*/
- print_r($matcher->match('/hello'));
- /* Gives:
- array (
- 'name' => 'World',
- '_route' => 'hello',
- );
+ $matcher->match('/hello');
+ /* Result:
+ [
+ 'name' => 'World',
+ '_route' => 'hello',
+ ];
*/
.. note::
@@ -165,23 +165,23 @@ There are a few new things in the code:
* Request attributes are extracted to keep our templates simple::
-
- Hello
+ // example.com/src/pages/hello.php
+ Hello
* Route configuration has been moved to its own file::
- // example.com/src/app.php
- use Symfony\Component\Routing;
+ // example.com/src/app.php
+ use Symfony\Component\Routing;
- $routes = new Routing\RouteCollection();
- $routes->add('hello', new Routing\Route('/hello/{name}', array('name' => 'World')));
- $routes->add('bye', new Routing\Route('/bye'));
+ $routes = new Routing\RouteCollection();
+ $routes->add('hello', new Routing\Route('/hello/{name}', ['name' => 'World']));
+ $routes->add('bye', new Routing\Route('/bye'));
- return $routes;
+ return $routes;
- We now have a clear separation between the configuration (everything
- specific to our application in ``app.php``) and the framework (the generic
- code that powers our application in ``front.php``).
+We now have a clear separation between the configuration (everything
+specific to our application in ``app.php``) and the framework (the generic
+code that powers our application in ``front.php``).
With less than 30 lines of code, we have a new framework, more powerful and
more flexible than the previous one. Enjoy!
@@ -189,13 +189,13 @@ more flexible than the previous one. Enjoy!
Using the Routing component has one big additional benefit: the ability to
generate URLs based on Route definitions. When using both URL matching and URL
generation in your code, changing the URL patterns should have no other
-impact. Want to know how to use the generator? Insanely easy::
+impact. You can use the generator this way::
use Symfony\Component\Routing;
$generator = new Routing\Generator\UrlGenerator($routes, $context);
- echo $generator->generate('hello', array('name' => 'Fabien'));
+ echo $generator->generate('hello', ['name' => 'Fabien']);
// outputs /hello/Fabien
The code should be self-explanatory; and thanks to the context, you can even
@@ -205,7 +205,7 @@ generate absolute URLs::
echo $generator->generate(
'hello',
- array('name' => 'Fabien'),
+ ['name' => 'Fabien'],
UrlGeneratorInterface::ABSOLUTE_URL
);
// outputs something like http://example.com/somewhere/hello/Fabien
diff --git a/create_framework/separation_of_concerns.rst b/create_framework/separation_of_concerns.rst
index a3c1265697e..3af0e98dd46 100644
--- a/create_framework/separation_of_concerns.rst
+++ b/create_framework/separation_of_concerns.rst
@@ -2,7 +2,7 @@ The Separation of Concerns
==========================
One down-side of our framework right now is that we need to copy and paste the
-code in ``front.php`` each time we create a new website. 40 lines of code is
+code in ``front.php`` each time we create a new website. 60 lines of code is
not that much, but it would be nice if we could wrap this code into a proper
class. It would bring us better *reusability* and easier testing to name just
a few benefits.
@@ -13,26 +13,29 @@ simple principle: the logic is about creating the Response associated with a
Request.
Let's create our very own namespace for our framework: ``Simplex``. Move the
-request handling logic into its own ``Simplex\\Framework`` class::
+request handling logic into its own ``Simplex\Framework`` class::
// example.com/src/Simplex/Framework.php
namespace Simplex;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
- use Symfony\Component\Routing\Matcher\UrlMatcher;
- use Symfony\Component\Routing\Exception\ResourceNotFoundException;
+ use Symfony\Component\HttpKernel\Controller\ArgumentResolver;
use Symfony\Component\HttpKernel\Controller\ControllerResolver;
+ use Symfony\Component\Routing\Exception\ResourceNotFoundException;
+ use Symfony\Component\Routing\Matcher\UrlMatcher;
class Framework
{
protected $matcher;
- protected $resolver;
+ protected $controllerResolver;
+ protected $argumentResolver;
- public function __construct(UrlMatcher $matcher, ControllerResolver $resolver)
+ public function __construct(UrlMatcher $matcher, ControllerResolver $controllerResolver, ArgumentResolver $argumentResolver)
{
$this->matcher = $matcher;
- $this->resolver = $resolver;
+ $this->controllerResolver = $controllerResolver;
+ $this->argumentResolver = $argumentResolver;
}
public function handle(Request $request)
@@ -42,8 +45,8 @@ request handling logic into its own ``Simplex\\Framework`` class::
try {
$request->attributes->add($this->matcher->match($request->getPathInfo()));
- $controller = $this->resolver->getController($request);
- $arguments = $this->resolver->getArguments($request, $controller);
+ $controller = $this->controllerResolver->getController($request);
+ $arguments = $this->argumentResolver->getArguments($request, $controller);
return call_user_func_array($controller, $arguments);
} catch (ResourceNotFoundException $exception) {
@@ -64,9 +67,11 @@ And update ``example.com/web/front.php`` accordingly::
$context = new Routing\RequestContext();
$matcher = new Routing\Matcher\UrlMatcher($routes, $context);
- $resolver = new HttpKernel\Controller\ControllerResolver();
- $framework = new Simplex\Framework($matcher, $resolver);
+ $controllerResolver = new ControllerResolver();
+ $argumentResolver = new ArgumentResolver();
+
+ $framework = new Simplex\Framework($matcher, $controllerResolver, $argumentResolver);
$response = $framework->handle($request);
$response->send();
@@ -95,9 +100,9 @@ Move the controller to ``Calendar\Controller\LeapYearController``::
// example.com/src/Calendar/Controller/LeapYearController.php
namespace Calendar\Controller;
+ use Calendar\Model\LeapYear;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
- use Calendar\Model\LeapYear;
class LeapYearController
{
@@ -131,10 +136,10 @@ And move the ``is_leap_year()`` function to its own class too::
Don't forget to update the ``example.com/src/app.php`` file accordingly::
- $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', array(
+ $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', [
'year' => null,
'_controller' => 'Calendar\Controller\LeapYearController::indexAction',
- )));
+ ]));
To sum up, here is the new file layout:
@@ -158,7 +163,7 @@ To sum up, here is the new file layout:
└── front.php
That's it! Our application has now four different layers and each of them has
-a well defined goal:
+a well-defined goal:
* ``web/front.php``: The front controller; the only exposed PHP code that
makes the interface with the client (it gets the Request and sends the
@@ -166,7 +171,7 @@ a well defined goal:
our application;
* ``src/Simplex``: The reusable framework code that abstracts the handling of
- incoming Requests (by the way, it makes your controllers/templates easily
+ incoming Requests (by the way, it makes your controllers/templates better
testable -- more about that later on);
* ``src/Calendar``: Our application specific code (the controllers and the
diff --git a/create_framework/templating.rst b/create_framework/templating.rst
index a00f5b352fb..30dbf992110 100644
--- a/create_framework/templating.rst
+++ b/create_framework/templating.rst
@@ -55,10 +55,10 @@ controller... your choice.
As a convention, for each route, the associated controller is configured via
the ``_controller`` route attribute::
- $routes->add('hello', new Routing\Route('/hello/{name}', array(
+ $routes->add('hello', new Routing\Route('/hello/{name}', [
'name' => 'World',
'_controller' => 'render_template',
- )));
+ ]));
try {
$request->attributes->add($matcher->match($request->getPathInfo()));
@@ -69,20 +69,20 @@ the ``_controller`` route attribute::
$response = new Response('An error occurred', 500);
}
-A route can now be associated with any controller and of course, within a
-controller, you can still use the ``render_template()`` to render a template::
+A route can now be associated with any controller and, within a controller, you
+can still use the ``render_template()`` to render a template::
- $routes->add('hello', new Routing\Route('/hello/{name}', array(
+ $routes->add('hello', new Routing\Route('/hello/{name}', [
'name' => 'World',
'_controller' => function ($request) {
return render_template($request);
}
- )));
+ ]));
This is rather flexible as you can change the Response object afterwards and
you can even pass additional arguments to the template::
- $routes->add('hello', new Routing\Route('/hello/{name}', array(
+ $routes->add('hello', new Routing\Route('/hello/{name}', [
'name' => 'World',
'_controller' => function ($request) {
// $foo will be available in the template
@@ -95,7 +95,7 @@ you can even pass additional arguments to the template::
return $response;
}
- )));
+ ]));
Here is the updated and improved version of our framework::
@@ -142,8 +142,8 @@ framework does not need to be modified in any way, just create a new
``app.php`` file::
// example.com/src/app.php
- use Symfony\Component\Routing;
use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Routing;
function is_leap_year($year = null) {
if (null === $year) {
@@ -154,7 +154,7 @@ framework does not need to be modified in any way, just create a new
}
$routes = new Routing\RouteCollection();
- $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', array(
+ $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', [
'year' => null,
'_controller' => function ($request) {
if (is_leap_year($request->attributes->get('year'))) {
@@ -163,7 +163,7 @@ framework does not need to be modified in any way, just create a new
return new Response('Nope, this is not a leap year.');
}
- )));
+ ]));
return $routes;
diff --git a/create_framework/unit_testing.rst b/create_framework/unit_testing.rst
index 9848cc93f65..ca406e1365f 100644
--- a/create_framework/unit_testing.rst
+++ b/create_framework/unit_testing.rst
@@ -16,7 +16,7 @@ using `PHPUnit`_. Create a PHPUnit configuration file in
matcher = $matcher;
- $this->resolver = $resolver;
+ $this->controllerResolver = $resolver;
+ $this->argumentResolver = $argumentResolver;
}
// ...
@@ -75,6 +78,7 @@ We are now ready to write our first test::
use PHPUnit\Framework\TestCase;
use Simplex\Framework;
use Symfony\Component\HttpFoundation\Request;
+ use Symfony\Component\HttpKernel\Controller\ArgumentResolverInterface;
use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
use Symfony\Component\Routing;
use Symfony\Component\Routing\Exception\ResourceNotFoundException;
@@ -106,9 +110,10 @@ We are now ready to write our first test::
->method('getContext')
->will($this->returnValue($this->createMock(Routing\RequestContext::class)))
;
- $resolver = $this->createMock(ControllerResolverInterface::class);
+ $controllerResolver = $this->createMock(ControllerResolverInterface::class);
+ $argumentResolver = $this->createMock(ArgumentResolverInterface::class);
- return new Framework($matcher, $resolver);
+ return new Framework($matcher, $controllerResolver, $argumentResolver);
}
}
@@ -131,7 +136,7 @@ Executing this test is as simple as running ``phpunit`` from the
After the test ran, you should see a green bar. If not, you have a bug
either in the test or in the framework code!
-Adding a unit test for any exception thrown in a controller is just as easy::
+Adding a unit test for any exception thrown in a controller::
public function testErrorHandling()
{
@@ -146,6 +151,7 @@ Last, but not the least, let's write a test for when we actually have a proper
Response::
use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\HttpKernel\Controller\ArgumentResolver;
use Symfony\Component\HttpKernel\Controller\ControllerResolver;
// ...
@@ -158,22 +164,23 @@ Response::
$matcher
->expects($this->once())
->method('match')
- ->will($this->returnValue(array(
+ ->will($this->returnValue([
'_route' => 'foo',
'name' => 'Fabien',
'_controller' => function ($name) {
return new Response('Hello '.$name);
}
- )))
+ ]))
;
$matcher
->expects($this->once())
->method('getContext')
->will($this->returnValue($this->createMock(Routing\RequestContext::class)))
;
- $resolver = new ControllerResolver();
+ $controllerResolver = new ControllerResolver();
+ $argumentResolver = new ArgumentResolver();
- $framework = new Framework($matcher, $resolver);
+ $framework = new Framework($matcher, $controllerResolver, $argumentResolver);
$response = $framework->handle(new Request());
diff --git a/debug/debugging.rst b/debug/debugging.rst
index 246da9c3380..c345ebf8acc 100644
--- a/debug/debugging.rst
+++ b/debug/debugging.rst
@@ -30,22 +30,21 @@ The ``app_dev.php`` front controller reads as follows by default::
// ...
- $loader = require_once __DIR__.'/../app/bootstrap.php.cache';
- require_once __DIR__.'/../app/AppKernel.php';
+ $loader = require __DIR__.'/../app/autoload.php';
+ Debug::enable();
$kernel = new AppKernel('dev', true);
$kernel->loadClassCache();
$request = Request::createFromGlobals();
+ // ...
To make your debugger happier, disable the loading of all PHP class caches
-by removing the call to ``loadClassCache()`` and by replacing the require
-statements like below::
+by removing the call to ``loadClassCache()``::
// ...
- // $loader = require_once __DIR__.'/../app/bootstrap.php.cache';
$loader = require_once __DIR__.'/../app/autoload.php';
- require_once __DIR__.'/../app/AppKernel.php';
+ Debug::enable();
$kernel = new AppKernel('dev', true);
// $kernel->loadClassCache();
@@ -62,6 +61,12 @@ cache files, or you can change the extension used by Symfony for these files::
$kernel->loadClassCache('classes', '.php.cache');
+.. deprecated:: 3.3
+
+ The ``loadClassCache()`` was deprecated in Symfony 3.3 and removed in
+ Symfony 4.0. No alternative is provided because this feature is useless
+ when using PHP 7 or higher.
+
Useful Debugging Commands
-------------------------
@@ -69,6 +74,10 @@ When developing a large application, it can be hard to keep track of all the
different services, routes and translations. Luckily, Symfony has some commands
that can help you visualize and find the information.
+``about``
+ Shows information about the current project, such as the Symfony version,
+ the Kernel and PHP.
+
``debug:container``
Displays information about the contents of the Symfony container for all public
services. To find only those matching a name, append the name as an argument.
@@ -76,6 +85,9 @@ that can help you visualize and find the information.
``debug:config``
Shows all configured bundles, their class and their alias.
+``debug:form``
+ Displays information about form types and their options.
+
``debug:event-dispatcher``
Displays information about all the registered listeners in the event dispatcher.
diff --git a/deployment.rst b/deployment.rst
index 0c3c19f4a37..6a92e4df9b1 100644
--- a/deployment.rst
+++ b/deployment.rst
@@ -79,7 +79,7 @@ There are also tools to help ease the pain of deployment. Some of them have been
specifically tailored to the requirements of Symfony.
`EasyDeployBundle`_
- A Symfony bundle that adds easy deploy tools to your application.
+ A Symfony bundle that adds deploy tools to your application.
`Deployer`_
This is another native PHP rewrite of Capistrano, with some ready recipes for
@@ -101,13 +101,6 @@ specifically tailored to the requirements of Symfony.
`Symfony plugin`_ is a plugin to ease Symfony related tasks, inspired by `Capifony`_
(which works only with Capistrano 2).
-`sf2debpkg`_
- Helps you build a native Debian package for your Symfony project.
-
-Basic scripting
- You can of course use shell, `Ant`_ or any other build tool to script
- the deploying of your project.
-
Common Post-Deployment Tasks
----------------------------
@@ -117,11 +110,12 @@ you'll need to do:
A) Check Requirements
~~~~~~~~~~~~~~~~~~~~~
-Check if your server meets the requirements by running:
+Check if your server meets the requirements by running the following command
+provided by the ``symfony`` binary created when `installing Symfony`_:
.. code-block:: terminal
- $ php app/check.php
+ $ symfony check:requirements
.. _b-configure-your-app-config-parameters-yml-file:
@@ -138,6 +132,11 @@ If your application uses environment variables instead of these parameters, you
must define those env vars in your production server using the tools provided by
your hosting service.
+At the very least you need to define the ``SYMFONY_ENV=prod`` (or
+``APP_ENV=prod`` if you're using :doc:`Symfony Flex `) to run the
+application in ``prod`` mode, but depending on your application you may need to
+define other env vars too.
+
C) Install/Update your Vendors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -159,28 +158,20 @@ as you normally do:
.. caution::
If you get a "class not found" error during this step, you may need to
- run ``export SYMFONY_ENV=prod`` before running this command so that
- the ``post-install-cmd`` scripts run in the ``prod`` environment.
+ run ``export SYMFONY_ENV=prod`` (or ``export APP_ENV=prod`` if you're
+ using :doc:`Symfony Flex `) before running this command so
+ that the ``post-install-cmd`` scripts run in the ``prod`` environment.
D) Clear your Symfony Cache
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Make sure you clear (and warm-up) your Symfony cache:
-
-.. code-block:: terminal
-
- $ php app/console cache:clear --env=prod --no-debug
-
-E) Dump your Assetic Assets
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you're using Assetic, you'll also want to dump your assets:
+Make sure you clear and warm-up your Symfony cache:
.. code-block:: terminal
- $ php app/console assetic:dump --env=prod --no-debug
+ $ php bin/console cache:clear --env=prod --no-debug
-F) Other Things!
+E) Other Things!
~~~~~~~~~~~~~~~~
There may be lots of other things that you need to do, depending on your
@@ -188,8 +179,8 @@ setup:
* Running any database migrations
* Clearing your APC cache
-* Running ``assets:install`` (already taken care of in ``composer install``)
* Add/edit CRON jobs
+* :ref:`Building and minifying your assets ` with Webpack Encore
* Pushing assets to a CDN
* ...
@@ -209,16 +200,44 @@ Don't forget that deploying your application also involves updating any dependen
(typically via Composer), migrating your database, clearing your cache and
other potential things like pushing assets to a CDN (see `Common Post-Deployment Tasks`_).
-.. _`Git Tagging`: https://git-scm.com/book/en/v2/Git-Basics-Tagging
+Troubleshooting
+---------------
+
+Deployments not Using the ``composer.json`` File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony applications provide a ``kernel.project_dir`` parameter and a related
+:method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method.
+You can use this method to perform operations with file paths relative to your
+project's root directory. The logic to find that project root directory is based
+on the location of the main ``composer.json`` file.
+
+If your deployment method doesn't use Composer, you may have removed the
+``composer.json`` file and the application won't work on the production server.
+The solution is to override the ``getProjectDir()`` method in the application
+kernel and return your project's root directory::
+
+ // app/AppKernel.php
+ // ...
+ class AppKernel extends Kernel
+ {
+ // ...
+
+ public function getProjectDir()
+ {
+ return dirname(__DIR__);
+ }
+ }
+
.. _`Capifony`: https://github.com/everzet/capifony
.. _`Capistrano`: http://capistranorb.com/
-.. _`sf2debpkg`: https://github.com/liip/sf2debpkg
.. _`Fabric`: http://www.fabfile.org/
.. _`Ansistrano`: https://ansistrano.com/
.. _`Magallanes`: https://github.com/andres-montanez/Magallanes
-.. _`Ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant
.. _`Memcached`: http://memcached.org/
.. _`Redis`: http://redis.io/
.. _`Symfony plugin`: https://github.com/capistrano/symfony/
.. _`Deployer`: http://deployer.org/
+.. _`Git Tagging`: https://git-scm.com/book/en/v2/Git-Basics-Tagging
.. _`EasyDeployBundle`: https://github.com/EasyCorp/easy-deploy-bundle
+.. _`installing Symfony`: https://symfony.com/download
diff --git a/deployment/azure-website.rst b/deployment/azure-website.rst
index 385ab888363..71c7cd288a1 100644
--- a/deployment/azure-website.rst
+++ b/deployment/azure-website.rst
@@ -65,7 +65,7 @@ application code to the Git repository.
:alt: Configure Azure Website credentials
Congratulations! Your Azure Website is now up and running. You can check
-it by browsing to the Website url you configured in the first step. You should
+it by browsing to the website URL you configured in the first step. You should
see the following display in your web browser:
.. image:: /_images/deployment/azure-website/step-05.png
@@ -90,9 +90,9 @@ and how to properly configure PHP for a production environment.
Configuring the latest PHP Runtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Even though Symfony only requires PHP 5.3.9 to run, it's always recommended
-to use the most recent PHP version whenever possible. PHP 5.3 is no longer
-supported by the PHP core team, but you can update it easily in Azure.
+Even though Symfony only requires PHP 5.5.9 to run, it's always recommended
+to use the most recent PHP version whenever possible. Earlier versions are no longer
+supported by the PHP core team, but you can update it in Azure.
To update your PHP version on Azure, go to the **Application settings** under
**SETTINGS** and select the version you want.
@@ -117,8 +117,8 @@ the web server.
.. image:: /_images/deployment/azure-website/step-08.png
:alt: OPCache Configuration
-Tweaking php.ini Configuration Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Tweaking ``php.ini`` Configuration Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Microsoft Azure allows you to override the ``php.ini`` global configuration
settings by creating a custom ``.user.ini`` file under the project root
@@ -132,7 +132,7 @@ directory (``site/wwwroot``).
upload_max_filesize = 10M
None of these settings *needs* to be overridden. The default PHP configuration
-is already pretty good, so this is just an example to show how you can easily
+is already pretty good, so this is just an example to show how you can
tweak PHP internal settings by uploading your custom ``.ini`` file.
You can either manually create this file on your Azure Website FTP server under
@@ -156,7 +156,7 @@ Enabling the PHP intl Extension
no longer necessary.** You can check if the ``intl`` extension is enabled in the
:phpfunction:`phpinfo` page.
-However if the ``intl`` extension is not enabled you can follow these steps.
+However, if the ``intl`` extension is not enabled you can follow these steps.
This is the tricky part of the guide! To enable the ``intl`` extension, there is
no need to upload any DLL files as the ``php_intl.dll`` file already exists on
@@ -172,7 +172,7 @@ access the online **Kudu** tool by browsing to the following URL:
**Kudu** is a set of tools to manage your application. It comes with a file
explorer, a command line prompt, a log stream and a configuration settings summary
-page. Of course, this section can only be accessed if you're logged in to
+page. This section can only be accessed if you're logged in to
your main Azure Website account.
.. image:: /_images/deployment/azure-website/step-09.png
@@ -252,13 +252,13 @@ directory with at least the following contents:
.. code-block:: text
- /app/bootstrap.php.cache
- /app/cache/*
+ /var/bootstrap.php.cache
+ /var/cache/*
/app/config/parameters.yml
- /app/logs/*
- !app/cache/.gitkeep
- !app/logs/.gitkeep
- /app/SymfonyRequirements.php
+ /var/logs/*
+ !var/cache/.gitkeep
+ !var/logs/.gitkeep
+ /var/SymfonyRequirements.php
/build/
/vendor/
/bin/
@@ -336,7 +336,7 @@ make them appear.
:alt: MySQL database settings
The displayed MySQL database settings should be something similar to the code
-below. Of course, each value depends on what you've already configured.
+below. Each value depends on what you've already configured.
.. code-block:: text
@@ -363,14 +363,14 @@ the host-name and credentials of some other third-party mailing service if
your application needs to send emails.
Your Symfony application is now configured and should be almost operational. The
-final step is to build the database schema. This can easily be done with the
+final step is to build the database schema. This can be done with the
command line interface if you're using Doctrine. In the online **Console** tool
of the Kudu application, run the following command to mount the tables into your
MySQL database.
.. code-block:: terminal
- $ php app/console doctrine:schema:update --force
+ $ php bin/console doctrine:schema:update --force
This command builds the tables and indexes for your MySQL database. If your
Symfony application is more complex than a basic Symfony Standard Edition, you
@@ -391,7 +391,7 @@ Configure the Web Server
At this point, the Symfony application has been deployed and works perfectly on
the Azure Website. However, the ``web`` folder is still part of the URL, which
-you definitely don't want. But don't worry! You can easily configure the web
+you definitely don't want. But don't worry! You can configure the web
server to point to the ``web`` folder and remove the ``web`` in the URL (and
guarantee that nobody can access files outside of the ``web`` directory.)
@@ -404,32 +404,32 @@ application, configure it with the following content:
.. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
As you can see, the latest rule ``RewriteRequestsToPublic`` is responsible for
@@ -446,7 +446,7 @@ Conclusion
----------
Nice work! You've now deployed your Symfony application to the Microsoft
-Azure Website Cloud platform. You also saw that Symfony can be easily configured
+Azure Website Cloud platform. You also saw that Symfony can be configured
and executed on a Microsoft IIS web server. The process is simple and easy
to implement. And as a bonus, Microsoft is continuing to reduce the number
of steps needed so that deployment becomes even easier.
diff --git a/deployment/fortrabbit.rst b/deployment/fortrabbit.rst
index ffe968e813d..31195949912 100644
--- a/deployment/fortrabbit.rst
+++ b/deployment/fortrabbit.rst
@@ -48,27 +48,27 @@ to redirect it to :phpfunction:`error_log`:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:monolog="http://symfony.com/schema/dic/monolog"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/monolog
- http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+ https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
-
.. code-block:: php
// app/config/config_prod.php
- $container->loadFromExtension('monolog', array(
+ $container->loadFromExtension('monolog', [
// ...
- 'handlers' => array(
- 'nested' => array(
+ 'handlers' => [
+ 'nested' => [
'type' => 'error_log',
- ),
- ),
- ));
+ ],
+ ],
+ ]);
Configuring Database Access & Session Handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -78,7 +78,7 @@ Create the file ``app/config/config_prod_secrets.php`` with the following
contents::
// get the path to the secrects.json file
- $secrets = getenv("APP_SECRETS")
+ $secrets = getenv("APP_SECRETS");
if (!$secrets) {
return;
}
@@ -98,7 +98,7 @@ contents::
// check if the Memcache component is present
if (isset($secrets['MEMCACHE'])) {
$memcache = $secrets['MEMCACHE'];
- $handlers = array();
+ $handlers = [];
foreach (range(1, $memcache['COUNT']) as $num) {
$handlers[] = $memcache['HOST'.$num].':'.$memcache['PORT'.$num];
@@ -126,12 +126,12 @@ Make sure this file is imported into the main config file:
- { resource: config.yml }
- { resource: config_prod_secrets.php }
- # ..
+ # ...
framework:
session:
# set handler_id to null to use default session handler from php.ini (memcached)
handler_id: ~
- # ..
+ # ...
.. code-block:: xml
@@ -140,18 +140,18 @@ Make sure this file is imported into the main config file:
+ xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+ http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-
+
-
-
@@ -161,11 +161,11 @@ Make sure this file is imported into the main config file:
$loader->import('config.php');
$loader->import('config_prod_secrets.php');
- $container->loadFromExtension('framework', array(
- 'session' => array(
+ $container->loadFromExtension('framework', [
+ 'session' => [
'handler_id' => null,
- ),
- ));
+ ],
+ ]);
// ...
@@ -182,7 +182,7 @@ Environment Variables
~~~~~~~~~~~~~~~~~~~~~
Set the ``SYMFONY_ENV`` environment variable to ``prod`` to make sure the right
-config files get loaded. ENV vars are configuable in fortrabbit Dashboard as well.
+config files get loaded. ENV vars are configurable in fortrabbit Dashboard as well.
Document Root
~~~~~~~~~~~~~
@@ -198,7 +198,7 @@ It is assumed that your codebase is under version-control with Git and dependenc
are managed with Composer (locally).
Every time you push to fortrabbit composer install runs before your code gets
-deployed. To finetune the deployment behavior put a `fortrabbit.yml`_. deployment
+deployed. To fine-tune the deployment behavior put a `fortrabbit.yml`_. deployment
file (optional) in the project root.
Add fortrabbit as a (additional) Git remote and add your configuration changes:
@@ -270,8 +270,8 @@ Commit and push
.. note::
- The first ``git push`` takes much longer as all composer dependencies get
- downloaded. All subsequent deploys are done within seconds.
+ The first ``git push`` takes much longer as all composer dependencies get
+ downloaded. All subsequent deploys are done within seconds.
That's it! Your application is being deployed on fortrabbit. More information
about `database migrations and tunneling`_ can be found in the fortrabbit
diff --git a/deployment/heroku.rst b/deployment/heroku.rst
index 5438208f4fa..fbef77703b2 100644
--- a/deployment/heroku.rst
+++ b/deployment/heroku.rst
@@ -24,7 +24,7 @@ Preparing your Application
Deploying a Symfony application to Heroku doesn't require any change in its
code, but it requires some minor tweaks to its configuration.
-By default, the Symfony app will log into your application's ``app/log/``
+By default, the Symfony app will log into your application's ``var/log/``
directory. This is not ideal as Heroku uses an `ephemeral file system`_. On
Heroku, the best way to handle logging is using `Logplex`_. And the best way to
send log data to Logplex is by writing to ``STDERR`` or ``STDOUT``. Luckily,
@@ -85,43 +85,33 @@ below:
~~~~~~~~~~~~~~~~~~~~
By default, Heroku will launch an Apache web server together with PHP to serve
-applications. However, two special circumstances apply to Symfony applications:
-
-#. The document root is in the ``web/`` directory and not in the root directory
- of the application;
-#. The Composer ``bin-dir``, where vendor binaries (and thus Heroku's own boot
- scripts) are placed, is ``bin/`` , and not the default ``vendor/bin``.
-
-.. note::
-
- Vendor binaries are usually installed to ``vendor/bin`` by Composer, but
- sometimes (e.g. when running a Symfony Standard Edition project!), the
- location will be different. If in doubt, you can always run
- ``composer config bin-dir`` to figure out the right location.
+applications. However, a special circumstance apply to Symfony applications:
+the document root is in the ``web/`` directory and not in the root directory
+of the application.
Create a new file called ``Procfile`` (without any extension) at the root
directory of the application and add just the following content:
.. code-block:: text
- web: bin/heroku-php-apache2 web/
+ web: vendor/bin/heroku-php-apache2 web/
.. note::
- If you prefer to use Nginx, which is also available on Heroku, you can create
+ If you prefer to use nginx, which is also available on Heroku, you can create
a configuration file for it and point to it from your Procfile as described
in the `Heroku documentation`_:
.. code-block:: text
- web: bin/heroku-php-nginx -C nginx_app.conf web/
+ web: vendor/bin/heroku-php-nginx -C nginx_app.conf web/
If you prefer working on the command console, execute the following commands to
create the ``Procfile`` file and to add it to the repository:
.. code-block:: terminal
- $ echo "web: bin/heroku-php-apache2 web/" > Procfile
+ $ echo "web: vendor/bin/heroku-php-apache2 web/" > Procfile
$ git add .
$ git commit -m "Procfile for Apache and PHP"
[master 35075db] Procfile for Apache and PHP
@@ -275,7 +265,7 @@ This is also very useful to build assets on the production system, e.g. with Ass
{
"scripts": {
"compile": [
- "app/console assetic:dump"
+ "bin/console assetic:dump"
]
}
}
diff --git a/deployment/platformsh.rst b/deployment/platformsh.rst
index 212099d87d0..e1fd257f538 100644
--- a/deployment/platformsh.rst
+++ b/deployment/platformsh.rst
@@ -40,7 +40,7 @@ Platform.sh how to deploy your application (read more about
# The type of the application to build.
type: php:5.6
build:
- flavor: composer
+ flavor: composer
# The relationships of the application with services or other applications.
# The left-hand side is the name of the relationship as it will be exposed
@@ -61,16 +61,17 @@ Platform.sh how to deploy your application (read more about
# The mounts that will be performed when the package is deployed.
mounts:
- '/app/cache': 'shared:files/cache'
- '/app/logs': 'shared:files/logs'
+ '/var/cache': 'shared:files/cache'
+ '/var/logs': 'shared:files/logs'
+ '/var/sessions': 'shared:files/sessions'
# The hooks that will be performed when the package is deployed.
hooks:
build: |
- rm web/app_dev.php
- app/console --env=prod assetic:dump --no-debug
+ rm web/app_dev.php
+ php bin/console --env=prod assetic:dump --no-debug
deploy: |
- app/console --env=prod cache:clear
+ php bin/console --env=prod cache:clear
For best practices, you should also add a ``.platform`` folder at the root of
your Git repository which contains the following files:
@@ -110,7 +111,7 @@ following file (it's your role to add this file to your code base)::
foreach ($relationships['database'] as $endpoint) {
if (empty($endpoint['query']['is_master'])) {
- continue;
+ continue;
}
$container->setParameter('database_driver', 'pdo_' . $endpoint['scheme']);
diff --git a/deployment/proxies.rst b/deployment/proxies.rst
index 4cf4927965e..7a130f4783c 100644
--- a/deployment/proxies.rst
+++ b/deployment/proxies.rst
@@ -3,73 +3,50 @@ How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy
When you deploy your application, you may be behind a load balancer (e.g.
an AWS Elastic Load Balancing) or a reverse proxy (e.g. Varnish for
-:doc:`caching`).
+:doc:`caching `).
For the most part, this doesn't cause any problems with Symfony. But, when
a request passes through a proxy, certain request information is sent using
-either the standard ``Forwarded`` header or non-standard special ``X-Forwarded-*``
-headers. For example, instead of reading the ``REMOTE_ADDR`` header (which
-will now be the IP address of your reverse proxy), the user's true IP will be
-stored in a standard ``Forwarded: for="..."`` header or a non standard
-``X-Forwarded-For`` header.
-
-.. versionadded:: 2.7
- ``Forwarded`` header support was introduced in Symfony 2.7.
+either the standard ``Forwarded`` header or ``X-Forwarded-*`` headers. For example,
+instead of reading the ``REMOTE_ADDR`` header (which will now be the IP address of
+your reverse proxy), the user's true IP will be stored in a standard ``Forwarded: for="..."``
+header or a ``X-Forwarded-For`` header.
If you don't configure Symfony to look for these headers, you'll get incorrect
information about the client's IP address, whether or not the client is connecting
via HTTPS, the client's port and the hostname being requested.
-Solution: trusted_proxies
--------------------------
-
-This is no problem, but you *do* need to tell Symfony what is happening
-and which reverse proxy IP addresses will be doing this type of thing:
-
-.. configuration-block::
-
- .. code-block:: yaml
+.. _request-set-trusted-proxies:
- # app/config/config.yml
- # ...
- framework:
- trusted_proxies: [192.0.0.1, 10.0.0.0/8]
+Solution: ``setTrustedProxies()``
+---------------------------------
- .. code-block:: xml
+To fix this, you need to tell Symfony which reverse proxy IP addresses to trust
+and what headers your reverse proxy uses to send information::
-
-
-
+ // web/app.php
-
-
-
-
+ // ...
+ $request = Request::createFromGlobals();
- .. code-block:: php
+ // tell Symfony about your reverse proxy
+ Request::setTrustedProxies(
+ // the IP address (or range) of your proxy
+ ['192.0.0.1', '10.0.0.0/8'],
- // app/config/config.php
- $container->loadFromExtension('framework', array(
- 'trusted_proxies' => array('192.0.0.1', '10.0.0.0/8'),
- ));
+ // trust *all* "X-Forwarded-*" headers
+ Request::HEADER_X_FORWARDED_ALL
-In this example, you're saying that your reverse proxy (or proxies) has
-the IP address ``192.0.0.1`` or matches the range of IP addresses that use
-the CIDR notation ``10.0.0.0/8``. For more details, see the
-:ref:`framework.trusted_proxies ` option.
+ // or, if your proxy instead uses the "Forwarded" header
+ // Request::HEADER_FORWARDED
-You are also saying that you trust that the proxy does not send conflicting
-headers, e.g. sending both ``X-Forwarded-For`` and ``Forwarded`` in the same
-request.
+ // or, if you're using AWS ELB
+ // Request::HEADER_X_FORWARDED_AWS_ELB
+ );
-That's it! Symfony will now look for the correct headers to get information
-like the client's IP address, host, port and whether the request is
-using HTTPS.
+The Request object has several ``Request::HEADER_*`` constants that control exactly
+*which* headers from your reverse proxy are trusted. The argument is a bit field,
+so you can also pass your own value (e.g. ``0b00110``).
But what if the IP of my Reverse Proxy Changes Constantly!
----------------------------------------------------------
@@ -82,84 +59,46 @@ In this case, you'll need to - *very carefully* - trust *all* proxies.
other than your load balancers. For AWS, this can be done with `security groups`_.
#. Once you've guaranteed that traffic will only come from your trusted reverse
- proxies, configure Symfony to *always* trust incoming request. This is
- done inside of your front controller:
-
- .. code-block:: diff
+ proxies, configure Symfony to *always* trust incoming request::
- // web/app.php
-
- // ...
- $request = Request::createFromGlobals();
- + Request::setTrustedProxies(array('127.0.0.1', $request->server->get('REMOTE_ADDR')));
+ // web/app.php
- // ...
+ // ...
+ Request::setTrustedProxies(
+ // trust *all* requests
+ ['127.0.0.1', $request->server->get('REMOTE_ADDR')],
-#. Ensure that the trusted_proxies setting in your ``app/config/config.yml``
- is not set or it will overwrite the ``setTrustedProxies()`` call above.
+ // if you're using ELB, otherwise use a constant from above
+ Request::HEADER_X_FORWARDED_AWS_ELB
+ );
That's it! It's critical that you prevent traffic from all non-trusted sources.
If you allow outside traffic, they could "spoof" their true IP address and
other information.
-.. _request-untrust-header:
-
-My Reverse Proxy Sends X-Forwarded-For but Does not Filter the Forwarded Header
--------------------------------------------------------------------------------
+If you are also using a reverse proxy on top of your load balancer (e.g.
+`CloudFront`_), calling ``$request->server->get('REMOTE_ADDR')`` won't be
+enough, as it will only trust the node sitting directly above your application
+(in this case your load balancer). You also need to append the IP addresses or
+ranges of any additional proxy (e.g. `CloudFront IP ranges`_) to the array of
+trusted proxies.
-Many popular proxy implementations do not yet support the ``Forwarded`` header
-and do not filter it by default. Ideally, you would configure this in your
-proxy. If this is not possible, you can tell Symfony to distrust the ``Forwarded``
-header, while still trusting your proxy's ``X-Forwarded-For`` header.
+Custom Headers When Using a Reverse Proxy
+-----------------------------------------
-This is done inside of your front controller::
+Some reverse proxies (like `CloudFront`_ with ``CloudFront-Forwarded-Proto``) may force you to use a custom header.
+For instance you have ``Custom-Forwarded-Proto`` instead of ``X-Forwarded-Proto``.
- // web/app.php
-
- // ...
- Request::setTrustedHeaderName(Request::HEADER_FORWARDED, null);
-
- $response = $kernel->handle($request);
- // ...
-
-Configuring the proxy server trust is very important, as not doing so will
-allow malicious users to "spoof" their IP address.
-
-My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers
-------------------------------------------------------------
-
-Although `RFC 7239`_ recently defined a standard ``Forwarded`` header to disclose
-all proxy information, most reverse proxies store information in non-standard
-``X-Forwarded-*`` headers.
-
-But if your reverse proxy uses other non-standard header names, you can configure
-these (see ":doc:`/components/http_foundation/trusting_proxies`").
-
-The code for doing this will need to live in your front controller (e.g. ``web/app.php``).
-
-.. _my-reverse-proxy-does-not-provide-all-the-standards-headers:
-
-My Reverse Proxy Does not Provide All the Standard Headers
-----------------------------------------------------------
-
-AWS Elastic Load Balancing for example does not provide the ``X-Forwarded-Host``
-and ``X-Forwarded`` HTTP headers, so you must make the following changes in the
-front controller:
-
-.. code-block:: diff
+In this case, you'll need to set the header ``X-Forwarded-Proto`` with the value of
+``Custom-Forwarded-Proto`` early enough in your application, i.e. before handling the request::
// web/app.php
// ...
- $request = Request::createFromGlobals();
- // be very careful with the next line; see "But what if the IP of my Reverse Proxy Changes Constantly!"
- + Request::setTrustedProxies(array('127.0.0.1', $request->server->get('REMOTE_ADDR')));
- // the next line is needed because AWS ELB doesn't send X-Forwarded-Host
- + Request::setTrustedHeaderName(Request::HEADER_CLIENT_HOST, null);
- // the next line is needed because AWS ELB doesn't use RFC 7239
- + Request::setTrustedHeaderName(Request::HEADER_FORWARDED, null);
-
+ $_SERVER['HTTP_X_FORWARDED_PROTO'] = $_SERVER['HTTP_CUSTOM_FORWARDED_PROTO'];
// ...
+ $response = $kernel->handle($request);
.. _`security groups`: http://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-groups.html
-.. _`RFC 7239`: http://tools.ietf.org/html/rfc7239
+.. _`CloudFront`: https://en.wikipedia.org/wiki/Amazon_CloudFront
+.. _`CloudFront IP ranges`: https://ip-ranges.amazonaws.com/ip-ranges.json
diff --git a/doctrine.rst b/doctrine.rst
index 2fd5d6d3988..1cfeda2fb3d 100644
--- a/doctrine.rst
+++ b/doctrine.rst
@@ -4,6 +4,11 @@
Databases and the Doctrine ORM
==============================
+.. admonition:: Screencast
+ :class: screencast
+
+ Do you prefer video tutorials? Check out the `Doctrine screencast series`_.
+
One of the most common and challenging tasks for any application
involves persisting and reading information to and from a database. Although
the Symfony Framework doesn't integrate any component to work with databases,
@@ -78,9 +83,9 @@ information. By convention, this information is usually configured in an
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/doctrine
- http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+ https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('doctrine', array(
- 'dbal' => array(
- 'driver' => 'pdo_mysql',
- 'host' => '%database_host%',
- 'dbname' => '%database_name%',
- 'user' => '%database_user%',
+ $container->loadFromExtension('doctrine', [
+ 'dbal' => [
+ 'driver' => 'pdo_mysql',
+ 'host' => '%database_host%',
+ 'dbname' => '%database_name%',
+ 'user' => '%database_user%',
'password' => '%database_password%',
- ),
- ));
+ ],
+ ]);
By separating the database information into a separate file, you can
- easily keep different versions of the file on each server. You can also
- easily store database configuration (or any sensitive information) outside
+ keep different versions of the file on each server. You can also
+ store database configuration (or any sensitive information) outside
of your project, like inside your Apache configuration, for example. For
more information, see :doc:`/configuration/external_parameters`.
@@ -116,7 +121,7 @@ can automatically generate an empty ``test_project`` database for you:
.. code-block:: terminal
- $ php app/console doctrine:database:create
+ $ php bin/console doctrine:database:create
.. sidebar:: Setting up the Database to be UTF8
@@ -128,12 +133,8 @@ can automatically generate an empty ``test_project`` database for you:
.. code-block:: terminal
- $ php app/console doctrine:database:drop --force
- $ php app/console doctrine:database:create
-
- There's no way to configure these defaults inside Doctrine, as it tries to be
- as agnostic as possible in terms of environment configuration. One way to solve
- this problem is to configure server-level defaults.
+ $ php bin/console doctrine:database:drop --force
+ $ php bin/console doctrine:database:create
Setting UTF8 defaults for MySQL is as simple as adding a few lines to
your configuration file (typically ``my.cnf``):
@@ -145,6 +146,55 @@ can automatically generate an empty ``test_project`` database for you:
collation-server = utf8mb4_unicode_ci # Replaces utf8_unicode_ci
character-set-server = utf8mb4 # Replaces utf8
+ You can also change the defaults for Doctrine so that the generated SQL
+ uses the correct character set.
+
+ .. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ doctrine:
+ dbal:
+ charset: utf8mb4
+ default_table_options:
+ charset: utf8mb4
+ collate: utf8mb4_unicode_ci
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+ utf8mb4
+ utf8mb4_unicode_ci
+
+
+
+
+ .. code-block:: php
+
+ // app/config/config.php
+ $configuration->loadFromExtension('doctrine', [
+ 'dbal' => [
+ 'charset' => 'utf8mb4',
+ 'default_table_options' => [
+ 'charset' => 'utf8mb4',
+ 'collate' => 'utf8mb4_unicode_ci',
+ ]
+ ],
+ ]);
+
We recommend against MySQL's ``utf8`` character set, since it does not
support 4-byte unicode characters, and strings containing them will be
truncated. This is fixed by the `newer utf8mb4 character set`_.
@@ -172,7 +222,7 @@ can automatically generate an empty ``test_project`` database for you:
doctrine:
dbal:
driver: pdo_sqlite
- path: '%kernel.root_dir%/sqlite.db'
+ path: '%kernel.project_dir%/app/sqlite.db'
charset: UTF8
.. code-block:: xml
@@ -183,28 +233,28 @@ can automatically generate an empty ``test_project`` database for you:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/doctrine
- http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+ https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('doctrine', array(
- 'dbal' => array(
- 'driver' => 'pdo_sqlite',
- 'path' => '%kernel.root_dir%/sqlite.db',
+ $container->loadFromExtension('doctrine', [
+ 'dbal' => [
+ 'driver' => 'pdo_sqlite',
+ 'path' => '%kernel.project_dir%/app/sqlite.db',
'charset' => 'UTF-8',
- ),
- ));
+ ],
+ ]);
Creating an Entity Class
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -237,7 +287,7 @@ just a simple PHP class.
.. code-block:: terminal
- $ php app/console doctrine:generate:entity
+ $ php bin/console doctrine:generate:entity
.. index::
single: Doctrine; Adding mapping metadata
@@ -329,18 +379,25 @@ directly inside the ``Product`` class via DocBlock annotations:
+ https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
-
-
+.. note::
+
+ If you are using an SQLite database, you'll see the following error:
+ *PDOException: SQLSTATE[HY000]: General error: 1 Cannot add a NOT NULL
+ column with default value NULL*. Add a ``nullable=true`` option to the
+ ``description`` property to fix the problem.
+
.. note::
A bundle can accept only one metadata definition format. For example, it's
@@ -399,7 +456,7 @@ see the :ref:`doctrine-field-types` section.
.. code-block:: terminal
- $ php app/console doctrine:schema:validate
+ $ php bin/console doctrine:schema:validate
.. _doctrine-generating-getters-and-setters:
@@ -419,14 +476,14 @@ Creating the Database Tables/Schema
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You now have a usable ``Product`` class with mapping information so that
-Doctrine knows exactly how to persist it. Of course, you don't yet have the
-corresponding ``product`` table in your database. Fortunately, Doctrine can
-automatically create all the database tables needed for every known entity
-in your application. To do this, run:
+Doctrine knows exactly how to persist it. You don't yet have the corresponding
+``product`` table in your database. Fortunately, Doctrine can automatically
+create all the database tables needed for every known entity in your
+application. To do this, run:
.. code-block:: terminal
- $ php app/console doctrine:schema:update --force
+ $ php bin/console doctrine:schema:update --force
.. tip::
@@ -463,18 +520,20 @@ a controller, this is pretty easy. Add the following method to the
// ...
use AppBundle\Entity\Product;
+ use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\HttpFoundation\Response;
- // ...
public function createAction()
{
+ // you can fetch the EntityManager via $this->getDoctrine()
+ // or you can add an argument to your action: createAction(EntityManagerInterface $entityManager)
+ $entityManager = $this->getDoctrine()->getManager();
+
$product = new Product();
$product->setName('Keyboard');
$product->setPrice(19.99);
$product->setDescription('Ergonomic and stylish!');
- $entityManager = $this->getDoctrine()->getManager();
-
// tells Doctrine you want to (eventually) save the Product (no queries yet)
$entityManager->persist($product);
@@ -484,33 +543,34 @@ a controller, this is pretty easy. Add the following method to the
return new Response('Saved new product with id '.$product->getId());
}
+ // if you have multiple entity managers, use the registry to fetch them
+ public function editAction()
+ {
+ $doctrine = $this->getDoctrine();
+ $entityManager = $doctrine->getManager();
+ $otherEntityManager = $doctrine->getManager('other_connection');
+ }
+
.. note::
If you're following along with this example, you'll need to create a
route that points to this action to see it work.
-.. tip::
+Take a look at the previous example in more detail:
- This article shows working with Doctrine from within a controller by using
- the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine`
- method of the controller. This method is a shortcut to get the
- ``doctrine`` service. You can work with Doctrine anywhere else
- by injecting that service in the service. See
- :doc:`/service_container` for more on creating your own services.
+.. _doctrine-entity-manager:
-Take a look at the previous example in more detail:
+* **line 12** The ``$this->getDoctrine()->getManager()`` method gets Doctrine's
+ *entity manager* object, which is the most important object in Doctrine. It's
+ responsible for saving objects to, and fetching objects from, the database.
-* **lines 10-13** In this section, you instantiate and work with the ``$product``
+* **lines 14-17** In this section, you instantiate and work with the ``$product``
object like any other normal PHP object.
-* **line 15** This line fetches Doctrine's *entity manager* object, which is
- responsible for the process of persisting objects to, and fetching objects
- from, the database.
-
-* **line 18** The ``persist($product)`` call tells Doctrine to "manage" the
+* **line 20** The ``persist($product)`` call tells Doctrine to "manage" the
``$product`` object. This does **not** cause a query to be made to the database.
-* **line 21** When the ``flush()`` method is called, Doctrine looks through
+* **line 23** When the ``flush()`` method is called, Doctrine looks through
all of the objects that it's managing to see if they need to be persisted
to the database. In this example, the ``$product`` object's data doesn't
exist in the database, so the entity manager executes an ``INSERT`` query,
@@ -602,23 +662,24 @@ Once you have a repository object, you can access all sorts of helpful methods::
.. note::
- Of course, you can also issue complex queries, which you'll learn more
+ You can also issue complex queries, which you'll learn more
about in the :ref:`doctrine-queries` section.
You can also take advantage of the useful ``findBy()`` and ``findOneBy()`` methods
-to easily fetch objects based on multiple conditions::
+to fetch objects based on multiple conditions::
$repository = $this->getDoctrine()->getRepository(Product::class);
// looks for a single product matching the given name and price
- $product = $repository->findOneBy(
- array('name' => 'Keyboard', 'price' => 19.99)
- );
+ $product = $repository->findOneBy([
+ 'name' => 'Keyboard',
+ 'price' => 19.99
+ ]);
// looks for multiple products matching the given name, ordered by price
$products = $repository->findBy(
- array('name' => 'Keyboard'),
- array('price' => 'ASC')
+ ['name' => 'Keyboard'],
+ ['price' => 'ASC']
);
.. tip::
@@ -698,10 +759,10 @@ without any work::
$product = $repository->find($productId);
$product = $repository->findOneByName('Keyboard');
-Of course, Doctrine also allows you to write more complex queries using the
-Doctrine Query Language (DQL). DQL is similar to SQL except that you should
-imagine that you're querying for one or more objects of an entity class (e.g. ``Product``)
-instead of querying for rows on a table (e.g. ``product``).
+Doctrine also allows you to write more complex queries using the Doctrine Query
+Language (DQL). DQL is similar to SQL except that you should imagine that you're
+querying for one or more objects of an entity class (e.g. ``Product``) instead
+of querying for rows on a table (e.g. ``product``).
When querying in Doctrine, you have two main options: writing pure DQL queries
or using Doctrine's Query Builder.
@@ -713,7 +774,6 @@ Imagine that you want to query for products that cost more than ``19.99``,
ordered from least to most expensive. You can use DQL, Doctrine's native
SQL-like language, to construct a query for this scenario::
- $entityManager = $this->getDoctrine()->getManager();
$query = $entityManager->createQuery(
'SELECT p
FROM AppBundle:Product p
@@ -740,7 +800,7 @@ result, you can use ``getOneOrNullResult()``::
$product = $query->setMaxResults(1)->getOneOrNullResult();
-The DQL syntax is incredibly powerful, allowing you to easily join between
+The DQL syntax is incredibly powerful, allowing you to join between
entities (the topic of :doc:`relations ` will be
covered later), group, etc. For more information, see the official
`Doctrine Query Language`_ documentation.
@@ -838,7 +898,7 @@ Learn more
.. _`Basic Mapping Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html
.. _`Query Builder`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/query-builder.html
.. _`Doctrine Query Language`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html
-.. _`Mapping Types Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping
+.. _`Mapping Types documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping
.. _`Property Mapping`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping
.. _`Reserved SQL keywords documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#quoting-reserved-words
.. _`Creating Classes for the Database`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#creating-classes-for-the-database
@@ -848,4 +908,5 @@ Learn more
.. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
.. _`newer utf8mb4 character set`: https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html
.. _`Transactions and Concurrency`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/transactions-and-concurrency.html
-.. _`limit of 767 bytes for the index key prefix`: https://dev.mysql.com/doc/refman/5.6/en/innodb-restrictions.html
+.. _`limit of 767 bytes for the index key prefix`: https://dev.mysql.com/doc/refman/5.6/en/innodb-limits.html
+.. _`Doctrine screencast series`: https://symfonycasts.com/screencast/symfony3-doctrine
diff --git a/doctrine/associations.rst b/doctrine/associations.rst
index 0a481bfcd27..24a333c8a36 100644
--- a/doctrine/associations.rst
+++ b/doctrine/associations.rst
@@ -4,6 +4,12 @@
How to Work with Doctrine Associations / Relations
==================================================
+.. admonition:: Screencast
+ :class: screencast
+
+ Do you prefer video tutorials? Check out the `Mastering Doctrine Relations`_
+ screencast series.
+
Suppose that each product in your application belongs to exactly one category.
In this case, you'll need a ``Category`` class, and a way to relate a
``Product`` object to a ``Category`` object.
@@ -14,7 +20,7 @@ the class for you.
.. code-block:: terminal
- $ php app/console doctrine:generate:entity --no-interaction \
+ $ php bin/console doctrine:generate:entity --no-interaction \
--entity="AppBundle:Category" \
--fields="name:string(255)"
@@ -77,7 +83,7 @@ property on the ``Product`` class, annotated as follows:
+ https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
@@ -87,7 +93,7 @@ property on the ``Product`` class, annotated as follows:
inversed-by="products"
join-column="category">
-
@@ -144,14 +150,14 @@ to hold those associated objects.
+ https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
-
-
+
-
-
+
@@ -86,47 +80,32 @@ managers that use this connection.
use AppBundle\EventListener\SearchIndexer2;
use AppBundle\EventListener\SearchIndexerSubscriber;
- $container->loadFromExtension('doctrine', array(
- 'dbal' => array(
- 'default_connection' => 'default',
- 'connections' => array(
- 'default' => array(
- 'driver' => 'pdo_sqlite',
- 'memory' => true,
- ),
- ),
- ),
- ));
-
- $container
- ->register('my.listener', SearchIndexer::class)
- ->addTag('doctrine.event_listener', array('event' => 'postPersist'))
+ $container->autowire(SearchIndexer::class)
+ ->addTag('doctrine.event_listener', ['event' => 'postPersist'])
;
- $container
- ->register('my.listener2', SearchIndexer2::class)
- ->addTag('doctrine.event_listener', array(
+ $container->autowire(SearchIndexer2::class)
+ ->addTag('doctrine.event_listener', [
'event' => 'postPersist',
'connection' => 'default',
- ))
+ ])
;
- $container
- ->register('my.subscriber', SearchIndexerSubscriber::class)
- ->addTag('doctrine.event_subscriber', array('connection' => 'default'))
+ $container->autowire(SearchIndexerSubscriber::class)
+ ->addTag('doctrine.event_subscriber', ['connection' => 'default'])
;
Creating the Listener Class
---------------------------
-In the previous example, a service ``my.listener`` was configured as a Doctrine
+In the previous example, a ``SearchIndexer`` service was configured as a Doctrine
listener on the event ``postPersist``. The class behind that service must have
a ``postPersist()`` method, which will be called when the event is dispatched::
// src/AppBundle/EventListener/SearchIndexer.php
namespace AppBundle\EventListener;
- // for Doctrine < 2.4: use Doctrine\ORM\Event\LifecycleEventArgs;
- use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
use AppBundle\Entity\Product;
+ // for Doctrine < 2.4: use Doctrine\ORM\Event\LifecycleEventArgs;
+ use Doctrine\Persistence\Event\LifecycleEventArgs;
class SearchIndexer
{
@@ -158,7 +137,7 @@ entity), you should check for the entity's class type in your method
In Doctrine 2.4, a feature called Entity Listeners was introduced.
It is a lifecycle listener class used for an entity. You can read
- about it in `the Doctrine Documentation`_.
+ about it in `the DoctrineBundle documentation`_.
Creating the Subscriber Class
-----------------------------
@@ -169,20 +148,20 @@ interface and have an event method for each event it subscribes to::
// src/AppBundle/EventListener/SearchIndexerSubscriber.php
namespace AppBundle\EventListener;
+ use AppBundle\Entity\Product;
use Doctrine\Common\EventSubscriber;
// for Doctrine < 2.4: use Doctrine\ORM\Event\LifecycleEventArgs;
- use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
use Doctrine\ORM\Events;
- use AppBundle\Entity\Product;
+ use Doctrine\Persistence\Event\LifecycleEventArgs;
class SearchIndexerSubscriber implements EventSubscriber
{
public function getSubscribedEvents()
{
- return array(
+ return [
Events::postPersist,
Events::postUpdate,
- );
+ ];
}
public function postUpdate(LifecycleEventArgs $args)
@@ -251,7 +230,7 @@ to the tag like so:
-
@@ -262,17 +241,14 @@ to the tag like so:
$container
->register('my.listener', SearchIndexer::class)
- ->addTag('doctrine.event_listener', array('event' => 'postPersist', 'lazy' => 'true'))
+ ->addTag('doctrine.event_listener', ['event' => 'postPersist', 'lazy' => 'true'])
;
.. note::
- Marking an event listener as ``lazy`` has nothing to do with lazy service
+ Marking an event listener as ``lazy`` has nothing to do with lazy service
definitions which are described :doc:`in their own article `
-.. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
-.. _`the Doctrine Documentation`: https://symfony.com/doc/current/bundles/DoctrineBundle/entity-listeners.html
-
Priorities for Event Listeners
------------------------------
@@ -304,10 +280,10 @@ numbers mean that listeners are invoked earlier.
-
-
@@ -319,10 +295,14 @@ numbers mean that listeners are invoked earlier.
$container
->register('my.listener.with_high_priority', MyHighPriorityListener::class)
- ->addTag('doctrine.event_listener', array('event' => 'postPersist', 'priority' => 10))
+ ->addTag('doctrine.event_listener', ['event' => 'postPersist', 'priority' => 10])
;
$container
->register('my.listener.with_low_priority', MyLowPriorityListener::class)
- ->addTag('doctrine.event_listener', array('event' => 'postPersist', 'priority' => 1))
+ ->addTag('doctrine.event_listener', ['event' => 'postPersist', 'priority' => 1])
;
+
+.. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
+.. _`the DoctrineBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineBundle/entity-listeners.html
+.. _`DoctrineMongoDBBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineMongoDBBundle/index.html
diff --git a/doctrine/lifecycle_callbacks.rst b/doctrine/lifecycle_callbacks.rst
index a6535a9c749..873de528404 100644
--- a/doctrine/lifecycle_callbacks.rst
+++ b/doctrine/lifecycle_callbacks.rst
@@ -15,6 +15,9 @@ callbacks. This is not necessary if you're using YAML or XML for your mapping.
.. code-block:: php-annotations
+ // src/AppBundle/Entity/Product.php
+ use Doctrine\ORM\Mapping as ORM;
+
/**
* @ORM\Entity()
* @ORM\HasLifecycleCallbacks()
@@ -33,6 +36,7 @@ the current date, only when the entity is first persisted (i.e. inserted):
.. code-block:: php-annotations
// src/AppBundle/Entity/Product.php
+ use Doctrine\ORM\Mapping as ORM;
/**
* @ORM\PrePersist
@@ -58,12 +62,12 @@ the current date, only when the entity is first persisted (i.e. inserted):
+ https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
-
diff --git a/doctrine/mapping_model_classes.rst b/doctrine/mapping_model_classes.rst
index 8e0b7b95c0d..5f2715a8c77 100644
--- a/doctrine/mapping_model_classes.rst
+++ b/doctrine/mapping_model_classes.rst
@@ -16,20 +16,13 @@ register the mappings for your model classes.
for one of the ODMs. For reusable bundles, rather than duplicate model classes
just to get the auto-mapping, use the compiler pass.
-.. versionadded:: 2.3
- The base mapping compiler pass was introduced in Symfony 2.3. The Doctrine bundles
- support it from DoctrineBundle >= 1.3.0, MongoDBBundle >= 3.0.0,
- PHPCRBundle >= 1.0.0 and the (unversioned) CouchDBBundle supports the
- compiler pass since the `CouchDB Mapping Compiler Pass pull request`_
- was merged.
-
In your bundle class, write the following code to register the compiler pass.
This one is written for the CmfRoutingBundle, so parts of it will need to
be adapted for your case::
+ use Doctrine\Bundle\CouchDBBundle\DependencyInjection\Compiler\DoctrineCouchDBMappingsPass;
use Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass;
use Doctrine\Bundle\MongoDBBundle\DependencyInjection\Compiler\DoctrineMongoDBMappingsPass;
- use Doctrine\Bundle\CouchDBBundle\DependencyInjection\Compiler\DoctrineCouchDBMappingsPass;
use Doctrine\Bundle\PHPCRBundle\DependencyInjection\Compiler\DoctrinePhpcrMappingsPass;
use Symfony\Cmf\RoutingBundle\Model;
@@ -41,17 +34,17 @@ be adapted for your case::
// ...
$modelDirectory = realpath(__DIR__.'/Resources/config/doctrine/model');
- $mappings = array(
+ $mappings = [
$modelDirectory => Model::class,
- );
+ ];
if (class_exists(DoctrineOrmMappingsPass::class)) {
$container->addCompilerPass(
DoctrineOrmMappingsPass::createXmlMappingDriver(
$mappings,
- array('cmf_routing.model_manager_name'),
+ ['cmf_routing.model_manager_name'],
'cmf_routing.backend_type_orm',
- array('CmfRoutingBundle' => Model::class)
+ ['CmfRoutingBundle' => Model::class]
));
}
@@ -59,9 +52,9 @@ be adapted for your case::
$container->addCompilerPass(
DoctrineMongoDBMappingsPass::createXmlMappingDriver(
$mappings,
- array('cmf_routing.model_manager_name'),
+ ['cmf_routing.model_manager_name'],
'cmf_routing.backend_type_mongodb',
- array('CmfRoutingBundle' => Model::class)
+ ['CmfRoutingBundle' => Model::class]
));
}
@@ -69,9 +62,9 @@ be adapted for your case::
$container->addCompilerPass(
DoctrineCouchDBMappingsPass::createXmlMappingDriver(
$mappings,
- array('cmf_routing.model_manager_name'),
+ ['cmf_routing.model_manager_name'],
'cmf_routing.backend_type_couchdb',
- array('CmfRoutingBundle' => Model::class)
+ ['CmfRoutingBundle' => Model::class]
));
}
@@ -79,9 +72,9 @@ be adapted for your case::
$container->addCompilerPass(
DoctrinePhpcrMappingsPass::createXmlMappingDriver(
$mappings,
- array('cmf_routing.model_manager_name'),
+ ['cmf_routing.model_manager_name'],
'cmf_routing.backend_type_phpcr',
- array('CmfRoutingBundle' => Model::class)
+ ['CmfRoutingBundle' => Model::class]
));
}
}
@@ -122,23 +115,23 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
``DoctrineOrmMappingsPass`` and adapted to use the ``DefaultFileLocator``
instead of the ``SymfonyFileLocator``::
- use Doctrine\Common\Persistence\Mapping\Driver\DefaultFileLocator;
- use Doctrine\ORM\Mapping\Driver\XmlDriver;
use AppBundle\Model;
+ use Doctrine\ORM\Mapping\Driver\XmlDriver;
+ use Doctrine\Persistence\Mapping\Driver\DefaultFileLocator;
// ...
private function buildMappingCompilerPass()
{
- $fileLocator = new Definition(DefaultFileLocator::class, array(
- array(realpath(__DIR__ . '/Resources/config/doctrine-base')),
+ $fileLocator = new Definition(DefaultFileLocator::class, [
+ [realpath(__DIR__ . '/Resources/config/doctrine-base')],
'.orm.xml'
- ));
- $driver = new Definition(XmlDriver::class, array($fileLocator));
+ ]);
+ $driver = new Definition(XmlDriver::class, [$fileLocator]);
return new DoctrineOrmMappingsPass(
$driver,
- array(Model::class),
- array('your_bundle.manager_name'),
+ [Model::class],
+ ['your_bundle.manager_name'],
'your_bundle.orm_enabled'
);
}
@@ -152,5 +145,3 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
the ``SymfonyFileLocator`` will get confused.
Adjust accordingly for the other Doctrine implementations.
-
-.. _`CouchDB Mapping Compiler Pass pull request`: https://github.com/doctrine/DoctrineCouchDBBundle/pull/27
diff --git a/doctrine/mongodb_session_storage.rst b/doctrine/mongodb_session_storage.rst
index fcfecfe3dd2..f097d713beb 100644
--- a/doctrine/mongodb_session_storage.rst
+++ b/doctrine/mongodb_session_storage.rst
@@ -44,9 +44,9 @@ need to change/add some parameters in the main configuration file:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
- http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+ https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
@@ -79,28 +79,28 @@ need to change/add some parameters in the main configuration file:
use Symfony\Component\DependencyInjection\Reference;
use Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler;
- $container->loadFromExtension('framework', array(
- 'session' => array(
+ $container->loadFromExtension('framework', [
+ 'session' => [
// ...
'handler_id' => 'session.handler.mongo',
'cookie_lifetime' => 2592000, // optional, it is set to 30 days here
'gc_maxlifetime' => 2592000, // optional, it is set to 30 days here
- ),
- ));
+ ],
+ ]);
$container->register('mongo_client', \MongoClient::class)
- ->setArguments(array(
+ ->setArguments([
// if using a username and password
- array('mongodb://%mongodb_username%:%mongodb_password%@%mongodb_host%:27017'),
+ ['mongodb://%mongodb_username%:%mongodb_password%@%mongodb_host%:27017'],
// if not using a username and password
- array('mongodb://%mongodb_host%:27017'),
- ));
+ ['mongodb://%mongodb_host%:27017'],
+ ]);
$container->register('session.handler.mongo', MongoDbSessionHandler::class)
- ->setArguments(array(
+ ->setArguments([
new Reference('mongo_client'),
'%mongo.session.options%',
- ));
+ ]);
The parameters used above should be defined somewhere in your application, often in your main
parameters configuration:
@@ -126,9 +126,9 @@ parameters configuration:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
- http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+ https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
@@ -148,10 +148,10 @@ parameters configuration:
use Symfony\Component\DependencyInjection\Reference;
- $container->setParameter('mongo.session.options', array(
+ $container->setParameter('mongo.session.options', [
'database' => 'session_db', // your MongoDB database name
'collection' => 'session', // your MongoDB collection name
- ));
+ ]);
$container->setParameter('mongodb_host', '1.2.3.4'); // your MongoDB server's IP
$container->setParameter('mongodb_username', 'my_username');
$container->setParameter('mongodb_password', 'my_password');
diff --git a/doctrine/multiple_entity_managers.rst b/doctrine/multiple_entity_managers.rst
index d1624a9b307..4fd29b05b14 100644
--- a/doctrine/multiple_entity_managers.rst
+++ b/doctrine/multiple_entity_managers.rst
@@ -69,9 +69,9 @@ The following configuration code shows how you can configure two entity managers
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/doctrine
- http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+ https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
@@ -98,12 +98,12 @@ The following configuration code shows how you can configure two entity managers
-
-
@@ -111,11 +111,11 @@ The following configuration code shows how you can configure two entity managers
.. code-block:: php
- $container->loadFromExtension('doctrine', array(
- 'dbal' => array(
+ $container->loadFromExtension('doctrine', [
+ 'dbal' => [
'default_connection' => 'default',
- 'connections' => array(
- 'default' => array(
+ 'connections' => [
+ 'default' => [
'driver' => 'pdo_mysql',
'host' => '%database_host%',
'port' => '%database_port%',
@@ -123,8 +123,8 @@ The following configuration code shows how you can configure two entity managers
'user' => '%database_user%',
'password' => '%database_password%',
'charset' => 'UTF8',
- ),
- 'customer' => array(
+ ],
+ 'customer' => [
'driver' => 'pdo_mysql',
'host' => '%database_host2%',
'port' => '%database_port2%',
@@ -132,29 +132,29 @@ The following configuration code shows how you can configure two entity managers
'user' => '%database_user2%',
'password' => '%database_password2%',
'charset' => 'UTF8',
- ),
- ),
- ),
+ ],
+ ],
+ ],
- 'orm' => array(
+ 'orm' => [
'default_entity_manager' => 'default',
- 'entity_managers' => array(
- 'default' => array(
+ 'entity_managers' => [
+ 'default' => [
'connection' => 'default',
- 'mappings' => array(
+ 'mappings' => [
'AppBundle' => null,
'AcmeStoreBundle' => null,
- ),
- ),
- 'customer' => array(
+ ],
+ ],
+ 'customer' => [
'connection' => 'customer',
- 'mappings' => array(
+ 'mappings' => [
'AcmeCustomerBundle' => null,
- ),
- ),
- ),
- ),
- ));
+ ],
+ ],
+ ],
+ ],
+ ]);
In this case, you've defined two entity managers and called them ``default``
and ``customer``. The ``default`` entity manager manages entities in the
@@ -173,35 +173,37 @@ When working with multiple connections to create your databases:
.. code-block:: terminal
# Play only with "default" connection
- $ php app/console doctrine:database:create
+ $ php bin/console doctrine:database:create
# Play only with "customer" connection
- $ php app/console doctrine:database:create --connection=customer
+ $ php bin/console doctrine:database:create --connection=customer
When working with multiple entity managers to update your schema:
.. code-block:: terminal
# Play only with "default" mappings
- $ php app/console doctrine:schema:update --force
+ $ php bin/console doctrine:schema:update --force
# Play only with "customer" mappings
- $ php app/console doctrine:schema:update --force --em=customer
+ $ php bin/console doctrine:schema:update --force --em=customer
If you *do* omit the entity manager's name when asking for it,
the default entity manager (i.e. ``default``) is returned::
+ // ...
+
class UserController extends Controller
{
public function indexAction()
{
- // All three return the "default" entity manager
- $entityManager = $this->get('doctrine')->getManager();
- $entityManager = $this->get('doctrine')->getManager('default');
+ // All 3 return the "default" entity manager
+ $entityManager = $this->getDoctrine()->getManager();
+ $entityManager = $this->getDoctrine()->getManager('default');
$entityManager = $this->get('doctrine.orm.default_entity_manager');
// Both of these return the "customer" entity manager
- $customerEntityManager = $this->get('doctrine')->getManager('customer');
+ $customerEntityManager = $this->getDoctrine()->getManager('customer');
$customerEntityManager = $this->get('doctrine.orm.customer_entity_manager');
}
}
@@ -214,25 +216,26 @@ The same applies to repository calls::
use AcmeStoreBundle\Entity\Customer;
use AcmeStoreBundle\Entity\Product;
+ // ...
class UserController extends Controller
{
public function indexAction()
{
// Retrieves a repository managed by the "default" em
- $products = $this->get('doctrine')
+ $products = $this->getDoctrine()
->getRepository(Product::class)
->findAll()
;
// Explicit way to deal with the "default" em
- $products = $this->get('doctrine')
+ $products = $this->getDoctrine()
->getRepository(Product::class, 'default')
->findAll()
;
// Retrieves a repository managed by the "customer" em
- $customers = $this->get('doctrine')
+ $customers = $this->getDoctrine()
->getRepository(Customer::class, 'customer')
->findAll()
;
diff --git a/doctrine/pdo_session_storage.rst b/doctrine/pdo_session_storage.rst
index 5aa8f9e75d5..3c21c61f5a8 100644
--- a/doctrine/pdo_session_storage.rst
+++ b/doctrine/pdo_session_storage.rst
@@ -11,24 +11,20 @@ multiple web server environment.
Symfony has a built-in solution for database session storage called
:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\PdoSessionHandler`.
-To use it, you just need to change some parameters in the main configuration file:
+To use it, first register a new handler service:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
- framework:
- session:
- # ...
- handler_id: session.handler.pdo
-
services:
- session.handler.pdo:
- class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
+ # ...
+
+ Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler:
public: false
arguments:
- - 'mysql:dbname=mydatabase'
+ - 'mysql:dbname=mydatabase; host=myhost; port=myport'
- { db_username: myuser, db_password: mypassword }
.. code-block:: xml
@@ -39,16 +35,12 @@ To use it, you just need to change some parameters in the main configuration fil
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
- http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-
-
+ https://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
- mysql:dbname=mydatabase
+
+ mysql:dbname=mydatabase, host=myhost
myuser
mypassword
@@ -60,23 +52,54 @@ To use it, you just need to change some parameters in the main configuration fil
.. code-block:: php
// app/config/config.php
+ use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
+
+ $storageDefinition = $container->register(PdoSessionHandler::class)
+ ->setArguments([
+ 'mysql:dbname=mydatabase; host=myhost; port=myport',
+ ['db_username' => 'myuser', 'db_password' => 'mypassword'],
+ ])
+ ;
+.. tip::
+
+ Configure the database credentials as
+ :doc:`parameters defined with environment variables `
+ to make your application more secure.
+
+Next, tell Symfony to use your service as the session handler:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ framework:
+ session:
+ # ...
+ handler_id: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
+
+ .. code-block:: xml
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/config.php
use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
// ...
- $container->loadFromExtension('framework', array(
+ $container->loadFromExtension('framework', [
// ...
- 'session' => array(
+ 'session' => [
// ...
- 'handler_id' => 'session.handler.pdo',
- ),
- ));
-
- $container->register('session.handler.pdo', PdoSessionHandler::class)
- ->setArguments(array(
- 'mysql:dbname=mydatabase',
- array('db_username' => 'myuser', 'db_password' => 'mypassword'),
- ));
+ 'handler_id' => PdoSessionHandler::class,
+ ],
+ ]);
Configuring the Table and Column Names
--------------------------------------
@@ -92,12 +115,12 @@ a second array argument to ``PdoSessionHandler``:
# app/config/config.yml
services:
# ...
- session.handler.pdo:
- class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
+
+ Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler:
public: false
arguments:
- - 'mysql:dbname=mydatabase'
- - { db_table: sessions, db_username: myuser, db_password: mypassword }
+ - 'mysql:dbname=mydatabase; host=myhost; port=myport'
+ - { db_table: 'sessions', db_username: 'myuser', db_password: 'mypassword' }
.. code-block:: xml
@@ -106,11 +129,11 @@ a second array argument to ``PdoSessionHandler``:
+ https://symfony.com/schema/dic/services/services-1.0.xsd">
-
- mysql:dbname=mydatabase
+
+ mysql:dbname=mydatabase, host=myhost
sessions
myuser
@@ -123,15 +146,15 @@ a second array argument to ``PdoSessionHandler``:
.. code-block:: php
// app/config/config.php
-
use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
// ...
- $container->register('session.handler.pdo', PdoSessionHandler::class)
- ->setArguments(array(
- 'mysql:dbname=mydatabase',
- array('db_table' => 'sessions', 'db_username' => 'myuser', 'db_password' => 'mypassword'),
- ));
+ $container->register(PdoSessionHandler::class)
+ ->setArguments([
+ 'mysql:dbname=mydatabase; host=myhost; port=myport',
+ ['db_table' => 'sessions', 'db_username' => 'myuser', 'db_password' => 'mypassword']
+ ])
+ ;
These are parameters that you can configure:
@@ -166,8 +189,9 @@ of your project's data, you can use the connection settings from the
.. code-block:: yaml
services:
- session.handler.pdo:
- class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
+ # ...
+
+ Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler:
public: false
arguments:
- 'mysql:host=%database_host%;port=%database_port%;dbname=%database_name%'
@@ -179,10 +203,10 @@ of your project's data, you can use the connection settings from the
+ https://symfony.com/schema/dic/services/services-1.0.xsd">
-
+
mysql:host=%database_host%;port=%database_port%;dbname=%database_name%
%database_user%
@@ -195,10 +219,12 @@ of your project's data, you can use the connection settings from the
.. code-block:: php
// ...
- $storageDefinition = new Definition(PdoSessionHandler::class, array(
- 'mysql:host=%database_host%;port=%database_port%;dbname=%database_name%',
- array('db_username' => '%database_user%', 'db_password' => '%database_password%')
- ));
+ $container->register(PdoSessionHandler::class)
+ ->setArguments([
+ 'mysql:host=%database_host%;port=%database_port%;dbname=%database_name%',
+ ['db_username' => '%database_user%', 'db_password' => '%database_password%']
+ ])
+ ;
.. _example-sql-statements:
@@ -228,8 +254,8 @@ MySQL
`sess_id` VARCHAR(128) NOT NULL PRIMARY KEY,
`sess_data` BLOB NOT NULL,
`sess_time` INTEGER UNSIGNED NOT NULL,
- `sess_lifetime` MEDIUMINT NOT NULL
- ) COLLATE utf8_bin, ENGINE = InnoDB;
+ `sess_lifetime` INTEGER UNSIGNED NOT NULL
+ ) COLLATE utf8mb4_bin, ENGINE = InnoDB;
.. note::
diff --git a/doctrine/registration_form.rst b/doctrine/registration_form.rst
index bfa3b69b450..80aa8eb27e5 100644
--- a/doctrine/registration_form.rst
+++ b/doctrine/registration_form.rst
@@ -43,9 +43,9 @@ With some validation added, your class may look something like this::
namespace AppBundle\Entity;
use Doctrine\ORM\Mapping as ORM;
- use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
use Symfony\Component\Security\Core\User\UserInterface;
+ use Symfony\Component\Validator\Constraints as Assert;
/**
* @ORM\Entity
@@ -95,7 +95,7 @@ With some validation added, your class may look something like this::
public function __construct()
{
- $this->roles = array('ROLE_USER');
+ $this->roles = ['ROLE_USER'];
}
// other properties and methods
@@ -142,7 +142,7 @@ With some validation added, your class may look something like this::
public function getSalt()
{
- // The bcrypt algorithm doesn't require a separate salt.
+ // The bcrypt and argon2i algorithms don't require a separate salt.
// You *may* need a real salt if you choose a different encoder.
return null;
}
@@ -189,12 +189,12 @@ Next, create the form for the ``User`` entity::
use AppBundle\Entity\User;
use Symfony\Component\Form\AbstractType;
- use Symfony\Component\Form\FormBuilderInterface;
- use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Form\Extension\Core\Type\EmailType;
- use Symfony\Component\Form\Extension\Core\Type\TextType;
- use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
+ use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
+ use Symfony\Component\Form\Extension\Core\Type\TextType;
+ use Symfony\Component\Form\FormBuilderInterface;
+ use Symfony\Component\OptionsResolver\OptionsResolver;
class UserType extends AbstractType
{
@@ -203,19 +203,19 @@ Next, create the form for the ``User`` entity::
$builder
->add('email', EmailType::class)
->add('username', TextType::class)
- ->add('plainPassword', RepeatedType::class, array(
+ ->add('plainPassword', RepeatedType::class, [
'type' => PasswordType::class,
- 'first_options' => array('label' => 'Password'),
- 'second_options' => array('label' => 'Repeat Password'),
- ))
+ 'first_options' => ['label' => 'Password'],
+ 'second_options' => ['label' => 'Repeat Password'],
+ ])
;
}
public function configureOptions(OptionsResolver $resolver)
{
- $resolver->setDefaults(array(
+ $resolver->setDefaults([
'data_class' => User::class,
- ));
+ ]);
}
}
@@ -237,18 +237,19 @@ into the database::
// src/AppBundle/Controller/RegistrationController.php
namespace AppBundle\Controller;
- use AppBundle\Form\UserType;
use AppBundle\Entity\User;
- use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+ use AppBundle\Form\UserType;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Request;
+ use Symfony\Component\Routing\Annotation\Route;
+ use Symfony\Component\Security\Core\Encoder\UserPasswordEncoderInterface;
class RegistrationController extends Controller
{
/**
* @Route("/register", name="user_registration")
*/
- public function registerAction(Request $request)
+ public function registerAction(Request $request, UserPasswordEncoderInterface $passwordEncoder)
{
// 1) build the form
$user = new User();
@@ -259,8 +260,7 @@ into the database::
if ($form->isSubmitted() && $form->isValid()) {
// 3) Encode the password (you could also do this via Doctrine listener)
- $password = $this->get('security.password_encoder')
- ->encodePassword($user, $user->getPlainPassword());
+ $password = $passwordEncoder->encodePassword($user, $user->getPlainPassword());
$user->setPassword($password);
// 4) save the User!
@@ -276,7 +276,7 @@ into the database::
return $this->render(
'registration/register.html.twig',
- array('form' => $form->createView())
+ ['form' => $form->createView()]
);
}
}
@@ -300,7 +300,7 @@ encoder in the security configuration:
+ xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
bcrypt
@@ -312,11 +312,11 @@ encoder in the security configuration:
// app/config/security.php
use AppBundle\Entity\User;
- $container->loadFromExtension('security', array(
- 'encoders' => array(
+ $container->loadFromExtension('security', [
+ 'encoders' => [
User::class => 'bcrypt',
- ),
- ));
+ ],
+ ]);
In this case the recommended `bcrypt`_ algorithm is used. If needed, check out
the :ref:`user password encoding ` article.
@@ -341,7 +341,7 @@ the :ref:`user password encoding ` article.
+ xsi:schemaLocation="http://symfony.com/schema/routing https://symfony.com/schema/routing/routing-1.0.xsd">
AppBundle:Registration:register
@@ -351,13 +351,13 @@ the :ref:`user password encoding ` article.
.. code-block:: php
// app/config/routing.php
- use Symfony\Component\Routing\RouteCollection;
use Symfony\Component\Routing\Route;
+ use Symfony\Component\Routing\RouteCollection;
$routes = new RouteCollection();
- $routes->add('user_registration', new Route('/register', array(
+ $routes->add('user_registration', new Route('/register', [
'_controller' => 'AppBundle:Registration:register',
- )));
+ ]));
return $routes;
@@ -366,7 +366,6 @@ Next, create the template:
.. code-block:: html+twig
{# app/Resources/views/registration/register.html.twig #}
-
{{ form_start(form) }}
{{ form_row(form.username) }}
{{ form_row(form.email) }}
@@ -386,7 +385,7 @@ your database schema using this command:
.. code-block:: terminal
- $ php app/console doctrine:schema:update --force
+ $ php bin/console doctrine:schema:update --force
That's it! Head to ``/register`` to try things out!
@@ -431,22 +430,23 @@ To do this, add a ``termsAccepted`` field to your form, but set its
// src/AppBundle/Form/UserType.php
// ...
- use Symfony\Component\Validator\Constraints\IsTrue;
+
use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
use Symfony\Component\Form\Extension\Core\Type\EmailType;
+ use Symfony\Component\Validator\Constraints\IsTrue;
class UserType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder
- ->add('email', EmailType::class);
+ ->add('email', EmailType::class)
// ...
- ->add('termsAccepted', CheckboxType::class, array(
+ ->add('termsAccepted', CheckboxType::class, [
'mapped' => false,
'constraints' => new IsTrue(),
- ))
- );
+ ])
+ ;
}
}
diff --git a/doctrine/repository.rst b/doctrine/repository.rst
index 5afa9d8e911..5428c71bb95 100644
--- a/doctrine/repository.rst
+++ b/doctrine/repository.rst
@@ -25,7 +25,7 @@ To do this, add the repository class name to your entity's mapping definition:
*/
class Product
{
- //...
+ // ...
}
.. code-block:: yaml
@@ -43,7 +43,7 @@ To do this, add the repository class name to your entity's mapping definition:
+ https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
getDoctrine()->getManager();
- $products = $entityManager->getRepository(Product::class)
- ->findAllOrderedByName();
+ public function listAction()
+ {
+ $products = $this->getDoctrine()
+ ->getRepository(Product::class)
+ ->findAllOrderedByName();
+ }
.. note::
diff --git a/doctrine/resolve_target_entity.rst b/doctrine/resolve_target_entity.rst
index 9c5901b354d..543f7711252 100644
--- a/doctrine/resolve_target_entity.rst
+++ b/doctrine/resolve_target_entity.rst
@@ -40,12 +40,11 @@ brevity) to explain how to set up and use the ``ResolveTargetEntityListener``.
A Customer entity::
// src/AppBundle/Entity/Customer.php
-
namespace AppBundle\Entity;
- use Doctrine\ORM\Mapping as ORM;
use Acme\CustomerBundle\Entity\Customer as BaseCustomer;
use Acme\InvoiceBundle\Model\InvoiceSubjectInterface;
+ use Doctrine\ORM\Mapping as ORM;
/**
* @ORM\Entity
@@ -60,11 +59,10 @@ A Customer entity::
An Invoice entity::
// src/Acme/InvoiceBundle/Entity/Invoice.php
-
namespace Acme\InvoiceBundle\Entity;
- use Doctrine\ORM\Mapping AS ORM;
use Acme\InvoiceBundle\Model\InvoiceSubjectInterface;
+ use Doctrine\ORM\Mapping as ORM;
/**
* Represents an Invoice.
@@ -84,7 +82,6 @@ An Invoice entity::
An InvoiceSubjectInterface::
// src/Acme/InvoiceBundle/Model/InvoiceSubjectInterface.php
-
namespace Acme\InvoiceBundle\Model;
/**
@@ -128,9 +125,9 @@ about the replacement:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/doctrine
- http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+ https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
@@ -146,14 +143,14 @@ about the replacement:
use Acme\InvoiceBundle\Model\InvoiceSubjectInterface;
use AppBundle\Entity\Customer;
- $container->loadFromExtension('doctrine', array(
- 'orm' => array(
+ $container->loadFromExtension('doctrine', [
+ 'orm' => [
// ...
- 'resolve_target_entities' => array(
+ 'resolve_target_entities' => [
InvoiceSubjectInterface::class => Customer::class,
- ),
- ),
- ));
+ ],
+ ],
+ ]);
Final Thoughts
--------------
diff --git a/doctrine/reverse_engineering.rst b/doctrine/reverse_engineering.rst
index ec48dc23455..0a48e98c7d2 100644
--- a/doctrine/reverse_engineering.rst
+++ b/doctrine/reverse_engineering.rst
@@ -48,9 +48,7 @@ to a post record thanks to a foreign key constraint.
Before diving into the recipe, be sure your database connection parameters are
correctly setup in the ``app/config/parameters.yml`` file (or wherever your
-database configuration is kept) and that you have initialized a bundle that
-will host your future entity class. In this tutorial it's assumed that an
-AcmeBlogBundle exists and is located under the ``src/Acme/BlogBundle`` folder.
+database configuration is kept).
The first step towards building entity classes from an existing database
is to ask Doctrine to introspect the database and generate the corresponding
@@ -59,10 +57,10 @@ table fields.
.. code-block:: terminal
- $ php app/console doctrine:mapping:import --force AcmeBlogBundle xml
+ $ php bin/console doctrine:mapping:import --force AppBundle xml
This command line tool asks Doctrine to introspect the database and generate
-the XML metadata files under the ``src/Acme/BlogBundle/Resources/config/doctrine``
+the XML metadata files under the ``src/AppBundle/Resources/config/doctrine``
folder of your bundle. This generates two files: ``BlogPost.orm.xml`` and
``BlogComment.orm.xml``.
@@ -75,16 +73,19 @@ The generated ``BlogPost.orm.xml`` metadata file looks as follows:
.. code-block:: xml
-
-
-
-
-
-
+
+
+
+
+
+
Once the metadata files are generated, you can ask Doctrine to build related
@@ -93,7 +94,7 @@ entity classes by executing the following command.
.. code-block:: terminal
// generates entity classes with annotation mappings
- $ php app/console doctrine:mapping:convert annotation ./src
+ $ php bin/console doctrine:mapping:convert annotation ./src
.. caution::
@@ -103,14 +104,12 @@ entity classes by executing the following command.
For example, the newly created ``BlogComment`` entity class looks as follow::
- // src/Acme/BlogBundle/Entity/BlogComment.php
- namespace Acme\BlogBundle\Entity;
+ // src/AppBundle/Entity/BlogComment.php
+ namespace AppBundle\Entity;
use Doctrine\ORM\Mapping as ORM;
/**
- * Acme\BlogBundle\Entity\BlogComment
- *
* @ORM\Table(name="blog_comment")
* @ORM\Entity
*/
@@ -170,4 +169,4 @@ entity in the ``BlogComment`` entity class.
The generated entities are now ready to be used. Have fun!
-.. _`Doctrine tools documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/tools.html#reverse-engineering
+.. _`Doctrine tools documentation`: https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/tools.html#reverse-engineering
diff --git a/email.rst b/email.rst
index 06e537b77e3..35795e83dc2 100644
--- a/email.rst
+++ b/email.rst
@@ -46,8 +46,9 @@ already included:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
- http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+ https://symfony.com/schema/dic/services/services-1.0.xsd
+ http://symfony.com/schema/dic/swiftmailer
+ https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
loadFromExtension('swiftmailer', array(
+ $container->loadFromExtension('swiftmailer', [
'transport' => "%mailer_transport%",
'host' => "%mailer_host%",
'username' => "%mailer_user%",
'password' => "%mailer_password%",
- ));
+ ]);
These values (e.g. ``%mailer_transport%``), are reading from the parameters
that are set in the :ref:`parameters.yml ` file. You
@@ -101,7 +102,7 @@ The Swift Mailer library works by creating, configuring and then sending
of the message and is accessible via the ``mailer`` service. Overall, sending
an email is pretty straightforward::
- public function indexAction($name)
+ public function indexAction($name, \Swift_Mailer $mailer)
{
$message = (new \Swift_Message('Hello Email'))
->setFrom('send@example.com')
@@ -110,23 +111,25 @@ an email is pretty straightforward::
$this->renderView(
// app/Resources/views/Emails/registration.html.twig
'Emails/registration.html.twig',
- array('name' => $name)
+ ['name' => $name]
),
'text/html'
)
- /*
- * If you also want to include a plaintext version of the message
+
+ // you can remove the following code if you don't define a text version for your emails
->addPart(
$this->renderView(
'Emails/registration.txt.twig',
- array('name' => $name)
+ ['name' => $name]
),
'text/plain'
)
- */
;
- $this->get('mailer')->send($message);
+ $mailer->send($message);
+
+ // or, you can also fetch the mailer service this way
+ // $this->get('mailer')->send($message);
return $this->render(...);
}
@@ -135,7 +138,7 @@ To keep things decoupled, the email body has been stored in a template and
rendered with the ``renderView()`` method. The ``registration.html.twig``
template might look something like this:
-.. code-block:: html+jinja
+.. code-block:: html+twig
{# app/Resources/views/Emails/registration.html.twig #}
) }})
-.. versionadded:: 2.7
- The ``absolute_url()`` function was introduced in Symfony 2.7. Prior
- to 2.7, the ``asset()`` function has an argument to enable returning
- an absolute URL.
-
The ``$message`` object supports many more options, such as including attachments,
adding HTML content, and much more. Fortunately, Swift Mailer covers the topic
of `Creating Messages`_ in great detail in its documentation.
diff --git a/email/cloud.rst b/email/cloud.rst
index d7ddbd33f3b..51103f1190d 100644
--- a/email/cloud.rst
+++ b/email/cloud.rst
@@ -12,8 +12,8 @@ option. If setting up and maintaining your own reliable mail server causes
you a headache there's a simple solution: Leverage the cloud to send your
emails.
-This article shows how easy it is to integrate
-`Amazon's Simple Email Service (SES)`_ into Symfony.
+This article shows how to integrate `Amazon's Simple Email Service (SES)`_
+into Symfony.
.. note::
@@ -47,9 +47,9 @@ and complete the configuration with the provided ``username`` and ``password``:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/swiftmailer
- http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+ https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
loadFromExtension('swiftmailer', array(
+ $container->loadFromExtension('swiftmailer', [
'transport' => 'smtp',
'host' => 'email-smtp.us-east-1.amazonaws.com',
'port' => 587,
'encryption' => 'tls',
'username' => 'AWS_SES_SMTP_USERNAME',
'password' => 'AWS_SES_SMTP_PASSWORD',
- ));
+ ]);
The ``port`` and ``encryption`` keys are not present in the Symfony Standard
-Edition configuration by default, but you can simply add them as needed.
+Edition configuration by default, but you can add them if needed.
And that's it, you're ready to start sending emails through the cloud!
diff --git a/email/dev_environment.rst b/email/dev_environment.rst
index 9b79e3f816c..8224eab88c8 100644
--- a/email/dev_environment.rst
+++ b/email/dev_environment.rst
@@ -7,9 +7,9 @@ How to Work with Emails during Development
When developing an application which sends email, you will often
not want to actually send the email to the specified recipient during
development. If you are using the SwiftmailerBundle with Symfony, you
-can easily achieve this through configuration settings without having to
-make any changes to your application's code at all. There are two main
-choices when it comes to handling email during development: (a) disabling the
+can achieve this through configuration settings without having to make
+any changes to your application's code at all. There are two main choices
+when it comes to handling email during development: (a) disabling the
sending of email altogether or (b) sending all email to a specific
address (with optional exceptions).
@@ -38,20 +38,20 @@ will not be sent when you run tests, but will continue to be sent in the
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
- http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+ https://symfony.com/schema/dic/services/services-1.0.xsd
+ http://symfony.com/schema/dic/swiftmailer https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
-
.. code-block:: php
// app/config/config_test.php
- $container->loadFromExtension('swiftmailer', array(
+ $container->loadFromExtension('swiftmailer', [
'disable_delivery' => "true",
- ));
+ ]);
-If you'd also like to disable deliver in the ``dev`` environment, simply
+If you'd also like to disable deliver in the ``dev`` environment,
add this same configuration to the ``config_dev.yml`` file.
.. _sending-to-a-specified-address:
@@ -79,9 +79,9 @@ via the ``delivery_addresses`` option:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/swiftmailer
- http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+ https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
dev@example.com
@@ -91,13 +91,13 @@ via the ``delivery_addresses`` option:
.. code-block:: php
// app/config/config_dev.php
- $container->loadFromExtension('swiftmailer', array(
- 'delivery_addresses' => array("dev@example.com"),
- ));
+ $container->loadFromExtension('swiftmailer', [
+ 'delivery_addresses' => ["dev@example.com"],
+ ]);
Now, suppose you're sending an email to ``recipient@example.com``::
- public function indexAction($name)
+ public function indexAction($name, \Swift_Mailer $mailer)
{
$message = (new \Swift_Message('Hello Email'))
->setFrom('send@example.com')
@@ -105,12 +105,11 @@ Now, suppose you're sending an email to ``recipient@example.com``::
->setBody(
$this->renderView(
'HelloBundle:Hello:email.txt.twig',
- array('name' => $name)
+ ['name' => $name]
)
)
;
-
- $this->get('mailer')->send($message);
+ $mailer->send($message);
return $this->render(...);
}
@@ -146,10 +145,10 @@ by adding the ``delivery_whitelist`` option:
swiftmailer:
delivery_addresses: ['dev@example.com']
delivery_whitelist:
- # all email addresses matching these regexes will be delivered
- # like normal, as well as being sent to dev@example.com
- - '/@specialdomain\.com$/'
- - '/^admin@mydomain\.com$/'
+ # all email addresses matching these regexes will be delivered
+ # like normal, as well as being sent to dev@example.com
+ - '/@specialdomain\.com$/'
+ - '/^admin@mydomain\.com$/'
.. code-block:: xml
@@ -159,9 +158,9 @@ by adding the ``delivery_whitelist`` option:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/swiftmailer
- http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+ https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
loadFromExtension('swiftmailer', array(
+ $container->loadFromExtension('swiftmailer', [
'transport' => 'gmail',
'username' => 'your_gmail_username',
'password' => 'your_gmail_password',
- ));
+ ]);
.. tip::
@@ -81,9 +81,9 @@ In the development configuration file, change the ``transport`` setting to
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/swiftmailer
- http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+ https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
loadFromExtension('swiftmailer', array(
+ $container->loadFromExtension('swiftmailer', [
'transport' => 'gmail',
'username' => '%mailer_user%',
'password' => '%mailer_password%',
- ));
+ ]);
Redefining the Default Configuration Parameters
-----------------------------------------------
-The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
+The ``gmail`` transport is a shortcut that uses the ``smtp`` transport
and sets these options:
============== ==================
@@ -122,7 +122,7 @@ parameters.
If your Gmail account uses 2-Step-Verification, you must `generate an App password`_
and use it as the value of the ``mailer_password`` parameter. You must also ensure
-that you `allow less secure apps to access your Gmail account`_.
+that you `allow less secure applications to access your Gmail account`_.
.. seealso::
@@ -130,4 +130,4 @@ that you `allow less secure apps to access your Gmail account`_.
for more details.
.. _`generate an App password`: https://support.google.com/accounts/answer/185833
-.. _`allow less secure apps to access your Gmail account`: https://support.google.com/accounts/answer/6010255
+.. _`allow less secure applications to access your Gmail account`: https://support.google.com/accounts/answer/6010255
diff --git a/email/spool.rst b/email/spool.rst
index 53622386f49..ca7b89a76fd 100644
--- a/email/spool.rst
+++ b/email/spool.rst
@@ -21,7 +21,7 @@ Spool Using Memory
When you use spooling to store the emails to memory, they will get sent right
before the kernel terminates. This means the email only gets sent if the whole
request got executed without any unhandled exception or any errors. To configure
-swiftmailer with the memory option, use the following configuration:
+Swift Mailer with the memory option, use the following configuration:
.. configuration-block::
@@ -39,21 +39,21 @@ swiftmailer with the memory option, use the following configuration:
+ xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+ http://symfony.com/schema/dic/swiftmailer https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
-
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('swiftmailer', array(
- // ...
- 'spool' => array('type' => 'memory'),
- ));
+ $container->loadFromExtension('swiftmailer', [
+ // ...
+ 'spool' => ['type' => 'memory'],
+ ]);
.. _spool-using-a-file:
@@ -63,7 +63,7 @@ Spool Using Files
When you use the filesystem for spooling, Symfony creates a folder in the given
path for each mail service (e.g. "default" for the default service). This folder
will contain files for each email in the spool. So make sure this directory is
-writable by Symfony (or your webserver/php)!
+writable by Symfony (or your webserver/PHP)!
In order to use the spool with files, use the following configuration:
@@ -86,8 +86,8 @@ In order to use the spool with files, use the following configuration:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
- http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+ https://symfony.com/schema/dic/services/services-1.0.xsd
+ http://symfony.com/schema/dic/swiftmailer https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
loadFromExtension('swiftmailer', array(
- // ...
+ $container->loadFromExtension('swiftmailer', [
+ // ...
- 'spool' => array(
+ 'spool' => [
'type' => 'file',
'path' => '/path/to/spooldir',
- ),
- ));
+ ],
+ ]);
.. tip::
If you want to store the spool somewhere with your project directory,
- remember that you can use the ``%kernel.root_dir%`` parameter to reference
+ remember that you can use the ``%kernel.project_dir%`` parameter to reference
the project's root:
.. code-block:: yaml
- path: '%kernel.root_dir%/spool'
+ path: '%kernel.project_dir%/app/spool'
Now, when your app sends an email, it will not actually be sent but instead
added to the spool. Sending the messages from the spool is done separately.
@@ -125,38 +125,38 @@ There is a console command to send the messages in the spool:
.. code-block:: terminal
- $ php app/console swiftmailer:spool:send --env=prod
+ $ php bin/console swiftmailer:spool:send --env=prod
It has an option to limit the number of messages to be sent:
.. code-block:: terminal
- $ php app/console swiftmailer:spool:send --message-limit=10 --env=prod
+ $ php bin/console swiftmailer:spool:send --message-limit=10 --env=prod
You can also set the time limit in seconds:
.. code-block:: terminal
- $ php app/console swiftmailer:spool:send --time-limit=10 --env=prod
+ $ php bin/console swiftmailer:spool:send --time-limit=10 --env=prod
-Of course you will not want to run this manually in reality. Instead, the
-console command should be triggered by a cron job or scheduled task and run
-at a regular interval.
+In practice you will not want to run this manually. Instead, the console command
+should be triggered by a cron job or scheduled task and run at a regular
+interval.
.. caution::
- When you create a message with SwiftMailer, it generates a ``Swift_Message``
+ When you create a message with Swift Mailer, it generates a ``Swift_Message``
class. If the ``swiftmailer`` service is lazy loaded, it generates instead a
proxy class named ``Swift_Message_``.
If you use the memory spool, this change is transparent and has no impact.
But when using the filesystem spool, the message class is serialized in
a file with the randomized class name. The problem is that this random
- class name changes on every cache clear. So if you send a mail and then you
- clear the cache, the message will not be unserializable.
+ class name changes on every cache clear.
- On the next execution of ``swiftmailer:spool:send`` an error will raise because
- the class ``Swift_Message_`` doesn't exist (anymore).
+ So if you send a mail and then you clear the cache, on the next execution of
+ ``swiftmailer:spool:send`` an error will raise because the class
+ ``Swift_Message_`` doesn't exist (anymore).
The solutions are either to use the memory spool or to load the
``swiftmailer`` service without the ``lazy`` option (see :doc:`/service_container/lazy_services`).
diff --git a/email/testing.rst b/email/testing.rst
index 95df725142c..58ba1cebd13 100644
--- a/email/testing.rst
+++ b/email/testing.rst
@@ -10,9 +10,9 @@ SwiftmailerBundle, which leverages the power of the `Swift Mailer`_ library.
To functionally test that an email was sent, and even assert the email subject,
content or any other headers, you can use :doc:`the Symfony Profiler `.
-Start with an easy controller action that sends an email::
+Start with a controller action that sends an email::
- public function sendEmailAction($name)
+ public function sendEmailAction($name, \Swift_Mailer $mailer)
{
$message = (new \Swift_Message('Hello Email'))
->setFrom('send@example.com')
@@ -20,7 +20,7 @@ Start with an easy controller action that sends an email::
->setBody('You should see me from the profiler!')
;
- $this->get('mailer')->send($message);
+ $mailer->send($message);
return $this->render(...);
}
@@ -28,7 +28,9 @@ Start with an easy controller action that sends an email::
In your functional test, use the ``swiftmailer`` collector on the profiler
to get information about the messages sent on the previous request::
- // src/AppBundle/Tests/Controller/MailControllerTest.php
+ // tests/AppBundle/Controller/MailControllerTest.php
+ namespace Tests\AppBundle\Controller;
+
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
class MailControllerTest extends WebTestCase
diff --git a/event_dispatcher.rst b/event_dispatcher.rst
index 6ee02e6af70..b7835fa778b 100644
--- a/event_dispatcher.rst
+++ b/event_dispatcher.rst
@@ -26,8 +26,8 @@ The most common way to listen to an event is to register an **event listener**::
// src/AppBundle/EventListener/ExceptionListener.php
namespace AppBundle\EventListener;
- use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
class ExceptionListener
@@ -77,8 +77,7 @@ using a special "tag":
# app/config/services.yml
services:
- app.exception_listener:
- class: AppBundle\EventListener\ExceptionListener
+ AppBundle\EventListener\ExceptionListener:
tags:
- { name: kernel.event_listener, event: kernel.exception }
@@ -89,13 +88,11 @@ using a special "tag":
+ https://symfony.com/schema/dic/services/services-1.0.xsd">
-
-
-
+
@@ -105,24 +102,25 @@ using a special "tag":
// app/config/services.php
use AppBundle\EventListener\ExceptionListener;
- $container
- ->register('app.exception_listener', ExceptionListener::class)
- ->addTag('kernel.event_listener', array('event' => 'kernel.exception'))
+ $container->register(ExceptionListener::class)
+ ->addTag('kernel.event_listener', ['event' => 'kernel.exception'])
;
.. note::
There is an optional tag attribute called ``method`` which defines which method
- to execute when the event is triggered. By default the name of the method is
+ to execute when the event is triggered. By default, the name of the method is
``on`` + "camel-cased event name". If the event is ``kernel.exception`` the
method executed by default is ``onKernelException()``.
The other optional tag attribute is called ``priority``, which defaults to
- ``0`` and it controls the order in which listeners are executed (the higher
- the number the earlier a listener is executed). This is useful when you
- need to guarantee that one listener is executed before another. The priorities
- of the internal Symfony listeners usually range from ``-255`` to ``255`` but
- your own listeners can use any positive or negative integer.
+ ``0`` and it controls the order in which listeners are executed for a given
+ event (the higher the number the earlier a listener is executed). This is
+ useful when you need to guarantee that one listener is executed before
+ another. The priorities of the internal Symfony listeners usually range from
+ ``-255`` to ``255`` but your own listeners can use any positive or negative integer.
+
+.. _events-subscriber:
Creating an Event Subscriber
----------------------------
@@ -132,10 +130,12 @@ that defines one or more methods that listen to one or various events. The main
difference with the event listeners is that subscribers always know which events
they are listening to.
-In a given subscriber, different methods can listen to the same event. The order
-in which methods are executed is defined by the ``priority`` parameter of each
-method (the higher the number the earlier the method is called). To learn more
-about event subscribers, read :doc:`/components/event_dispatcher`.
+If different event subscriber methods listen to the same event, their order is
+defined by the ``priority`` parameter. This value is a positive or negative
+integer which defaults to ``0``. The higher the number, the earlier the method
+is called. **Priority is aggregated for all listeners and subscribers**, so your
+methods could be executed before or after the methods defined in other listeners
+and subscribers. To learn more about event subscribers, read :doc:`/components/event_dispatcher`.
The following example shows an event subscriber that defines several methods which
listen to the same ``kernel.exception`` event::
@@ -152,13 +152,13 @@ listen to the same ``kernel.exception`` event::
public static function getSubscribedEvents()
{
// return the subscribed events, their methods and priorities
- return array(
- KernelEvents::EXCEPTION => array(
- array('processException', 10),
- array('logException', 0),
- array('notifyException', -10),
- )
- );
+ return [
+ KernelEvents::EXCEPTION => [
+ ['processException', 10],
+ ['logException', 0],
+ ['notifyException', -10],
+ ],
+ ];
}
public function processException(GetResponseForExceptionEvent $event)
@@ -177,47 +177,17 @@ listen to the same ``kernel.exception`` event::
}
}
-Now, you just need to register the class as a service and add the
-``kernel.event_subscriber`` tag to tell Symfony that this is an event subscriber:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/services.yml
- services:
- app.exception_subscriber:
- class: AppBundle\EventSubscriber\ExceptionSubscriber
- tags:
- - { name: kernel.event_subscriber }
+That's it! Your ``services.yml`` file should already be setup to load services from
+the ``EventSubscriber`` directory. Symfony takes care of the rest.
- .. code-block:: xml
+.. _ref-event-subscriber-configuration:
-
-
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/services.php
- use AppBundle\EventSubscriber\ExceptionSubscriber;
+.. tip::
- $container
- ->register('app.exception_subscriber', ExceptionSubscriber::class)
- ->addTag('kernel.event_subscriber')
- ;
+ If your methods are *not* called when an exception is thrown, double-check that
+ you're :ref:`loading services ` from
+ the ``EventSubscriber`` directory and have :ref:`autoconfigure `
+ enabled. You can also manually add the ``kernel.event_subscriber`` tag.
Request Events, Checking Types
------------------------------
@@ -231,8 +201,6 @@ or a "sub request"::
namespace AppBundle\EventListener;
use Symfony\Component\HttpKernel\Event\GetResponseEvent;
- use Symfony\Component\HttpKernel\HttpKernel;
- use Symfony\Component\HttpKernel\HttpKernelInterface;
class RequestListener
{
@@ -273,14 +241,14 @@ using the console. To show all events and their listeners, run:
.. code-block:: terminal
- $ php app/console debug:event-dispatcher
+ $ php bin/console debug:event-dispatcher
You can get registered listeners for a particular event by specifying
its name:
.. code-block:: terminal
- $ php app/console debug:event-dispatcher kernel.exception
+ $ php bin/console debug:event-dispatcher kernel.exception
Learn more
----------
diff --git a/event_dispatcher/before_after_filters.rst b/event_dispatcher/before_after_filters.rst
index 0ed6588c0e6..4b5a36bd401 100644
--- a/event_dispatcher/before_after_filters.rst
+++ b/event_dispatcher/before_after_filters.rst
@@ -8,10 +8,10 @@ It is quite common in web application development to need some logic to be
executed just before or just after your controller actions acting as filters
or hooks.
-In symfony1, this was achieved with the preExecute and postExecute methods.
-Most major frameworks have similar methods but there is no such thing in Symfony.
-The good news is that there is a much better way to interfere with the
-Request -> Response process using the :doc:`EventDispatcher component `.
+Some web frameworks define methods like ``preExecute()`` and ``postExecute()``,
+but there is no such thing in Symfony. The good news is that there is a much
+better way to interfere with the Request -> Response process using the
+:doc:`EventDispatcher component `.
Token Validation Example
------------------------
@@ -53,7 +53,7 @@ parameters key:
+ https://symfony.com/schema/dic/services/services-1.0.xsd">
@@ -66,17 +66,17 @@ parameters key:
.. code-block:: php
// app/config/config.php
- $container->setParameter('tokens', array(
+ $container->setParameter('tokens', [
'client1' => 'pass1',
'client2' => 'pass2',
- ));
+ ]);
Tag Controllers to Be Checked
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A ``kernel.controller`` listener gets notified on *every* request, right before
-the controller is executed. So, first, you need some way to identify if the
-controller that matches the request needs token validation.
+A ``kernel.controller`` (aka ``KernelEvents::CONTROLLER``) listener gets notified
+on *every* request, right before the controller is executed. So, first, you need
+some way to identify if the controller that matches the request needs token validation.
A clean and easy way is to create an empty interface and make the controllers
implement it::
@@ -104,21 +104,23 @@ A controller that implements this interface simply looks like this::
}
}
-Creating an Event Listener
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Creating an Event Subscriber
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Next, you'll need to create an event listener, which will hold the logic
+Next, you'll need to create an event subscriber, which will hold the logic
that you want to be executed before your controllers. If you're not familiar with
-event listeners, you can learn more about them at :doc:`/event_dispatcher`::
+event subscribers, you can learn more about them at :doc:`/event_dispatcher`::
- // src/AppBundle/EventListener/TokenListener.php
- namespace AppBundle\EventListener;
+ // src/AppBundle/EventSubscriber/TokenSubscriber.php
+ namespace AppBundle\EventSubscriber;
use AppBundle\Controller\TokenAuthenticatedController;
- use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\FilterControllerEvent;
+ use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+ use Symfony\Component\HttpKernel\KernelEvents;
- class TokenListener
+ class TokenSubscriber implements EventSubscriberInterface
{
private $tokens;
@@ -131,92 +133,56 @@ event listeners, you can learn more about them at :doc:`/event_dispatcher`::
{
$controller = $event->getController();
- /*
- * $controller passed can be either a class or a Closure.
- * This is not usual in Symfony but it may happen.
- * If it is a class, it comes in array format
- */
- if (!is_array($controller)) {
- return;
+ // when a controller class defines multiple action methods, the controller
+ // is returned as [$controllerInstance, 'methodName']
+ if (is_array($controller)) {
+ $controller = $controller[0];
}
- if ($controller[0] instanceof TokenAuthenticatedController) {
+ if ($controller instanceof TokenAuthenticatedController) {
$token = $event->getRequest()->query->get('token');
if (!in_array($token, $this->tokens)) {
throw new AccessDeniedHttpException('This action needs a valid token!');
}
}
}
- }
-
-Registering the Listener
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Finally, register your listener as a service and tag it as an event listener.
-By listening on ``kernel.controller``, you're telling Symfony that you want
-your listener to be called just before any controller is executed.
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/services.yml
- services:
- app.tokens.action_listener:
- class: AppBundle\EventListener\TokenListener
- arguments: ['%tokens%']
- tags:
- - { name: kernel.event_listener, event: kernel.controller, method: onKernelController }
- .. code-block:: xml
-
-
-
-
-
-
-
- %tokens%
-
-
-
-
- .. code-block:: php
+ public static function getSubscribedEvents()
+ {
+ return [
+ KernelEvents::CONTROLLER => 'onKernelController',
+ ];
+ }
+ }
- // app/config/services.php
- use AppBundle\EventListener\TokenListener;
+That's it! Your ``services.yml`` file should already be setup to load services from
+the ``EventSubscriber`` directory. Symfony takes care of the rest. Your
+``TokenSubscriber`` ``onKernelController()`` method will be executed on each request.
+If the controller that is about to be executed implements ``TokenAuthenticatedController``,
+token authentication is applied. This lets you have a "before" filter on any controller
+you want.
- $container->register('app.tokens.action_listener', TokenListener::class)
- ->addArgument('%tokens%')
- ->addTag('kernel.event_listener', array(
- 'event' => 'kernel.controller',
- 'method' => 'onKernelController',
- ));
+.. tip::
-With this configuration, your ``TokenListener`` ``onKernelController()`` method
-will be executed on each request. If the controller that is about to be executed
-implements ``TokenAuthenticatedController``, token authentication is
-applied. This lets you have a "before" filter on any controller that you
-want.
+ If your subscriber is *not* called on each request, double-check that
+ you're :ref:`loading services ` from
+ the ``EventSubscriber`` directory and have :ref:`autoconfigure `
+ enabled. You can also manually add the ``kernel.event_subscriber`` tag.
After Filters with the ``kernel.response`` Event
------------------------------------------------
In addition to having a "hook" that's executed *before* your controller, you
can also add a hook that's executed *after* your controller. For this example,
-imagine that you want to add a sha1 hash (with a salt using that token) to
+imagine that you want to add a ``sha1`` hash (with a salt using that token) to
all responses that have passed this token authentication.
-Another core Symfony event - called ``kernel.response`` - is notified on
-every request, but after the controller returns a Response object. Creating
-an "after" listener is as easy as creating a listener class and registering
+Another core Symfony event - called ``kernel.response`` (aka ``KernelEvents::RESPONSE``) -
+is notified on every request, but after the controller returns a Response object.
+Creating an "after" listener is as easy as creating a listener class and registering
it as a service on this event.
-For example, take the ``TokenListener`` from the previous example and first
+For example, take the ``TokenSubscriber`` from the previous example and first
record the authentication token inside the request attributes. This will
serve as a basic flag that this request underwent token authentication::
@@ -235,9 +201,9 @@ serve as a basic flag that this request underwent token authentication::
}
}
-Now, add another method to this class - ``onKernelResponse()`` - that looks
-for this flag on the request object and sets a custom header on the response
-if it's found::
+Now, configure the subscriber to listen to another event and add ``onKernelResponse()``.
+This will look for the ``auth_token`` flag on the request object and set a custom
+header on the response if it's found::
// add the new use statement at the top of your file
use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
@@ -256,58 +222,15 @@ if it's found::
$response->headers->set('X-CONTENT-HASH', $hash);
}
-Finally, a second "tag" is needed in the service definition to notify Symfony
-that the ``onKernelResponse`` event should be notified for the ``kernel.response``
-event:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/services.yml
- services:
- app.tokens.action_listener:
- class: AppBundle\EventListener\TokenListener
- arguments: ['%tokens%']
- tags:
- - { name: kernel.event_listener, event: kernel.controller, method: onKernelController }
- - { name: kernel.event_listener, event: kernel.response, method: onKernelResponse }
-
- .. code-block:: xml
-
-
-
-
-
-
-
- %tokens%
-
-
-
-
- .. code-block:: php
+ public static function getSubscribedEvents()
+ {
+ return [
+ KernelEvents::CONTROLLER => 'onKernelController',
+ KernelEvents::RESPONSE => 'onKernelResponse',
+ ];
+ }
- // app/config/services.php
- use AppBundle\EventListener\TokenListener;
-
- $container->register('app.tokens.action_listener', TokenListener::class)
- ->addArgument('%tokens%')
- ->addTag('kernel.event_listener', array(
- 'event' => 'kernel.controller',
- 'method' => 'onKernelController',
- ))
- ->addTag('kernel.event_listener', array(
- 'event' => 'kernel.response',
- 'method' => 'onKernelResponse',
- ));
-
-That's it! The ``TokenListener`` is now notified before every controller is
+That's it! The ``TokenSubscriber`` is now notified before every controller is
executed (``onKernelController()``) and after every controller returns a response
(``onKernelResponse()``). By making specific controllers implement the ``TokenAuthenticatedController``
interface, your listener knows which controllers it should take action on.
diff --git a/event_dispatcher/class_extension.rst b/event_dispatcher/class_extension.rst
deleted file mode 100644
index 382c8dcf970..00000000000
--- a/event_dispatcher/class_extension.rst
+++ /dev/null
@@ -1,117 +0,0 @@
-.. index::
- single: EventDispatcher
-
-How to Extend a Class without Using Inheritance
-===============================================
-
-To allow multiple classes to add methods to another one, you can define the
-magic ``__call()`` method in the class you want to be extended like this::
-
- class Foo
- {
- // ...
-
- public function __call($method, $arguments)
- {
- // creates an event named 'foo.method_is_not_found'
- $event = new HandleUndefinedMethodEvent($this, $method, $arguments);
- $this->dispatcher->dispatch('foo.method_is_not_found', $event);
-
- // no listener was able to process the event? The method does not exist
- if (!$event->isProcessed()) {
- throw new \Exception(sprintf('Call to undefined method %s::%s.', get_class($this), $method));
- }
-
- // returns the listener returned value
- return $event->getReturnValue();
- }
- }
-
-This uses a special ``HandleUndefinedMethodEvent`` that should also be
-created. This is a generic class that could be reused each time you need to
-use this pattern of class extension::
-
- use Symfony\Component\EventDispatcher\Event;
-
- class HandleUndefinedMethodEvent extends Event
- {
- protected $subject;
- protected $method;
- protected $arguments;
- protected $returnValue;
- protected $isProcessed = false;
-
- public function __construct($subject, $method, $arguments)
- {
- $this->subject = $subject;
- $this->method = $method;
- $this->arguments = $arguments;
- }
-
- public function getSubject()
- {
- return $this->subject;
- }
-
- public function getMethod()
- {
- return $this->method;
- }
-
- public function getArguments()
- {
- return $this->arguments;
- }
-
- /**
- * Sets the value to return and stops other listeners from being notified
- */
- public function setReturnValue($returnValue)
- {
- $this->returnValue = $returnValue;
- $this->isProcessed = true;
- $this->stopPropagation();
- }
-
- public function getReturnValue()
- {
- return $this->returnValue;
- }
-
- public function isProcessed()
- {
- return $this->isProcessed;
- }
- }
-
-Next, create a class that will listen to the ``foo.method_is_not_found`` event
-and *add* the method ``bar()``::
-
- class Bar
- {
- public function onFooMethodIsNotFound(HandleUndefinedMethodEvent $event)
- {
- // only respond to the calls to the 'bar' method
- if ('bar' != $event->getMethod()) {
- // allow another listener to take care of this unknown method
- return;
- }
-
- // the subject object (the foo instance)
- $foo = $event->getSubject();
-
- // the bar method arguments
- $arguments = $event->getArguments();
-
- // ... do something
-
- // set the return value
- $event->setReturnValue($someValue);
- }
- }
-
-Finally, add the new ``bar()`` method to the ``Foo`` class by registering an
-instance of ``Bar`` with the ``foo.method_is_not_found`` event::
-
- $bar = new Bar();
- $dispatcher->addListener('foo.method_is_not_found', array($bar, 'onFooMethodIsNotFound'));
diff --git a/event_dispatcher/method_behavior.rst b/event_dispatcher/method_behavior.rst
index 0356899ebc3..5ea5e74ffab 100644
--- a/event_dispatcher/method_behavior.rst
+++ b/event_dispatcher/method_behavior.rst
@@ -11,45 +11,129 @@ If you want to do something just before, or just after a method is called, you
can dispatch an event respectively at the beginning or at the end of the
method::
- class Foo
+ class CustomMailer
{
// ...
- public function send($foo, $bar)
+ public function send($subject, $message)
{
- // do something before the method
- $event = new FilterBeforeSendEvent($foo, $bar);
- $this->dispatcher->dispatch('foo.pre_send', $event);
+ // dispatch an event before the method
+ $event = new BeforeSendMailEvent($subject, $message);
+ $this->dispatcher->dispatch('mailer.pre_send', $event);
// get $foo and $bar from the event, they may have been modified
- $foo = $event->getFoo();
- $bar = $event->getBar();
+ $subject = $event->getSubject();
+ $message = $event->getMessage();
// the real method implementation is here
$returnValue = ...;
// do something after the method
- $event = new FilterSendReturnValue($returnValue);
- $this->dispatcher->dispatch('foo.post_send', $event);
+ $event = new AfterSendMailEvent($returnValue);
+ $this->dispatcher->dispatch('mailer.post_send', $event);
return $event->getReturnValue();
}
}
-In this example, two events are thrown: ``foo.pre_send``, before the method is
-executed, and ``foo.post_send`` after the method is executed. Each uses a
+In this example, two events are thrown: ``mailer.pre_send``, before the method is
+executed, and ``mailer.post_send`` after the method is executed. Each uses a
custom Event class to communicate information to the listeners of the two
-events. These event classes would need to be created by you and should allow,
-in this example, the variables ``$foo``, ``$bar`` and ``$returnValue`` to be retrieved
-and set by the listeners.
+events. For example, ``BeforeSendMailEvent`` might look like this::
-For example, assuming the ``FilterSendReturnValue`` has a ``setReturnValue()``
-method, one listener might look like this::
+ // src/AppBundle/Event/BeforeSendMailEvent.php
+ namespace AppBundle\Event;
- public function onFooPostSend(FilterSendReturnValue $event)
+ use Symfony\Component\EventDispatcher\Event;
+
+ class BeforeSendMailEvent extends Event
+ {
+ private $subject;
+ private $message;
+
+ public function __construct($subject, $message)
+ {
+ $this->subject = $subject;
+ $this->message = $message;
+ }
+
+ public function getSubject()
+ {
+ return $this->subject;
+ }
+
+ public function setSubject($subject)
+ {
+ $this->subject = $subject;
+ }
+
+ public function getMessage()
+ {
+ return $this->message;
+ }
+
+ public function setMessage($message)
+ {
+ $this->message = $message;
+ }
+ }
+
+And the ``AfterSendMailEvent`` even like this::
+
+ // src/AppBundle/Event/AfterSendMailEvent.php
+ namespace AppBundle\Event;
+
+ use Symfony\Component\EventDispatcher\Event;
+
+ class AfterSendMailEvent extends Event
{
- $returnValue = $event->getReturnValue();
- // modify the original ``$returnValue`` value
+ private $returnValue;
- $event->setReturnValue($returnValue);
+ public function __construct($returnValue)
+ {
+ $this->returnValue = $returnValue;
+ }
+
+ public function getReturnValue()
+ {
+ return $this->returnValue;
+ }
+
+ public function setReturnValue($returnValue)
+ {
+ $this->returnValue = $returnValue;
+ }
+ }
+
+Both events allow you to get some information (e.g. ``getMessage()``) and even change
+that information (e.g. ``setMessage()``).
+
+Now, you can create an event subscriber to hook into this event. For example, you
+could listen to the ``mailer.post_send`` event and change the method's return value::
+
+ // src/AppBundle/EventSubscriber/MailPostSendSubscriber.php
+ namespace AppBundle\EventSubscriber;
+
+ use AppBundle\Event\AfterSendMailEvent;
+ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+ class MailPostSendSubscriber implements EventSubscriberInterface
+ {
+ public function onMailerPostSend(AfterSendMailEvent $event)
+ {
+ $returnValue = $event->getReturnValue();
+ // modify the original ``$returnValue`` value
+
+ $event->setReturnValue($returnValue);
+ }
+
+ public static function getSubscribedEvents()
+ {
+ return [
+ 'mailer.post_send' => 'onMailerPostSend'
+ ];
+ }
}
+
+That's it! Your subscriber should be called automatically (or read more about
+:ref:`event subscriber configuration `).
diff --git a/form/action_method.rst b/form/action_method.rst
index 40a236292b0..06bd7e3a858 100644
--- a/form/action_method.rst
+++ b/form/action_method.rst
@@ -89,10 +89,10 @@ options:
{
// ...
- $form = $this->createForm(TaskType::class, $task, array(
+ $form = $this->createForm(TaskType::class, $task, [
'action' => $this->generateUrl('target_route'),
'method' => 'GET',
- ));
+ ]);
// ...
}
@@ -109,15 +109,15 @@ options:
$formFactory = $formFactoryBuilder->getFormFactory();
- $form = $formFactory->create(TaskType::class, $task, array(
+ $form = $formFactory->create(TaskType::class, $task, [
'action' => '...',
'method' => 'GET',
- ));
+ ]);
Finally, you can override the action and method in the template by passing them
to the ``form()`` or the ``form_start()`` helper functions:
-.. code-block:: html+twig
+.. code-block:: twig
{# app/Resources/views/default/new.html.twig #}
{{ form_start(form, {'action': path('target_route'), 'method': 'GET'}) }}
diff --git a/form/bootstrap4.rst b/form/bootstrap4.rst
new file mode 100644
index 00000000000..6a349fb33e1
--- /dev/null
+++ b/form/bootstrap4.rst
@@ -0,0 +1,119 @@
+Bootstrap 4 Form Theme
+======================
+
+Symfony provides several ways of integrating Bootstrap into your application. The
+most straightforward way is to just add the required ```` and ``
{% endjavascripts %}
-In the ``dev`` environment, each file is still served individually, so that
-you can debug problems more easily. However, in the ``prod`` environment
-(or more specifically, when the ``debug`` flag is ``false``), this will be
-rendered as a single ``script`` tag, which contains the contents of all of
-the JavaScript files.
+In the ``dev`` environment, each file is still served individually, so that you
+can debug problems. However, in the ``prod`` environment (or more specifically,
+when the ``debug`` flag is ``false``), this will be rendered as a single
+``script`` tag, which contains the contents of all of the JavaScript files.
.. tip::
@@ -323,9 +322,9 @@ configuration under the ``assetic`` section. Read more in the
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
@@ -338,16 +337,16 @@ configuration under the ``assetic`` section. Read more in the
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'assets' => array(
- 'jquery_and_ui' => array(
- 'inputs' => array(
+ $container->loadFromExtension('assetic', [
+ 'assets' => [
+ 'jquery_and_ui' => [
+ 'inputs' => [
'@AppBundle/Resources/public/js/thirdparty/jquery.js',
'@AppBundle/Resources/public/js/thirdparty/jquery.ui.js',
- ),
- ),
- ),
- ));
+ ],
+ ],
+ ],
+ ]);
After you have defined the named assets, you can reference them in your templates
with the ``@named_asset`` notation:
@@ -404,27 +403,27 @@ should be defined:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'uglifyjs2' => array(
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'uglifyjs2' => [
'bin' => '/usr/local/bin/uglifyjs',
- ),
- ),
- ));
+ ],
+ ],
+ ]);
Now, to actually *use* the filter on a group of JavaScript files, add it
into your template:
@@ -452,10 +451,11 @@ done from the template and is relative to the public document root:
.. note::
- Symfony also contains a method for cache *busting*, where the final URL
- generated by Assetic contains a query parameter that can be incremented
- via configuration on each deployment. For more information, see the
- :ref:`reference-framework-assets-version` configuration option.
+ Symfony provides various cache busting implementations via the
+ :ref:`version `,
+ :ref:`version_format `, and
+ :ref:`json_manifest_path `
+ configuration options.
.. _assetic-dumping:
@@ -498,7 +498,7 @@ each time you deploy), you should run the following command:
.. code-block:: terminal
- $ php app/console assetic:dump --env=prod --no-debug
+ $ php bin/console assetic:dump --env=prod --no-debug
This will physically generate and write each file that you need (e.g. ``/js/abcd123.js``).
If you update any of your assets, you'll need to run this again to regenerate
@@ -531,26 +531,26 @@ the following change in your ``config_dev.yml`` file:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
-
.. code-block:: php
// app/config/config_dev.php
- $container->loadFromExtension('assetic', array(
+ $container->loadFromExtension('assetic', [
'use_controller' => false,
- ));
+ ]);
Next, since Symfony is no longer generating these assets for you, you'll
need to dump them manually. To do so, run the following command:
.. code-block:: terminal
- $ php app/console assetic:dump
+ $ php bin/console assetic:dump
This physically writes all of the asset files you need for your ``dev``
environment. The big disadvantage is that you need to run this each time
@@ -559,7 +559,7 @@ assets will be regenerated automatically *as they change*:
.. code-block:: terminal
- $ php app/console assetic:watch
+ $ php bin/console assetic:watch
The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior
versions, you had to use the ``--watch`` option of the ``assetic:dump``
diff --git a/frontend/assetic/jpeg_optimize.rst b/frontend/assetic/jpeg_optimize.rst
index 324975cbae7..b4253a0de56 100644
--- a/frontend/assetic/jpeg_optimize.rst
+++ b/frontend/assetic/jpeg_optimize.rst
@@ -37,27 +37,27 @@ using the ``bin`` option of the ``jpegoptim`` filter:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'jpegoptim' => array(
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'jpegoptim' => [
'bin' => 'path/to/jpegoptim',
- ),
- ),
- ));
+ ],
+ ],
+ ]);
It can now be used from a template:
@@ -94,36 +94,36 @@ to ``true``:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'jpegoptim' => array(
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'jpegoptim' => [
'bin' => 'path/to/jpegoptim',
'strip_all' => 'true',
- ),
- ),
- ));
+ ],
+ ],
+ ]);
Lowering Maximum Quality
~~~~~~~~~~~~~~~~~~~~~~~~
By default, the ``jpegoptim`` filter doesn't alter the quality level of the JPEG
image. Use the ``max`` option to configure the maximum quality setting (in a
-scale of ``0`` to ``100``). The reduction in the image file size will of course
+scale of ``0`` to ``100``). The reduction in the image file size will
be at the expense of its quality:
.. configuration-block::
@@ -145,29 +145,29 @@ be at the expense of its quality:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'jpegoptim' => array(
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'jpegoptim' => [
'bin' => 'path/to/jpegoptim',
'max' => '70',
- ),
- ),
- ));
+ ],
+ ],
+ ]);
Shorter Syntax: Twig Function
-----------------------------
@@ -197,17 +197,17 @@ following configuration:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
@@ -215,16 +215,16 @@ following configuration:
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'jpegoptim' => array(
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'jpegoptim' => [
'bin' => 'path/to/jpegoptim',
- ),
- ),
- 'twig' => array(
- 'functions' => array('jpegoptim'),
- ),
- ));
+ ],
+ ],
+ 'twig' => [
+ 'functions' => ['jpegoptim'],
+ ],
+ ]);
The Twig template can now be changed to the following:
@@ -256,18 +256,18 @@ file:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
@@ -275,20 +275,20 @@ file:
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'jpegoptim' => array(
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'jpegoptim' => [
'bin' => 'path/to/jpegoptim',
- ),
- ),
- 'twig' => array(
- 'functions' => array(
- 'jpegoptim' => array(
+ ],
+ ],
+ 'twig' => [
+ 'functions' => [
+ 'jpegoptim' => [
'output' => 'images/*.jpg',
- ),
- ),
- ),
- ));
+ ],
+ ],
+ ],
+ ]);
.. tip::
diff --git a/frontend/assetic/php.rst b/frontend/assetic/php.rst
index bea6f2f8946..3f2db541d2e 100644
--- a/frontend/assetic/php.rst
+++ b/frontend/assetic/php.rst
@@ -46,27 +46,27 @@ and some regular CSS and JavaScript application files (called ``main.css`` and
web/assets/
├── css
- │ ├── main.css
- │ └── code-highlight.css
+ │ ├── main.css
+ │ └── code-highlight.css
├── js
- │ ├── bootstrap.js
- │ ├── jquery.js
- │ └── main.js
+ │ ├── bootstrap.js
+ │ ├── jquery.js
+ │ └── main.js
└── scss
├── bootstrap
- │ ├── _alerts.scss
- │ ├── ...
- │ ├── _variables.scss
- │ ├── _wells.scss
- │ └── mixins
- │ ├── _alerts.scss
- │ ├── ...
- │ └── _vendor-prefixes.scss
+ │ ├── _alerts.scss
+ │ ├── ...
+ │ ├── _variables.scss
+ │ ├── _wells.scss
+ │ └── mixins
+ │ ├── _alerts.scss
+ │ ├── ...
+ │ └── _vendor-prefixes.scss
├── bootstrap.scss
├── font-awesome
- │ ├── _animated.scss
- │ ├── ...
- │ └── _variables.scss
+ │ ├── _animated.scss
+ │ ├── ...
+ │ └── _variables.scss
└── font-awesome.scss
Combining and Minimizing CSS Files and Compiling SCSS Files
@@ -93,12 +93,12 @@ First, configure a new ``scssphp`` Assetic filter:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
-
@@ -106,14 +106,14 @@ First, configure a new ``scssphp`` Assetic filter:
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'scssphp' => array(
- 'formatter' => 'Leafo\ScssPhp\Formatter\Compressed',
- ),
- // ...
- ),
- ));
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'scssphp' => [
+ 'formatter' => 'Leafo\ScssPhp\Formatter\Compressed',
+ ],
+ // ...
+ ],
+ ]);
The value of the ``formatter`` option is the fully qualified class name of the
formatter used by the filter to produce the compiled CSS file. Using the
@@ -136,7 +136,7 @@ by Assetic:
"assets/scss/font-awesome.scss"
"assets/css/*.css"
%}
-
+
{% endstylesheets %}
This simple configuration compiles, combines and minifies the SCSS files into a
@@ -166,12 +166,12 @@ First, configure a new ``jsqueeze`` Assetic filter as follows:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
-
@@ -179,12 +179,12 @@ First, configure a new ``jsqueeze`` Assetic filter as follows:
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'jsqueeze' => null,
- // ...
- ),
- ));
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'jsqueeze' => null,
+ // ...
+ ],
+ ]);
Next, update the code of your Twig template to add the ``{% javascripts %}`` tag
defined by Assetic:
diff --git a/frontend/assetic/uglifyjs.rst b/frontend/assetic/uglifyjs.rst
index 4da6c61e005..af46db3e775 100644
--- a/frontend/assetic/uglifyjs.rst
+++ b/frontend/assetic/uglifyjs.rst
@@ -21,6 +21,16 @@ Install UglifyJS
UglifyJS is available as a `Node.js`_ module. First, you need to `install Node.js`_
and then, decide the installation method: global or local.
+.. caution::
+
+ Some Linux distributions rename the Node.js binary from ``node`` to ``nodejs``.
+ This may result in errors like *"/usr/bin/env: node: No such file or
+ directory"*. You can solve this problem with a symlink:
+
+ .. code-block:: terminal
+
+ $ ln -s /usr/bin/nodejs /usr/bin/node
+
Global Installation
~~~~~~~~~~~~~~~~~~~
@@ -86,29 +96,29 @@ your JavaScripts:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'uglifyjs2' => array(
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'uglifyjs2' => [
// the path to the uglifyjs executable
'bin' => '/usr/local/bin/uglifyjs',
- ),
- ),
- ));
+ ],
+ ],
+ ]);
.. note::
@@ -154,28 +164,28 @@ can configure its location using the ``node`` key:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
+ $container->loadFromExtension('assetic', [
'node' => '/usr/bin/nodejs',
- 'uglifyjs2' => array(
+ 'uglifyjs2' => [
// the path to the uglifyjs executable
'bin' => '/usr/local/bin/uglifyjs',
- ),
- ));
+ ],
+ ]);
Minify your Assets
------------------
@@ -193,7 +203,7 @@ asset tags of your templates to tell Assetic to use the ``uglifyjs2`` filter:
The above example assumes that you have a bundle called AppBundle and your
JavaScript files are in the ``Resources/public/js`` directory under your
- bundle. However you can include your JavaScript files no matter where they are.
+ bundle. However, you can include your JavaScript files no matter where they are.
With the addition of the ``uglifyjs2`` filter to the asset tags above, you
should now see minified JavaScripts coming over the wire much faster.
@@ -258,27 +268,27 @@ Next, add the configuration for this filter:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
- 'filters' => array(
- 'uglifycss' => array(
+ $container->loadFromExtension('assetic', [
+ 'filters' => [
+ 'uglifycss' => [
'bin' => '/usr/local/bin/uglifycss',
- ),
- ),
- ));
+ ],
+ ],
+ ]);
To use the filter for your CSS files, add the filter to the Assetic ``stylesheets``
helper:
@@ -286,7 +296,7 @@ helper:
.. code-block:: html+twig
{% stylesheets 'bundles/App/css/*' filter='uglifycss' filter='cssrewrite' %}
-
+
{% endstylesheets %}
Just like with the ``uglifyjs2`` filter, if you prefix the filter name with
diff --git a/frontend/assetic/yuicompressor.rst b/frontend/assetic/yuicompressor.rst
index c0d4aa8018a..7a96df63642 100644
--- a/frontend/assetic/yuicompressor.rst
+++ b/frontend/assetic/yuicompressor.rst
@@ -14,7 +14,7 @@ How to Minify JavaScripts and Stylesheets with YUI Compressor
Yahoo! provides an excellent utility for minifying JavaScripts and stylesheets
so they travel over the wire faster, the `YUI Compressor`_. Thanks to Assetic,
-you can take advantage of this tool very easily.
+you can take advantage of this tool.
Download the YUI Compressor JAR
-------------------------------
@@ -38,9 +38,9 @@ stylesheets:
# java: '/usr/bin/java'
filters:
yui_css:
- jar: '%kernel.root_dir%/Resources/java/yuicompressor.jar'
+ jar: '%kernel.project_dir%/app/Resources/java/yuicompressor.jar'
yui_js:
- jar: '%kernel.root_dir%/Resources/java/yuicompressor.jar'
+ jar: '%kernel.project_dir%/app/Resources/java/yuicompressor.jar'
.. code-block:: xml
@@ -50,34 +50,34 @@ stylesheets:
xmlns:assetic="http://symfony.com/schema/dic/assetic"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/assetic
- http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
+ https://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
.. code-block:: php
// app/config/config.php
- $container->loadFromExtension('assetic', array(
+ $container->loadFromExtension('assetic', [
// 'java' => '/usr/bin/java',
- 'filters' => array(
- 'yui_css' => array(
- 'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar',
- ),
- 'yui_js' => array(
- 'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar',
- ),
- ),
- ));
+ 'filters' => [
+ 'yui_css' => [
+ 'jar' => '%kernel.project_dir%/app/Resources/java/yuicompressor.jar',
+ ],
+ 'yui_js' => [
+ 'jar' => '%kernel.project_dir%/app/Resources/java/yuicompressor.jar',
+ ],
+ ],
+ ]);
.. note::
@@ -115,7 +115,7 @@ can be repeated to minify your stylesheets.
.. code-block:: html+twig
{% stylesheets '@AppBundle/Resources/public/css/*' filter='yui_css' %}
-
+
{% endstylesheets %}
Disable Minification in Debug Mode
diff --git a/frontend/custom_version_strategy.rst b/frontend/custom_version_strategy.rst
new file mode 100644
index 00000000000..ba56f1f7689
--- /dev/null
+++ b/frontend/custom_version_strategy.rst
@@ -0,0 +1,195 @@
+.. index::
+ single: Asset; Custom Version Strategy
+
+How to Use a Custom Version Strategy for Assets
+===============================================
+
+Asset versioning is a technique that improves the performance of web
+applications by adding a version identifier to the URL of the static assets
+(CSS, JavaScript, images, etc.) When the content of the asset changes, its
+identifier is also modified to force the browser to download it again instead of
+reusing the cached asset.
+
+If your application requires advanced versioning, such as generating the
+version dynamically based on some external information, you can create your
+own version strategy.
+
+.. note::
+
+ Symfony provides various cache busting implementations via the
+ :ref:`version `,
+ :ref:`version_format `, and
+ :ref:`json_manifest_path `
+ configuration options.
+
+Creating your Own Asset Version Strategy
+----------------------------------------
+
+The following example shows how to create a version strategy compatible with
+`gulp-buster`_. This tool defines a configuration file called ``busters.json``
+which maps each asset file to its content hash:
+
+.. code-block:: json
+
+ {
+ "js/script.js": "f9c7afd05729f10f55b689f36bb20172",
+ "css/style.css": "91cd067f79a5839536b46c494c4272d8"
+ }
+
+Implement VersionStrategyInterface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Asset version strategies are PHP classes that implement the
+:class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface`.
+In this example, the constructor of the class takes as arguments the path to
+the manifest file generated by `gulp-buster`_ and the format of the generated
+version string::
+
+ // src/AppBundle/Asset/VersionStrategy/GulpBusterVersionStrategy.php
+ namespace AppBundle\Asset\VersionStrategy;
+
+ use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;
+
+ class GulpBusterVersionStrategy implements VersionStrategyInterface
+ {
+ /**
+ * @var string
+ */
+ private $manifestPath;
+
+ /**
+ * @var string
+ */
+ private $format;
+
+ /**
+ * @var string[]
+ */
+ private $hashes;
+
+ /**
+ * @param string $manifestPath
+ * @param string|null $format
+ */
+ public function __construct($manifestPath, $format = null)
+ {
+ $this->manifestPath = $manifestPath;
+ $this->format = $format ?: '%s?%s';
+ }
+
+ public function getVersion($path)
+ {
+ if (!is_array($this->hashes)) {
+ $this->hashes = $this->loadManifest();
+ }
+
+ return isset($this->hashes[$path]) ? $this->hashes[$path] : '';
+ }
+
+ public function applyVersion($path)
+ {
+ $version = $this->getVersion($path);
+
+ if ('' === $version) {
+ return $path;
+ }
+
+ return sprintf($this->format, $path, $version);
+ }
+
+ private function loadManifest()
+ {
+ return json_decode(file_get_contents($this->manifestPath), true);
+ }
+ }
+
+Register the Strategy Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After creating the strategy PHP class, register it as a Symfony service.
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/services.yml
+ services:
+ AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy:
+ arguments:
+ - "%kernel.project_dir%/busters.json"
+ - "%%s?version=%%s"
+ public: false
+
+ .. code-block:: xml
+
+
+
+
+
+
+ %kernel.project_dir%/busters.json
+ %%s?version=%%s
+
+
+
+
+ .. code-block:: php
+
+ // app/config/services.php
+ use AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy;
+ use Symfony\Component\DependencyInjection\Definition;
+
+ $container->autowire(GulpBusterVersionStrategy::class)
+ ->setArguments(
+ [
+ '%kernel.project_dir%/busters.json',
+ '%%s?version=%%s',
+ ]
+ )->setPublic(false);
+
+Finally, enable the new asset versioning for all the application assets or just
+for some :ref:`asset package ` thanks to
+the :ref:`version_strategy ` option:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ framework:
+ # ...
+ assets:
+ version_strategy: 'AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy'
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/config.php
+ use AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy;
+
+ $container->loadFromExtension('framework', [
+ // ...
+ 'assets' => [
+ 'version_strategy' => GulpBusterVersionStrategy::class,
+ ],
+ ]);
+
+.. _`gulp-buster`: https://www.npmjs.com/package/gulp-buster
diff --git a/frontend/encore/advanced-config.rst b/frontend/encore/advanced-config.rst
new file mode 100644
index 00000000000..2c309d9b466
--- /dev/null
+++ b/frontend/encore/advanced-config.rst
@@ -0,0 +1,224 @@
+Advanced Webpack Config
+=======================
+
+Summarized, Encore generates the Webpack configuration that's used in your
+``webpack.config.js`` file. Encore doesn't support adding all of Webpack's
+`configuration options`_, because many can be added on your own.
+
+For example, suppose you need to resolve automatically a new extension.
+To do that, modify the config after fetching it from Encore:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+
+ var Encore = require('@symfony/webpack-encore');
+
+ // ... all Encore config here
+
+ // fetch the config, then modify it!
+ var config = Encore.getWebpackConfig();
+
+ // add an extension
+ config.resolve.extensions.push('json');
+
+ // export the final config
+ module.exports = config;
+
+But be careful not to accidentally override any config from Encore:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ // ...
+
+ // GOOD - this modifies the config.resolve.extensions array
+ config.resolve.extensions.push('json');
+
+ // BAD - this replaces any extensions added by Encore
+ // config.resolve.extensions = ['json'];
+
+Configuring Watching Options and Polling
+----------------------------------------
+
+Encore provides the method ``configureWatchOptions()`` to configure
+`Watching Options`_ when running ``encore dev --watch`` or ``encore dev-server``:
+
+.. code-block:: javascript
+
+ Encore.configureWatchOptions(function(watchOptions) {
+ // enable polling and check for changes every 250ms
+ // polling is useful when running Encore inside a Virtual Machine
+ watchOptions.poll = 250;
+ });
+
+Defining Multiple Webpack Configurations
+----------------------------------------
+
+Webpack supports passing an `array of configurations`_, which are processed in
+parallel. Webpack Encore includes a ``reset()`` object allowing to reset the
+state of the current configuration to build a new one:
+
+.. code-block:: javascript
+
+ // define the first configuration
+ Encore
+ .setOutputPath('web/build/first_build/')
+ .setPublicPath('/build/first_build')
+ .addEntry('app', './assets/js/app.js')
+ .addStyleEntry('global', './assets/css/global.scss')
+ .enableSassLoader()
+ .autoProvidejQuery()
+ .enableSourceMaps(!Encore.isProduction())
+ ;
+
+ // build the first configuration
+ const firstConfig = Encore.getWebpackConfig();
+
+ // Set a unique name for the config (needed later!)
+ firstConfig.name = 'firstConfig';
+
+ // reset Encore to build the second config
+ Encore.reset();
+
+ // define the second configuration
+ Encore
+ .setOutputPath('web/build/second_build/')
+ .setPublicPath('/build/second_build')
+ .addEntry('mobile', './assets/js/mobile.js')
+ .addStyleEntry('mobile', './assets/css/mobile.less')
+ .enableLessLoader()
+ .enableSourceMaps(!Encore.isProduction())
+ ;
+
+ // build the second configuration
+ const secondConfig = Encore.getWebpackConfig();
+
+ // Set a unique name for the config (needed later!)
+ secondConfig.name = 'secondConfig';
+
+ // export the final configuration as an array of multiple configurations
+ module.exports = [firstConfig, secondConfig];
+
+When running Encore, both configurations will be built in parallel. If you
+prefer to build configs separately, pass the ``--config-name`` option:
+
+.. code-block:: terminal
+
+ $ yarn encore dev --config-name firstConfig
+
+Next, define the output directories of each build:
+
+.. code-block:: yaml
+
+ # app/config/config.yml
+ webpack_encore:
+ output_path: '%kernel.project_dir%/web/default_build'
+ builds:
+ firstConfig: '%kernel.project_dir%/web/first_build'
+ secondConfig: '%kernel.project_dir%/web/second_build'
+
+Finally, use the third optional parameter of the ``encore_entry_*_tags()``
+functions to specify which build to use:
+
+.. code-block:: twig
+
+ {# Using the entrypoints.json file located in ./web/first_build #}
+ {{ encore_entry_script_tags('app', null, 'firstConfig') }}
+ {{ encore_entry_link_tags('global', null, 'firstConfig') }}
+
+ {# Using the entrypoints.json file located in ./web/second_build #}
+ {{ encore_entry_script_tags('mobile', null, 'secondConfig') }}
+ {{ encore_entry_link_tags('mobile', null, 'secondConfig') }}
+
+Generating a Webpack Configuration Object without using the Command-Line Interface
+----------------------------------------------------------------------------------
+
+Ordinarily you would use your ``webpack.config.js`` file by calling Encore
+from the command-line interface. But sometimes, having access to the generated
+Webpack configuration can be required by tools that don't use Encore (for
+instance a test-runner such as `Karma`_).
+
+The problem is that if you try generating that Webpack configuration object
+without using the ``encore`` command you will encounter the following error:
+
+.. code-block:: text
+
+ Error: Encore.setOutputPath() cannot be called yet because the runtime environment doesn't appear to be configured. Make sure you're using the encore executable or call Encore.configureRuntimeEnvironment() first if you're purposely not calling Encore directly.
+
+The reason behind that message is that Encore needs to know a few things before
+being able to create a configuration object, the most important one being what
+the target environment is.
+
+To solve this issue you can use ``configureRuntimeEnvironment``. This method
+must be called from a JavaScript file **before** requiring ``webpack.config.js``.
+
+For instance:
+
+.. code-block:: javascript
+
+ const Encore = require('@symfony/webpack-encore');
+
+ // Set the runtime environment
+ Encore.configureRuntimeEnvironment('dev');
+
+ // Retrieve the Webpack configuration object
+ const webpackConfig = require('./webpack.config');
+
+If needed, you can also pass to that method all the options that you would
+normally use from the command-line interface:
+
+.. code-block:: javascript
+
+ Encore.configureRuntimeEnvironment('dev-server', {
+ // Same options you would use with the
+ // CLI utility, with their name in camelCase.
+ https: true,
+ keepPublicPath: true,
+ });
+
+Having the full control on Loaders Rules
+----------------------------------------
+
+The method ``configureLoaderRule()`` provides a clean way to configure Webpack loaders rules (``module.rules``, see `Configuration `_).
+
+This is a low-level method. All your modifications will be applied just before pushing the loaders rules to Webpack.
+It means that you can override the default configuration provided by Encore, which may break things. Be careful when using it.
+
+One use might be to configure the ``eslint-loader`` to lint Vue files too.
+The following code is equivalent:
+
+.. code-block:: javascript
+
+ // Manually
+ const webpackConfig = Encore.getWebpackConfig();
+
+ const eslintLoader = webpackConfig.module.rules.find(rule => rule.loader === 'eslint-loader');
+ eslintLoader.test = /\.(jsx?|vue)$/;
+
+ return webpackConfig;
+
+ // Using Encore.configureLoaderRule()
+ Encore.configureLoaderRule('eslint', loaderRule => {
+ loaderRule.test = /\.(jsx?|vue)$/
+ });
+
+ return Encore.getWebpackConfig();
+
+The following loaders are configurable with ``configureLoaderRule()``:
+ - ``javascript`` (alias ``js``)
+ - ``css``
+ - ``images``
+ - ``fonts``
+ - ``sass`` (alias ``scss``)
+ - ``less``
+ - ``stylus``
+ - ``vue``
+ - ``eslint``
+ - ``typescript`` (alias ``ts``)
+ - ``handlebars``
+
+.. _`configuration options`: https://webpack.js.org/configuration/
+.. _`array of configurations`: https://github.com/webpack/docs/wiki/configuration#multiple-configurations
+.. _`Karma`: https://karma-runner.github.io
+.. _`Watching Options`: https://webpack.js.org/configuration/watch/#watchoptions
diff --git a/frontend/encore/babel.rst b/frontend/encore/babel.rst
new file mode 100644
index 00000000000..7f10688b150
--- /dev/null
+++ b/frontend/encore/babel.rst
@@ -0,0 +1,65 @@
+Configuring Babel
+=================
+
+`Babel`_ is automatically configured for all ``.js`` and ``.jsx`` files via the
+``babel-loader`` with sensible defaults (e.g. with the ``@babel/preset-env`` and
+``@babel/preset-react`` if requested).
+
+Need to extend the Babel configuration further? The easiest way is via
+``configureBabel()``:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+
+ .configureBabel(function(babelConfig) {
+ // add additional presets
+ babelConfig.presets.push('@babel/preset-flow');
+
+ // no plugins are added by default, but you can add some
+ babelConfig.plugins.push('styled-jsx/babel');
+ }, {
+ // node_modules is not processed through Babel by default
+ // but you can whitelist specific modules to process
+ includeNodeModules: ['foundation-sites'],
+
+ // or completely control the exclude rule (note that you
+ // can't use both "includeNodeModules" and "exclude" at
+ // the same time)
+ exclude: /bower_components/
+ })
+ ;
+
+Configuring Browser Targets
+---------------------------
+
+The ``@babel/preset-env`` preset rewrites your JavaScript so that the final syntax
+will work in whatever browsers you want. To configure the browsers that you need
+to support, see :ref:`browserslist_package_config`.
+
+After changing your "browserslist" config, you will need to manually remove the babel
+cache directory:
+
+.. code-block:: terminal
+
+ # On Unix run this command. On Windows, clear this directory manually
+ $ rm -rf node_modules/.cache/babel-loader/
+
+Creating a ``.babelrc`` File
+----------------------------
+
+Instead of calling ``configureBabel()``, you could create a ``.babelrc`` file
+at the root of your project. This is a more "standard" way of configuring
+Babel, but it has a downside: as soon as a ``.babelrc`` file is present,
+**Encore can no longer add any Babel configuration for you**. For example,
+if you call ``Encore.enableReactPreset()``, the ``react`` preset will *not*
+automatically be added to Babel: you must add it yourself in ``.babelrc``.
+
+As soon as a ``.babelrc`` file is present, it will take priority over the Babel
+configuration added by Encore.
+
+.. _`Babel`: http://babeljs.io/
diff --git a/frontend/encore/bootstrap.rst b/frontend/encore/bootstrap.rst
new file mode 100644
index 00000000000..ff281f588ac
--- /dev/null
+++ b/frontend/encore/bootstrap.rst
@@ -0,0 +1,81 @@
+Using Bootstrap CSS & JS
+========================
+
+Want to use Bootstrap (or something similar) in your project? No problem!
+First, install it. To be able to customize things further, we'll install
+``bootstrap``:
+
+.. code-block:: terminal
+
+ $ yarn add bootstrap --dev
+
+Importing Bootstrap Styles
+--------------------------
+
+Now that ``bootstrap`` lives in your ``node_modules/`` directory, you can
+import it from any Sass or JavaScript file. For example, if you already have
+a ``global.scss`` file, import it from there:
+
+.. code-block:: scss
+
+ // assets/css/global.scss
+
+ // customize some Bootstrap variables
+ $primary: darken(#428bca, 20%);
+
+ // the ~ allows you to reference things in node_modules
+ @import "~bootstrap/scss/bootstrap";
+
+That's it! This imports the ``node_modules/bootstrap/scss/bootstrap.scss``
+file into ``global.scss``. You can even customize the Bootstrap variables first!
+
+.. tip::
+
+ If you don't need *all* of Bootstrap's features, you can include specific files
+ in the ``bootstrap`` directory instead - e.g. ``~bootstrap/scss/alert``.
+
+Importing Bootstrap JavaScript
+------------------------------
+
+Bootstrap JavaScript requires jQuery and Popper.js, so make sure you have this installed:
+
+.. code-block:: terminal
+
+ $ yarn add jquery popper.js --dev
+
+Now, require bootstrap from any of your JavaScript files:
+
+.. code-block:: javascript
+
+ // app.js
+
+ const $ = require('jquery');
+ // this "modifies" the jquery module: adding behavior to it
+ // the bootstrap module doesn't export/return anything
+ require('bootstrap');
+
+ // or you can include specific pieces
+ // require('bootstrap/js/dist/tooltip');
+ // require('bootstrap/js/dist/popover');
+
+ $(document).ready(function() {
+ $('[data-toggle="popover"]').popover();
+ });
+
+Using other Bootstrap / jQuery Plugins
+--------------------------------------
+
+If you need to use jQuery plugins that work well with jQuery, you may need to use
+Encore's :ref:`autoProvidejQuery() ` method so that
+these plugins know where to find jQuery. Then, you can include the needed JavaScript
+and CSS like normal:
+
+.. code-block:: javascript
+
+ // ...
+
+ // require the JavaScript
+ require('bootstrap-star-rating');
+ // require 2 CSS files needed
+ require('bootstrap-star-rating/css/star-rating.css');
+ require('bootstrap-star-rating/themes/krajee-svg/theme.css');
diff --git a/frontend/encore/cdn.rst b/frontend/encore/cdn.rst
new file mode 100644
index 00000000000..0c486f06057
--- /dev/null
+++ b/frontend/encore/cdn.rst
@@ -0,0 +1,47 @@
+Using a CDN
+===========
+
+Are you deploying to a CDN? That's awesome :) Once you've made sure that your
+built files are uploaded to the CDN, configure it in Encore:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ .setOutputPath('web/build/')
+ // in dev mode, don't use the CDN
+ .setPublicPath('/build');
+ // ...
+ ;
+
+ + if (Encore.isProduction()) {
+ + Encore.setPublicPath('https://my-cool-app.com.global.prod.fastly.net');
+ +
+ + // guarantee that the keys in manifest.json are *still*
+ + // prefixed with build/
+ + // (e.g. "build/dashboard.js": "https://my-cool-app.com.global.prod.fastly.net/dashboard.js")
+ + Encore.setManifestKeyPrefix('build/');
+ + }
+
+That's it! Internally, Webpack will now know to load assets from your CDN -
+e.g. ``https://my-cool-app.com.global.prod.fastly.net/dashboard.js``.
+
+.. note::
+
+ It's still your responsibility to put your assets on the CDN - e.g. by
+ uploading them or by using "origin pull", where your CDN pulls assets
+ directly from your web server.
+
+You *do* need to make sure that the ``script`` and ``link`` tags you include on your
+pages also use the CDN. Fortunately, the
+:ref:`entrypoints.json ` paths are updated
+to include the full URL to the CDN.
+
+If you are using ``Encore.enableIntegrityHashes()`` and your CDN and your domain
+are not the `same-origin`_, you may need to set the ``crossorigin`` option in
+your webpack_encore.yaml configuration to ``anonymous`` or ``use-credentials``
+to overcome CORS errors.
+
+.. _`same-origin`: https://en.wikipedia.org/wiki/Same-origin_policy
diff --git a/frontend/encore/code-splitting.rst b/frontend/encore/code-splitting.rst
new file mode 100644
index 00000000000..ffbfe8b4d28
--- /dev/null
+++ b/frontend/encore/code-splitting.rst
@@ -0,0 +1,64 @@
+Async Code Splitting
+====================
+
+When you require/import a JavaScript or CSS module, Webpack compiles that code into
+the final JavaScript or CSS file. Usually, that's exactly what you want. But what
+if you only need to use a piece of code under certain conditions? For example,
+what if you want to use `video.js`_ to play a video, but only once a user has
+clicked a link:
+
+.. code-block:: javascript
+
+ // assets/js/app.js
+
+ import $ from 'jquery';
+ // a fictional "large" module (e.g. it imports video.js internally)
+ import VideoPlayer from './components/VideoPlayer';
+
+ $('.js-open-video').on('click', function() {
+ // use the larger VideoPlayer module
+ const player = new VideoPlayer('some-element');
+ });
+
+In this example, the VideoPlayer module and everything it imports will be packaged
+into the final, built JavaScript file, even though it may not be very common for
+someone to actually need it. A better solution is to use `dynamic imports`_: load
+the code via AJAX when it's needed:
+
+.. code-block:: javascript
+
+ // assets/js/app.js
+
+ import $ from 'jquery';
+
+ $('.js-open-video').on('click', function() {
+ // you could start a loading animation here
+
+ // use import() as a function - it returns a Promise
+ import('./components/VideoPlayer').then(({ default: VideoPlayer }) => {
+ // you could stop a loading animation here
+
+ // use the larger VideoPlayer module
+ const player = new VideoPlayer('some-element');
+
+ }).catch(error => 'An error occurred while loading the component');
+ });
+
+By using ``import()`` like a function, the module will be downloaded async and
+the ``.then()`` callback will be executed when it's finished. The ``VideoPlayer``
+argument to the callback will be the loaded module. In other words, it works like
+normal AJAX calls! Behind the scenes, Webpack will package the ``VideoPlayer`` module
+into a separate file (e.g. ``0.js``) so it can be downloaded. All the details are
+handled for you.
+
+The ``{ default: VideoPlayer }`` part may look strange. When using the async
+import, your ``.then()`` callback is passed an object, where the *actual* module
+is on a ``.default`` key. There are reasons why this is done, but it does look
+quirky. The ``{ default: VideoPlayer }`` code makes sure that the ``VideoPlayer``
+module we want is read from this ``.default`` property.
+
+For more details and configuration options, see `dynamic imports`_ on Webpack's
+documentation.
+
+.. _`video.js`: https://videojs.com/
+.. _`dynamic imports`: https://webpack.js.org/guides/code-splitting/#dynamic-imports
diff --git a/frontend/encore/copy-files.rst b/frontend/encore/copy-files.rst
new file mode 100644
index 00000000000..c8d3edbb243
--- /dev/null
+++ b/frontend/encore/copy-files.rst
@@ -0,0 +1,71 @@
+Copying & Referencing Images
+============================
+
+Need to reference a static file - like the path to an image for an ``img`` tag?
+That can be tricky if you store your assets outside of the public document root.
+Fortunately, depending on your situation, there is a solution!
+
+Referencing Images from Inside a Webpacked JavaScript File
+----------------------------------------------------------
+
+To reference an image tag from inside a JavaScript file, *require* the file:
+
+.. code-block:: javascript
+
+ // assets/js/app.js
+
+ // returns the final, public path to this file
+ // path is relative to this file - e.g. assets/images/logo.png
+ const logoPath = require('../images/logo.png');
+
+ var html = `
`;
+
+When you ``require`` (or ``import``) an image file, Webpack copies it into your
+output directory and returns the final, *public* path to that file.
+
+Referencing Image files from a Template
+---------------------------------------
+
+To reference an image file from outside of a JavaScript file that's processed by
+Webpack - like a template - you can use the ``copyFiles()`` method to copy those
+files into your final output directory.
+
+.. code-block:: diff
+
+ // webpack.config.js
+
+ Encore
+ // ...
+ .setOutputPath('web/build/')
+
+ + .copyFiles({
+ + from: './assets/images',
+ +
+ + // optional target path, relative to the output dir
+ + //to: 'images/[path][name].[ext]',
+ +
+ + // if versioning is enabled, add the file hash too
+ + //to: 'images/[path][name].[hash:8].[ext]',
+ +
+ + // only copy files matching this pattern
+ + //pattern: /\.(png|jpg|jpeg)$/
+ + })
+
+This will copy all files from ``assets/images`` into ``web/build`` (the output
+path). If you have :doc:`versioning enabled `, the copied files will
+include a hash based on their content.
+
+To render inside Twig, use the ``asset()`` function:
+
+.. code-block:: html+twig
+
+ {# assets/images/logo.png was copied to web/build/logo.png #}
+  }})
+
+ {# assets/images/subdir/logo.png was copied to web/build/subdir/logo.png #}
+  }})
+
+Make sure you've enabled the :ref:`json_manifest_path ` option,
+which tells the ``asset()`` function to read the final paths from the ``manifest.json``
+file. If you're not sure what path argument to pass to the ``asset()`` function,
+find the file in ``manifest.json`` and use the *key* as the argument.
diff --git a/frontend/encore/css-preprocessors.rst b/frontend/encore/css-preprocessors.rst
new file mode 100644
index 00000000000..6b70e8f38cb
--- /dev/null
+++ b/frontend/encore/css-preprocessors.rst
@@ -0,0 +1,33 @@
+CSS Preprocessors: Sass, LESS, Stylus, etc.
+===========================================
+
+To use the Sass, LESS or Stylus pre-processors, enable the one you want in ``webpack.config.js``:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+
+ // enable just the one you want
+
+ // processes files ending in .scss or .sass
+ .enableSassLoader()
+
+ // processes files ending in .less
+ .enableLessLoader()
+
+ // processes files ending in .styl
+ .enableStylusLoader()
+ ;
+
+Then restart Encore. When you do, it will give you a command you can run to
+install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+You can also pass configuration options to each of the loaders. See the
+`Encore's index.js file`_ for detailed documentation.
+
+.. _`Encore's index.js file`: https://github.com/symfony/webpack-encore/blob/master/index.js
diff --git a/frontend/encore/custom-loaders-plugins.rst b/frontend/encore/custom-loaders-plugins.rst
new file mode 100644
index 00000000000..66ce1f7c5cc
--- /dev/null
+++ b/frontend/encore/custom-loaders-plugins.rst
@@ -0,0 +1,66 @@
+Adding Custom Loaders & Plugins
+===============================
+
+Adding Custom Loaders
+---------------------
+
+Encore already comes with a variety of different loaders out of the box,
+but if there is a specific loader that you want to use that is not currently supported, you
+can add your own loader through the ``addLoader`` function.
+The ``addLoader`` takes any valid webpack rules config.
+
+If, for example, you want to add the `handlebars-loader`_, call ``addLoader`` with
+your loader config
+
+.. code-block:: javascript
+
+ Encore
+ // ...
+ .addLoader({ test: /\.handlebars$/, loader: 'handlebars-loader' })
+ ;
+
+Since the loader config accepts any valid Webpack rules object, you can pass any
+additional information your need for the loader
+
+.. code-block:: javascript
+
+ Encore
+ // ...
+ .addLoader({
+ test: /\.handlebars$/,
+ loader: 'handlebars-loader',
+ options: {
+ helperDirs: [
+ __dirname + '/helpers1',
+ __dirname + '/helpers2',
+ ],
+ partialDirs: [
+ path.join(__dirname, 'templates', 'partials')
+ ]
+ }
+ })
+ ;
+
+Adding Custom Plugins
+---------------------
+
+Encore uses a variety of different `plugins`_ internally. But, you can add your own
+via the ``addPlugin()`` method. For example, if you use `Moment.js`_, you might want
+to use the `IgnorePlugin`_ (see `moment/moment#2373`_):
+
+.. code-block:: diff
+
+ // webpack.config.js
+ + var webpack = require('webpack');
+
+ Encore
+ // ...
+
+ + .addPlugin(new webpack.IgnorePlugin(/^\.\/locale$/, /moment$/))
+ ;
+
+.. _`handlebars-loader`: https://github.com/pcardune/handlebars-loader
+.. _`plugins`: https://webpack.js.org/plugins/
+.. _`Moment.js`: https://momentjs.com/
+.. _`IgnorePlugin`: https://webpack.js.org/plugins/ignore-plugin/
+.. _`moment/moment#2373`: https://github.com/moment/moment/issues/2373
diff --git a/frontend/encore/dev-server.rst b/frontend/encore/dev-server.rst
new file mode 100644
index 00000000000..4fbb0e1f879
--- /dev/null
+++ b/frontend/encore/dev-server.rst
@@ -0,0 +1,99 @@
+Using webpack-dev-server and HMR
+================================
+
+While developing, instead of using ``yarn encore dev --watch``, you can use the
+`webpack-dev-server`_:
+
+.. code-block:: terminal
+
+ $ yarn encore dev-server
+
+This serves the built assets from a new server at ``http://localhost:8080`` (it does
+not actually write any files to disk). This means your ``script`` and ``link`` tags
+need to change to point to this.
+
+If you're using the ``encore_entry_script_tags()`` and ``encore_entry_link_tags()``
+Twig shortcuts (or are :ref:`processing your assets through entrypoints.json `
+in some other way), you're done: the paths in your templates will automatically point
+to the dev server.
+
+The ``dev-server`` command supports all the options defined by `webpack-dev-server`_.
+You can set these options via command line options:
+
+.. code-block:: terminal
+
+ $ yarn encore dev-server --https --port 9000
+
+You can also set these options using the ``Encore.configureDevServerOptions()``
+method in your ``webpack.config.js`` file:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+
+ .configureDevServerOptions(options => {
+ options.https = {
+ key: '/path/to/server.key',
+ cert: '/path/to/server.crt',
+ }
+ })
+ ;
+
+.. versionadded:: 0.28.4
+
+ The ``Encore.configureDevServerOptions()`` method was introduced in Encore 0.28.4.
+
+Hot Module Replacement HMR
+--------------------------
+
+Encore *does* support `HMR`_ for :doc:`Vue.js `, but
+does *not* work for styles anywhere at this time. To activate it, pass the ``--hot``
+option:
+
+.. code-block:: terminal
+
+ $ ./node_modules/.bin/encore dev-server --hot
+
+If you want to use SSL with self-signed certificates, add the ``--https``,
+``--pfx=``, and ``--allowed-hosts`` options to the ``dev-server`` command in
+the ``package.json`` file:
+
+.. code-block:: diff
+
+ {
+ ...
+ "scripts": {
+ - "dev-server": "encore dev-server",
+ + "dev-server": "encore dev-server --https --pfx=$HOME/.symfony/certs/default.p12 --allowed-hosts=mydomain.wip",
+ ...
+ }
+ }
+
+If you experience issues related to CORS (Cross Origin Resource Sharing), add
+the ``--disable-host-check`` and ``--port`` options to the ``dev-server``
+command in the ``package.json`` file:
+
+.. code-block:: diff
+
+ {
+ ...
+ "scripts": {
+ - "dev-server": "encore dev-server",
+ + "dev-server": "encore dev-server --port 8080 --disable-host-check",
+ ...
+ }
+ }
+
+.. caution::
+
+ Beware that `it's not recommended to disable host checking`_ in general, but
+ here it's required to solve the CORS issue.
+
+
+.. _`webpack-dev-server`: https://webpack.js.org/configuration/dev-server/
+.. _`HMR`: https://webpack.js.org/concepts/hot-module-replacement/
+.. _`it's not recommended to disable host checking`: https://webpack.js.org/configuration/dev-server/#devserverdisablehostcheck
diff --git a/frontend/encore/faq.rst b/frontend/encore/faq.rst
new file mode 100644
index 00000000000..48c8a07b88d
--- /dev/null
+++ b/frontend/encore/faq.rst
@@ -0,0 +1,170 @@
+FAQ and Common Issues
+=====================
+
+.. _how-do-i-deploy-my-encore-assets:
+
+How Do I Deploy My Encore Assets?
+---------------------------------
+
+There are two important things to remember when deploying your assets.
+
+**1) Compile Assets for Production**
+
+Optimize your assets for production by running:
+
+.. code-block:: terminal
+
+ $ ./node_modules/.bin/encore production
+
+That will minify your assets and make other performance optimizations. Yay!
+
+But, what server should you run this command on? That depends on how you deploy.
+For example, you could execute this locally (or on a build server), and use
+`rsync`_ or something else to transfer the generated files to your production
+server. Or, you could put your files on your production server first (e.g. via
+``git pull``) and then run this command on production (ideally, before traffic
+hits your code). In this case, you'll need to install Node.js on your production
+server.
+
+**2) Only Deploy the Built Assets**
+
+The *only* files that need to be deployed to your production servers are the
+final, built assets (e.g. the ``web/build`` directory). You do *not* need to install
+Node.js, deploy ``webpack.config.js``, the ``node_modules`` directory or even your source
+asset files, **unless** you plan on running ``encore production`` on your production
+machine. Once your assets are built, these are the *only* thing that need to live
+on the production server.
+
+Do I Need to Install Node.js on My Production Server?
+-----------------------------------------------------
+
+No, unless you plan to build your production assets on your production server,
+which is not recommended. See `How Do I Deploy my Encore Assets?`_.
+
+What Files Should I Commit to git? And which Should I Ignore?
+-------------------------------------------------------------
+
+You should commit all of your files to git, except for the ``node_modules/`` directory
+and the built files. Your ``.gitignore`` file should include:
+
+.. code-block:: text
+
+ /node_modules/
+ # whatever path you're passing to Encore.setOutputPath()
+ /web/build
+
+You *should* commit all of your source asset files, ``package.json`` and ``yarn.lock``.
+
+My App Lives under a Subdirectory
+---------------------------------
+
+If your app does not live at the root of your web server (i.e. it lives under a subdirectory,
+like ``/myAppSubdir``), you will need to configure that when calling ``Encore.setPublicPath()``:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ Encore
+ // ...
+
+ .setOutputPath('web/build/')
+
+ - .setPublicPath('/build')
+ + // this is your *true* public path
+ + .setPublicPath('/myAppSubdir/build')
+
+ + // this is now needed so that your manifest.json keys are still `build/foo.js`
+ + // (which is a file that's used by Symfony's `asset()` function)
+ + .setManifestKeyPrefix('build')
+ ;
+
+If you're using the ``encore_entry_script_tags()`` and ``encore_entry_link_tags()``
+Twig shortcuts (or are :ref:`processing your assets through entrypoints.json `
+in some other way) you're done! These shortcut methods read from an
+:ref:`entrypoints.json ` file that will
+now contain the subdirectory.
+
+"jQuery is not defined" or "$ is not defined"
+---------------------------------------------
+
+This error happens when your code (or some library that you are using) expects ``$``
+or ``jQuery`` to be a global variable. But, when you use Webpack and ``require('jquery')``,
+no global variables are set.
+
+The fix depends on if the error is happening in your code or inside some third-party
+code that you're using. See :doc:`/frontend/encore/legacy-applications` for the fix.
+
+Uncaught ReferenceError: webpackJsonp is not defined
+----------------------------------------------------
+
+If you get this error, it's probably because you've forgotten to add a ``script``
+tag for the ``runtime.js`` file that contains Webpack's runtime. If you're using
+the ``encore_entry_script_tags()`` Twig function, this should never happen: the
+file script tag is rendered automatically.
+
+This dependency was not found: some-module in ./path/to/file.js
+---------------------------------------------------------------
+
+Usually, after you install a package via yarn, you can require / import it to use
+it. For example, after running ``yarn add respond.js``, you try to require that module:
+
+.. code-block:: javascript
+
+ require('respond.js');
+
+But, instead of working, you see an error:
+
+ This dependency was not found:
+
+ * respond.js in ./app/Resources/assets/js/app.js
+
+Typically, a package will "advertise" its "main" file by adding a ``main`` key to
+its ``package.json``. But sometimes, old libraries won't have this. Instead, you'll
+need to specifically require the file you need. In this case, the file you should
+use is located at ``node_modules/respond.js/dest/respond.src.js``. You can require
+this via:
+
+.. code-block:: javascript
+
+ // require a non-minified file whenever possible
+ require('respond.js/dest/respond.src.js');
+
+I need to execute Babel on a third-party Module
+-----------------------------------------------
+
+For performance, Encore does not process libraries inside ``node_modules/`` through
+Babel. But, you can change that via the ``configureBabel()`` method. See
+:doc:`/frontend/encore/babel` for details.
+
+.. _`rsync`: https://rsync.samba.org/
+
+How Do I Integrate my Encore Configuration with my IDE?
+-------------------------------------------------------
+
+`Webpack integration in PhpStorm`_ and other IDEs makes your development more
+productive (for example by resolving aliases). However, you may face this error:
+
+.. code-block:: text
+
+ Encore.setOutputPath() cannot be called yet because the runtime environment
+ doesn't appear to be configured. Make sure you're using the encore executable
+ or call Encore.configureRuntimeEnvironment() first if you're purposely not
+ calling Encore directly.
+
+It fails because the Encore Runtime Environment is only configured when you are
+running it (e.g. when executing ``yarn encore dev``). Fix this issue calling to
+``Encore.isRuntimeEnvironmentConfigured()`` and
+``Encore.configureRuntimeEnvironment()`` methods:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ const Encore = require('@symfony/webpack-encore')
+
+ if (!Encore.isRuntimeEnvironmentConfigured()) {
+ Encore.configureRuntimeEnvironment(process.env.NODE_ENV || 'dev');
+ }
+
+ // ... the rest of the Encore configuration
+
+.. _`Webpack integration in PhpStorm`: https://www.jetbrains.com/help/phpstorm/using-webpack.html
diff --git a/frontend/encore/installation.rst b/frontend/encore/installation.rst
new file mode 100644
index 00000000000..f0d2575d4d2
--- /dev/null
+++ b/frontend/encore/installation.rst
@@ -0,0 +1,143 @@
+Installing Encore
+=================
+
+First, make sure you `install Node.js`_ and also the `Yarn package manager`_.
+The following instructions depend on whether you are installing Encore in a
+Symfony application or not.
+
+Installing Encore in Symfony Applications
+-----------------------------------------
+
+Run these commands to install both the PHP and JavaScript dependencies in your
+project:
+
+.. code-block:: terminal
+
+ $ composer require symfony/webpack-encore-bundle
+ $ yarn install
+
+If you are using :doc:`Symfony Flex `, this will install and enable
+the `WebpackEncoreBundle`_, create the ``assets/`` directory, add a
+``webpack.config.js`` file, and add ``node_modules/`` to ``.gitignore``. You can
+skip the rest of this article and go write your first JavaScript and CSS by
+reading :doc:`/frontend/encore/simple-example`!
+
+If you are not using Symfony Flex, you'll need to create all these directories
+and files by yourself following the instructions shown in the next section.
+
+Installing Encore in non Symfony Applications
+---------------------------------------------
+
+Install Encore into your project via Yarn:
+
+.. code-block:: terminal
+
+ $ yarn add @symfony/webpack-encore --dev
+
+ # if you prefer npm, run this command instead:
+ $ npm install @symfony/webpack-encore --save-dev
+
+This command creates (or modifies) a ``package.json`` file and downloads
+dependencies into a ``node_modules/`` directory. Yarn also creates/updates a
+``yarn.lock`` (called ``package-lock.json`` if you use npm).
+
+.. tip::
+
+ You *should* commit ``package.json`` and ``yarn.lock`` (or ``package-lock.json``
+ if using npm) to version control, but ignore ``node_modules/``.
+
+Creating the webpack.config.js File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Next, create a new ``webpack.config.js`` file at the root of your project. This
+is the main config file for both Webpack and Webpack Encore:
+
+.. code-block:: javascript
+
+ var Encore = require('@symfony/webpack-encore');
+
+ Encore
+ // directory where compiled assets will be stored
+ .setOutputPath('web/build/')
+ // public path used by the web server to access the output path
+ .setPublicPath('/build')
+ // only needed for CDN's or sub-directory deploy
+ //.setManifestKeyPrefix('build/')
+
+ /*
+ * ENTRY CONFIG
+ *
+ * Add 1 entry for each "page" of your app
+ * (including one that's included on every page - e.g. "app")
+ *
+ * Each entry will result in one JavaScript file (e.g. app.js)
+ * and one CSS file (e.g. app.css) if your JavaScript imports CSS.
+ */
+ .addEntry('app', './assets/js/app.js')
+ //.addEntry('page1', './assets/js/page1.js')
+ //.addEntry('page2', './assets/js/page2.js')
+
+ // will require an extra script tag for runtime.js
+ // but, you probably want this, unless you're building a single-page app
+ .enableSingleRuntimeChunk()
+
+ .cleanupOutputBeforeBuild()
+ .enableSourceMaps(!Encore.isProduction())
+ // enables hashed filenames (e.g. app.abc123.css)
+ .enableVersioning(Encore.isProduction())
+
+ // uncomment if you use TypeScript
+ //.enableTypeScriptLoader()
+
+ // uncomment if you use Sass/SCSS files
+ //.enableSassLoader()
+
+ // uncomment if you're having problems with a jQuery plugin
+ //.autoProvidejQuery()
+ ;
+
+ module.exports = Encore.getWebpackConfig();
+
+Next, open the new ``assets/js/app.js`` file which contains some JavaScript code
+*and* imports some CSS:
+
+.. code-block:: javascript
+
+ // assets/js/app.js
+ /*
+ * Welcome to your app's main JavaScript file!
+ *
+ * We recommend including the built version of this JavaScript file
+ * (and its CSS file) in your base layout (base.html.twig).
+ */
+
+ // any CSS you import will output into a single css file (app.css in this case)
+ import '../css/app.css';
+
+ // Need jQuery? Install it with "yarn add jquery", then uncomment to import it.
+ // import $ from 'jquery';
+
+ console.log('Hello Webpack Encore');
+
+And the new ``assets/css/app.css`` file:
+
+.. code-block:: css
+
+ /* assets/css/app.css */
+ body {
+ background-color: lightgray;
+ }
+
+You'll customize and learn more about these file in :doc:`/frontend/encore/simple-example`.
+
+.. caution::
+
+ Some of the documentation will use features that are specific to Symfony or
+ Symfony's `WebpackEncoreBundle`_. These are optional, and are special ways
+ of pointing to the asset paths generated by Encore that enable features like
+ :doc:`versioning ` and
+ :doc:`split chunks `.
+
+.. _`install Node.js`: https://nodejs.org/en/download/
+.. _`Yarn package manager`: https://yarnpkg.com/lang/en/docs/install/
+.. _`WebpackEncoreBundle`: https://github.com/symfony/webpack-encore-bundle
diff --git a/frontend/encore/legacy-applications.rst b/frontend/encore/legacy-applications.rst
new file mode 100644
index 00000000000..4f1193d7e06
--- /dev/null
+++ b/frontend/encore/legacy-applications.rst
@@ -0,0 +1,86 @@
+jQuery Plugins and Legacy Applications
+======================================
+
+Inside Webpack, when you require a module, it does *not* (usually) set a global variable.
+Instead, it just returns a value:
+
+.. code-block:: javascript
+
+ // this loads jquery, but does *not* set a global $ or jQuery variable
+ const $ = require('jquery');
+
+In practice, this will cause problems with some outside libraries that *rely* on
+jQuery to be global *or* if *your* JavaScript isn't being processed through Webpack
+(e.g. you have some JavaScript in your templates) and you need jQuery. Both will
+cause similar errors:
+
+.. code-block:: text
+
+ Uncaught ReferenceError: $ is not defined at [...]
+ Uncaught ReferenceError: jQuery is not defined at [...]
+
+The fix depends on what code is causing the problem.
+
+.. _encore-autoprovide-jquery:
+
+Fixing jQuery Plugins that Expect jQuery to be Global
+-----------------------------------------------------
+
+jQuery plugins often expect that jQuery is already available via the ``$`` or
+``jQuery`` global variables. To fix this, call ``autoProvidejQuery()`` from your
+``webpack.config.js`` file:
+
+.. code-block:: diff
+
+ Encore
+ // ...
+ + .autoProvidejQuery()
+ ;
+
+After restarting Encore, Webpack will look for all uninitialized ``$`` and ``jQuery``
+variables and automatically require ``jquery`` and set those variables for you.
+It "rewrites" the "bad" code to be correct.
+
+Internally, this ``autoProvidejQuery()`` method calls the ``autoProvideVariables()``
+method from Encore. In practice, it's equivalent to doing:
+
+.. code-block:: javascript
+
+ Encore
+ // you can use this method to provide other common global variables,
+ // such as '_' for the 'underscore' library
+ .autoProvideVariables({
+ $: 'jquery',
+ jQuery: 'jquery',
+ 'window.jQuery': 'jquery',
+ })
+ // ...
+ ;
+
+Accessing jQuery from outside of Webpack JavaScript Files
+---------------------------------------------------------
+
+If *your* code needs access to ``$`` or ``jQuery`` and you are inside of a file
+that's processed by Webpack/Encore, you should remove any "$ is not defined" errors
+by requiring jQuery: ``var $ = require('jquery')``.
+
+But if you also need to provide access to ``$`` and ``jQuery`` variables outside of
+JavaScript files processed by Webpack (e.g. JavaScript that still lives in your
+templates), you need to manually set these as global variables in some JavaScript
+file that is loaded before your legacy code.
+
+For example, in your ``app.js`` file that's processed by Webpack and loaded on every
+page, add:
+
+.. code-block:: diff
+
+ // require jQuery normally
+ const $ = require('jquery');
+
+ + // create global $ and jQuery variables
+ + global.$ = global.jQuery = $;
+
+The ``global`` variable is a special way of setting things in the ``window``
+variable. In a web context, using ``global`` and ``window`` are equivalent,
+except that ``window.jQuery`` won't work when using ``autoProvidejQuery()``.
+In other words, use ``global``.
diff --git a/frontend/encore/page-specific-assets.rst b/frontend/encore/page-specific-assets.rst
new file mode 100644
index 00000000000..92ab00a0a61
--- /dev/null
+++ b/frontend/encore/page-specific-assets.rst
@@ -0,0 +1,27 @@
+Creating Page-Specific CSS/JS
+=============================
+
+If you're creating a single page app (SPA), then you probably only need to define
+*one* entry in ``webpack.config.js``. But if you have multiple pages, you might
+want page-specific CSS and JavaScript.
+
+To learn how to set this up, see the :ref:`multiple-javascript-entries` example.
+
+Multiple Entries Per Page?
+--------------------------
+
+Typically, you should include only *one* JavaScript entry per page. Think of the
+checkout page as its own "app", where ``checkout.js`` includes all the functionality
+you need.
+
+However, it's pretty common to need to include some global JavaScript and CSS on
+every page. For that reason, it usually makes sense to have one entry (e.g. ``app``)
+that contains this global code (both JavaScript & CSS) and is included on every
+page (i.e. it's included in the *layout* of your app). This means that you will
+always have one, global entry on every page (e.g. ``app``) and you *may* have one
+page-specific JavaScript and CSS file from a page-specific entry (e.g. ``checkout``).
+
+.. tip::
+
+ Be sure to use :doc:`split chunks `
+ to avoid duplicating and shared code between your entry files.
diff --git a/frontend/encore/postcss.rst b/frontend/encore/postcss.rst
new file mode 100644
index 00000000000..4a9bc1ac6e6
--- /dev/null
+++ b/frontend/encore/postcss.rst
@@ -0,0 +1,94 @@
+PostCSS and autoprefixing (postcss-loader)
+==========================================
+
+`PostCSS`_ is a CSS post-processing tool that can transform your CSS in a lot
+of cool ways, like `autoprefixing`_, `linting`_ and more!
+
+First, download ``postcss-loader`` and any plugins you want, like ``autoprefixer``:
+
+.. code-block:: terminal
+
+ $ yarn add postcss-loader autoprefixer --dev
+
+Next, create a ``postcss.config.js`` file at the root of your project:
+
+.. code-block:: javascript
+
+ module.exports = {
+ plugins: {
+ // include whatever plugins you want
+ // but make sure you install these via yarn or npm!
+
+ // add browserslist config to package.json (see below)
+ autoprefixer: {}
+ }
+ }
+
+Then, enable the loader in Encore!
+
+.. code-block:: diff
+
+ // webpack.config.js
+
+ Encore
+ // ...
+ + .enablePostCssLoader()
+ ;
+
+Because you just modified ``webpack.config.js``, stop and restart Encore.
+
+That's it! The ``postcss-loader`` will now be used for all CSS, Sass, etc files.
+You can also pass options to the `postcss-loader`_ by passing a callback:
+
+.. code-block:: diff
+
+ // webpack.config.js
+
+ Encore
+ // ...
+ + .enablePostCssLoader((options) => {
+ + options.config = {
+ + // the directory where the postcss.config.js file is stored
+ + path: 'path/to/config'
+ + };
+ + })
+ ;
+
+.. _browserslist_package_config:
+
+Adding browserslist to ``package.json``
+---------------------------------------
+
+The ``autoprefixer`` (and many other tools) need to know what browsers you want to
+support. The best-practice is to configure this directly in your ``package.json``
+(so that all the tools can read this):
+
+.. code-block:: diff
+
+ {
+ + "browserslist": [
+ + "defaults"
+ + ]
+ }
+
+The ``defaults`` option is recommended for most users and would be equivalent
+to the following browserslist:
+
+.. code-block:: diff
+
+ {
+ + "browserslist": [
+ + "> 0.5%",
+ + "last 2 versions",
+ + "Firefox ESR",
+ + "not dead"
+ + ]
+ }
+
+See `browserslist`_ for more details on the syntax.
+
+.. _`PostCSS`: http://postcss.org/
+.. _`autoprefixing`: https://github.com/postcss/autoprefixer
+.. _`linting`: https://stylelint.io/
+.. _`browserslist`: https://github.com/browserslist/browserslist
+.. _`postcss-loader`: https://github.com/postcss/postcss-loader
diff --git a/frontend/encore/reactjs.rst b/frontend/encore/reactjs.rst
new file mode 100644
index 00000000000..ca3b017f13b
--- /dev/null
+++ b/frontend/encore/reactjs.rst
@@ -0,0 +1,35 @@
+Enabling React.js
+=================
+
+.. admonition:: Screencast
+ :class: screencast
+
+ Do you prefer video tutorials? Check out the `React.js screencast series`_.
+
+Using React? First add some dependencies with Yarn:
+
+.. code-block:: terminal
+
+ $ yarn add @babel/preset-react --dev
+ $ yarn add react react-dom prop-types
+
+Enable react in your ``webpack.config.js``:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+ + .enableReactPreset()
+ ;
+
+
+Then restart Encore. When you do, it will give you a command you can run to
+install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+Your ``.js`` and ``.jsx`` files will now be transformed through ``babel-preset-react``.
+
+.. _`React.js screencast series`: https://symfonycasts.com/screencast/reactjs
diff --git a/frontend/encore/server-data.rst b/frontend/encore/server-data.rst
new file mode 100644
index 00000000000..ebb1f3cb8a5
--- /dev/null
+++ b/frontend/encore/server-data.rst
@@ -0,0 +1,45 @@
+Passing Information from Twig to JavaScript
+===========================================
+
+In Symfony applications, you may find that you need to pass some dynamic data
+(e.g. user information) from Twig to your JavaScript code. One great way to pass
+dynamic configuration is by storing information in ``data`` attributes and reading
+them later in JavaScript. For example:
+
+.. code-block:: html+twig
+
+
+
+Fetch this in JavaScript:
+
+.. code-block:: javascript
+
+ document.addEventListener('DOMContentLoaded', function() {
+ var userRating = document.querySelector('.js-user-rating');
+ var isAuthenticated = userRating.dataset.isAuthenticated;
+
+ // or with jQuery
+ //var isAuthenticated = $('.js-user-rating').data('isAuthenticated');
+ });
+
+.. note::
+
+ When `accessing data attributes from JavaScript`_, the attribute names are
+ converted from dash-style to camelCase. For example, ``data-is-authenticated``
+ becomes ``isAuthenticated`` and ``data-number-of-reviews`` becomes
+ ``numberOfReviews``.
+
+There is no size limit for the value of the ``data-`` attributes, so you can
+store any content. In Twig, use the ``html_attr`` escaping strategy to avoid messing
+with HTML attributes. For example, if your ``User`` object has some ``getProfileData()``
+method that returns an array, you could do the following:
+
+.. code-block:: html+twig
+
+ `. Why?
+ If ``app.js`` contains application code that *frequently* changes, then
+ (when using versioning), its filename hash will frequently change. This means
+ your users won't enjoy the benefits of long-term caching for this file (which
+ is generally quite large).
diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst
new file mode 100644
index 00000000000..7a9800dd3b3
--- /dev/null
+++ b/frontend/encore/simple-example.rst
@@ -0,0 +1,351 @@
+Encore: Setting up your Project
+===============================
+
+After :doc:`installing Encore `, your app already has one
+CSS and one JS file, organized into an ``assets/`` directory:
+
+* ``assets/js/app.js``
+* ``assets/css/app.css``
+
+With Encore, think of your ``app.js`` file like a standalone JavaScript
+application: it will *require* all of the dependencies it needs (e.g. jQuery or React),
+*including* any CSS. Your ``app.js`` file is already doing this with a special
+``require()`` function:
+
+.. code-block:: javascript
+
+ // assets/js/app.js
+ // ...
+
+ require('../css/app.css');
+
+ // var $ = require('jquery');
+
+Encore's job (via Webpack) is simple: to read and follow *all* of the ``require()``
+statements and create one final ``app.js`` (and ``app.css``) that contains *everything*
+your app needs. Encore can do a lot more: minify files, pre-process Sass/LESS,
+support React, Vue.js, etc.
+
+Configuring Encore/Webpack
+--------------------------
+
+Everything in Encore is configured via a ``webpack.config.js`` file at the root
+of your project. It already holds the basic config you need:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ var Encore = require('@symfony/webpack-encore');
+
+ Encore
+ // directory where compiled assets will be stored
+ .setOutputPath('web/build/')
+ // public path used by the web server to access the output path
+ .setPublicPath('/build')
+
+ .addEntry('app', './assets/js/app.js')
+
+ // ...
+ ;
+
+ // ...
+
+The *key* part is ``addEntry()``: this tells Encore to load the ``assets/js/app.js``
+file and follow *all* of the ``require()`` statements. It will then package everything
+together and - thanks to the first ``app`` argument - output final ``app.js`` and
+``app.css`` files into the ``web/build`` directory.
+
+.. _encore-build-assets:
+
+To build the assets, run:
+
+.. code-block:: terminal
+
+ # compile assets once
+ $ yarn encore dev
+
+ # or, recompile assets automatically when files change
+ $ yarn encore dev --watch
+
+ # on deploy, create a production build
+ $ yarn encore production
+
+.. note::
+
+ Stop and restart ``encore`` each time you update your ``webpack.config.js`` file.
+
+Congrats! You now have three new files:
+
+* ``web/build/app.js`` (holds all the JavaScript for your "app" entry)
+* ``web/build/app.css`` (holds all the CSS for your "app" entry)
+* ``web/build/runtime.js`` (a file that helps Webpack do its job)
+
+Next, include these in your base layout file. Two Twig helpers from WebpackEncoreBundle
+can do most of the work for you:
+
+.. code-block:: html+twig
+
+ {# app/Resources/views/base.html.twig #}
+
+
+
+
+
+ {% block stylesheets %}
+ {# 'app' must match the first argument to addEntry() in webpack.config.js #}
+ {{ encore_entry_link_tags('app') }}
+
+
+ {% endblock %}
+
+
+
+
+ {% block javascripts %}
+ {{ encore_entry_script_tags('app') }}
+
+
+ {% endblock %}
+
+
+
+.. _encore-entrypointsjson-simple-description:
+
+That's it! When you refresh your page, all of the JavaScript from
+``assets/js/app.js`` - as well as any other JavaScript files it included - will
+be executed. All the CSS files that were required will also be displayed.
+
+The ``encore_entry_link_tags()`` and ``encore_entry_script_tags()`` functions
+read from an ``entrypoints.json`` file that's generated by Encore to know the exact
+filename(s) to render. This file is *especially* useful because you can
+:doc:`enable versioning ` or
+:doc:`point assets to a CDN ` without making *any* changes to your
+template: the paths in ``entrypoints.json`` will always be the final, correct paths.
+
+If you're *not* using Symfony, you can ignore the ``entrypoints.json`` file and
+point to the final, built file directly. ``entrypoints.json`` is only required for
+some optional features.
+
+.. versionadded:: 0.21.0
+
+ The ``encore_entry_link_tags()`` comes from WebpackEncoreBundle and relies
+ on a feature in Encore that was first introduced in version 0.21.0. Previously,
+ the ``asset()`` function was used to point directly to the file.
+
+Requiring JavaScript Modules
+----------------------------
+
+Webpack is a module bundler... which means that you can ``require`` other JavaScript
+files. First, create a file that exports a function:
+
+.. code-block:: javascript
+
+ // assets/js/greet.js
+ module.exports = function(name) {
+ return `Yo yo ${name} - welcome to Encore!`;
+ };
+
+We'll use jQuery to print this message on the page. Install it via:
+
+.. code-block:: terminal
+
+ $ yarn add jquery --dev
+
+Great! Use ``require()`` to import ``jquery`` and ``greet.js``:
+
+.. code-block:: diff
+
+ // assets/js/app.js
+ // ...
+
+ + // loads the jquery package from node_modules
+ + var $ = require('jquery');
+
+ + // import the function from greet.js (the .js extension is optional)
+ + // ./ (or ../) means to look for a local file
+ + var greet = require('./greet');
+
+ + $(document).ready(function() {
+ + $('body').prepend('`.
+
+.. _`Encore's index.js file`: https://github.com/symfony/webpack-encore/blob/master/index.js
+.. _`ECMAScript 6 modules`: https://hacks.mozilla.org/2015/08/es6-in-depth-modules/
diff --git a/frontend/encore/sourcemaps.rst b/frontend/encore/sourcemaps.rst
new file mode 100644
index 00000000000..62d4c6a351b
--- /dev/null
+++ b/frontend/encore/sourcemaps.rst
@@ -0,0 +1,23 @@
+Enabling Source Maps
+====================
+
+`Source maps`_ allow browsers to access the original code related to some
+asset (e.g. the Sass code that was compiled to CSS or the TypeScript code that
+was compiled to JavaScript). Source maps are useful for debugging purposes but
+unnecessary when executing the application in production.
+
+Encore's default ``webpack.config.js`` file enables source maps in the ``dev``
+build:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+
+ .enableSourceMaps(!Encore.isProduction())
+ ;
+
+.. _`Source maps`: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
diff --git a/frontend/encore/split-chunks.rst b/frontend/encore/split-chunks.rst
new file mode 100644
index 00000000000..ebaa4ee48ce
--- /dev/null
+++ b/frontend/encore/split-chunks.rst
@@ -0,0 +1,64 @@
+Preventing Duplication by "Splitting" Shared Code into Separate Files
+=====================================================================
+
+Suppose you have multiple entry files and *each* requires ``jquery``. In this
+case, *each* output file will contain jQuery, making your files much larger than
+necessary. To solve this, you can ask webpack to analyze your files and *split* them
+into additional files, which will contain "shared" code.
+
+To enable this, call ``splitEntryChunks()``:
+
+.. code-block:: diff
+
+ Encore
+ // ...
+
+ // multiple entry files, which probably import the same code
+ .addEntry('app', './assets/js/app.js')
+ .addEntry('homepage', './assets/js/homepage.js')
+ .addEntry('blog', './assets/js/blog.js')
+ .addEntry('store', './assets/js/store.js')
+
+ + .splitEntryChunks()
+
+
+Now, each output file (e.g. ``homepage.js``) *may* be split into multiple file
+(e.g. ``homepage.js``, ``vendor~homepage.js``). This means that you *may* need to
+include *multiple* ``script`` tags (or ``link`` tags for CSS) in your template.
+Encore creates an :ref:`entrypoints.json `
+file that lists exactly which CSS and JavaScript files are needed for each entry.
+
+If you're using the ``encore_entry_link_tags()`` and ``encore_entry_script_tags()``
+Twig functions from WebpackEncoreBundle, you don't need to do anything else! These
+functions automatically read this file and render as many ``script`` or ``link``
+tags as needed:
+
+.. code-block:: html+twig
+
+ {#
+ May now render multiple script tags:
+
+
+
+ #}
+ {{ encore_entry_script_tags('homepage') }}
+
+Controlling how Assets are Split
+--------------------------------
+
+The logic for *when* and *how* to split the files is controlled by the
+`SplitChunksPlugin from Webpack`_. You can control the configuration passed to
+this plugin with the ``configureSplitChunks()`` function:
+
+.. code-block:: diff
+
+ Encore
+ // ...
+
+ .splitEntryChunks()
+ + .configureSplitChunks(function(splitChunks) {
+ + // change the configuration
+ + splitChunks.minSize = 0;
+ + })
+
+.. _`SplitChunksPlugin from Webpack`: https://webpack.js.org/plugins/split-chunks-plugin/
diff --git a/frontend/encore/typescript.rst b/frontend/encore/typescript.rst
new file mode 100644
index 00000000000..b1af45d9c04
--- /dev/null
+++ b/frontend/encore/typescript.rst
@@ -0,0 +1,58 @@
+Enabling TypeScript (ts-loader)
+===============================
+
+Want to use `TypeScript`_? No problem! First, enable it:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+ + .addEntry('main', './assets/main.ts')
+
+ + .enableTypeScriptLoader()
+
+ // optionally enable forked type script for faster builds
+ // https://www.npmjs.com/package/fork-ts-checker-webpack-plugin
+ // requires that you have a tsconfig.json file that is setup correctly.
+ + //.enableForkedTypeScriptTypesChecking()
+ ;
+
+Then restart Encore. When you do, it will give you a command you can run to
+install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+Any ``.ts`` files that you require will be processed correctly. You can
+also configure the `ts-loader options`_ via the ``enableTypeScriptLoader()``
+method.
+
+.. code-block:: diff
+
+ Encore
+ // ...
+ .addEntry('main', './assets/main.ts')
+
+ - .enableTypeScriptLoader()
+ + .enableTypeScriptLoader(function(tsConfig) {
+ + // You can use this callback function to adjust ts-loader settings
+ + // https://github.com/TypeStrong/ts-loader/blob/master/README.md#loader-options
+ + // For example:
+ + // tsConfig.silent = false
+ + })
+
+ // ...
+ ;
+
+See the `Encore's index.js file`_ for detailed documentation and check
+out the `tsconfig.json reference`_ and the `Webpack guide about Typescript`_.
+
+If React is enabled (``.enableReactPreset()``), any ``.tsx`` file will also be
+processed by ``ts-loader``.
+
+.. _`TypeScript`: https://www.typescriptlang.org/
+.. _`ts-loader options`: https://github.com/TypeStrong/ts-loader#options
+.. _`Encore's index.js file`: https://github.com/symfony/webpack-encore/blob/master/index.js
+.. _`tsconfig.json reference`: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
+.. _`Webpack guide about Typescript`: https://webpack.js.org/guides/typescript/
diff --git a/frontend/encore/url-loader.rst b/frontend/encore/url-loader.rst
new file mode 100644
index 00000000000..976cd6974d8
--- /dev/null
+++ b/frontend/encore/url-loader.rst
@@ -0,0 +1,51 @@
+Inlining files in CSS with Webpack URL Loader
+=============================================
+
+A simple technique to improve the performance of web applications is to reduce
+the number of HTTP requests inlining small files as base64 encoded URLs in the
+generated CSS files.
+
+Webpack Encore provides this feature via Webpack's `URL Loader`_ plugin, but
+it's disabled by default. First, add the URL loader to your project:
+
+.. code-block:: terminal
+
+ $ yarn add url-loader --dev
+
+Then enable it in your ``webpack.config.js``:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+ .configureUrlLoader({
+ fonts: { limit: 4096 },
+ images: { limit: 4096 }
+ })
+ ;
+
+The ``limit`` option defines the maximum size in bytes of the inlined files. In
+the previous example, font and image files having a size below or equal to 4 KB
+will be inlined and the rest of files will be processed as usual.
+
+You can also use all the other options supported by the `URL Loader`_. If you
+want to disable this loader for either images or fonts, remove the corresponding
+key from the object that is passed to the ``configureUrlLoader()`` method:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+ .configureUrlLoader({
+ // 'fonts' is not defined, so only images will be inlined
+ images: { limit: 4096 }
+ })
+ ;
+
+.. _`URL Loader`: https://github.com/webpack-contrib/url-loader
diff --git a/frontend/encore/versioning.rst b/frontend/encore/versioning.rst
new file mode 100644
index 00000000000..98a2b7fb6b2
--- /dev/null
+++ b/frontend/encore/versioning.rst
@@ -0,0 +1,92 @@
+Asset Versioning
+================
+
+.. _encore-long-term-caching:
+
+Tired of deploying and having browser's cache the old version of your assets?
+By calling ``enableVersioning()``, each filename will now include a hash that
+changes whenever the *contents* of that file change (e.g. ``app.123abc.js``
+instead of ``app.js``). This allows you to use aggressive caching strategies
+(e.g. a far future ``Expires``) because, whenever a file change, its hash will change,
+ignoring any existing cache:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ .setOutputPath('web/build/')
+ // ...
+ + .enableVersioning()
+
+To link to these assets, Encore creates two files ``entrypoints.json`` and
+``manifest.json``.
+
+.. _load-manifest-files:
+
+Loading Assets from ``entrypoints.json`` & ``manifest.json``
+------------------------------------------------------------
+
+Whenever you run Encore, two configuration files are generated: ``entrypoints.json``
+and ``manifest.json``. Each file is similar, and contains a map to the final, versioned
+filename.
+
+The first file - ``entrypoints.json`` - is used by the ``encore_entry_script_tags()``
+and ``encore_entry_link_tags()`` Twig helpers. If you're using these, then your
+CSS and JavaScript files will render with the new, versioned filename. If you're
+not using Symfony, your app will need to read this file in a similar way.
+
+The ``manifest.json`` file is only needed to get the versioned filename of *other*
+files, like font files or image files (though it also contains information about
+the CSS and JavaScript files):
+
+.. code-block:: json
+
+ {
+ "build/app.js": "/build/app.123abc.js",
+ "build/dashboard.css": "/build/dashboard.a4bf2d.css",
+ "build/images/logo.png": "/build/images/logo.3eed42.png"
+ }
+
+In your app, you need to read this file if you want to be able to link (e.g. via
+an ``img`` tag) to certain assets. If you're using Symfony, just activate the
+``json_manifest_file`` versioning strategy in ``config.yml``:
+
+.. code-block:: yaml
+
+ # app/config/config.yml
+ framework:
+ # ...
+ assets:
+ # feature is supported in Symfony 3.3 and higher
+ json_manifest_path: '%kernel.project_dir%/web/build/manifest.json'
+
+That's it! Just be sure to wrap each path in the Twig ``asset()`` function
+like normal:
+
+.. code-block:: html+twig
+
+  }})
+
+Troubleshooting
+---------------
+
+Asset Versioning and Deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When deploying a new version of your application, versioned assets will include
+a new hash, making the previous assets no longer available. This is usually not
+a problem when deploying applications using a rolling update, blue/green or
+symlink strategies.
+
+However, even when applying those techniques, there could be a lapse of time
+when some publicly/privately cached response requests the previous version of
+the assets. If your application can't afford to serve any broken asset, the best
+solution is to use a CDN (or custom made service) that keeps all the old assets
+cached for some time.
+
+Learn more
+----------
+
+* :doc:`/components/asset`
diff --git a/frontend/encore/versus-assetic.rst b/frontend/encore/versus-assetic.rst
new file mode 100644
index 00000000000..afc2373b2b7
--- /dev/null
+++ b/frontend/encore/versus-assetic.rst
@@ -0,0 +1,56 @@
+Encore Versus Assetic?
+======================
+
+Symfony originally shipped with support for :doc:`Assetic `: a
+pure PHP library capable of processing, combining and minifying CSS and JavaScript
+files. And while Encore is now the recommended way of processing your assets, Assetic
+still works well.
+
+So what are the differences between Assetic and Encore?
+
++----------------------------------+-------------------------------+-------------------------+
+| | Assetic | Encore +
++----------------------------------+-------------------------------+-------------------------+
+| Language | Pure PHP, relies on other | Node.js |
+| | language tools for some tasks | |
++----------------------------------+-------------------------------+-------------------------+
+| Combine assets? | Yes | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| Minify assets? | Yes (when configured) | Yes (out-of-the-box) |
++----------------------------------+-------------------------------+-------------------------+
+| Process Sass/Less? | Yes | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| Loads JS Modules? [1]_ | No | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| Load CSS dependencies in JS? [1] | No | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| React, Vue.js support? | No [2]_ | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| Support | Not actively maintained | Actively maintained |
++----------------------------------+-------------------------------+-------------------------+
+
+.. [1] JavaScript modules allow you to organize your JavaScript into small files
+ called modules and import them:
+
+ .. code-block:: javascript
+
+ // require third-party modules
+ var $ = require('jquery');
+
+ // require your own CoolComponent.js modules
+ var coolComponent = require('./components/CoolComponent');
+
+ Encore (via Webpack) parses these automatically and creates a JavaScript
+ file that contains all needed dependencies. You can even require CSS or
+ images.
+
+.. [2] Assetic has outdated support for React.js only. Encore ships with modern
+ support for React.js, Vue.js, TypeScript, etc.
+
+Should I Upgrade from Assetic to Encore
+---------------------------------------
+
+If you already have Assetic working in an application, and haven't needed any of
+the features that Encore offers over Assetic, continuing to use Assetic is fine.
+If you *do* start to need more features, then you might have a business case for
+changing to Encore.
diff --git a/frontend/encore/virtual-machine.rst b/frontend/encore/virtual-machine.rst
new file mode 100644
index 00000000000..068d5c8451f
--- /dev/null
+++ b/frontend/encore/virtual-machine.rst
@@ -0,0 +1,121 @@
+Using Encore in a Virtual Machine
+=================================
+
+Encore is compatible with virtual machines such as `VirtualBox`_ and `VMWare`_
+but you may need to make some changes to your configuration to make it work.
+
+File Watching Issues
+--------------------
+
+When using a virtual machine, your project root directory is shared with the
+virtual machine using `NFS`_. This introduces issues with files watching, so
+you must enable the `polling`_ option to make it work:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+
+ // ...
+
+ // will be applied for `encore dev --watch` and `encore dev-server` commands
+ Encore.configureWatchOptions(watchOptions => {
+ watchOptions.poll = 250; // check for changes every 250 milliseconds
+ });
+
+Development Server Issues
+-------------------------
+
+Configure the Public Path
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+ You can skip this section if your application is running on
+ ``http://localhost`` instead a custom local domain-name like
+ ``http://app.vm``.
+
+When running the development server, you will probably see the following errors
+in the web console:
+
+.. code-block:: text
+
+ GET http://localhost:8080/build/vendors~app.css net::ERR_CONNECTION_REFUSED
+ GET http://localhost:8080/build/runtime.js net::ERR_CONNECTION_REFUSED
+ ...
+
+If your Symfony application is running on a custom domain (e.g.
+``http://app.vm``), you must configure the public path explicitly in your
+``package.json``:
+
+.. code-block:: diff
+
+ {
+ ...
+ "scripts": {
+ - "dev-server": "encore dev-server",
+ + "dev-server": "encore dev-server --public http://app.vm:8080",
+ ...
+ }
+ }
+
+After restarting Encore and reloading your web page, you will probably see
+different issues in the web console:
+
+.. code-block:: text
+
+ GET http://app.vm:8080/build/vendors~app.css net::ERR_CONNECTION_REFUSED
+ GET http://app.vm:8080/build/runtime.js net::ERR_CONNECTION_REFUSED
+
+You still need to make other configuration changes, as explained in the
+following sections.
+
+Allow External Access
+~~~~~~~~~~~~~~~~~~~~~
+
+Add the ``--host 0.0.0.0`` argument to the ``dev-server`` configuration in your
+``package.json`` file to make the development server accept all incoming
+connections:
+
+.. code-block:: diff
+
+ {
+ ...
+ "scripts": {
+ - "dev-server": "encore dev-server --public http://app.vm:8080",
+ + "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0",
+ ...
+ }
+ }
+
+.. caution::
+
+ Make sure to run the development server inside your virtual machine only;
+ otherwise other computers can have access to it.
+
+Fix "Invalid Host header" Issue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Webpack will respond ``Invalid Host header`` when trying to access files from
+the dev-server. To fix this, add the argument ``--disable-host-check``:
+
+.. code-block:: diff
+
+ {
+ ...
+ "scripts": {
+ - "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0",
+ + "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0 --disable-host-check",
+ ...
+ }
+ }
+
+.. caution::
+
+ Beware that `it's not recommended to disable host checking`_ in general, but
+ here it's required to solve the issue when using Encore in a virtual machine.
+
+.. _`VirtualBox`: https://www.virtualbox.org/
+.. _`VMWare`: https://www.vmware.com
+.. _`NFS`: https://en.wikipedia.org/wiki/Network_File_System
+.. _`polling`: https://webpack.js.org/configuration/watch/#watchoptionspoll
+.. _`it's not recommended to disable host checking`: https://webpack.js.org/configuration/dev-server/#devserverdisablehostcheck
diff --git a/frontend/encore/vuejs.rst b/frontend/encore/vuejs.rst
new file mode 100644
index 00000000000..4c67362ada1
--- /dev/null
+++ b/frontend/encore/vuejs.rst
@@ -0,0 +1,162 @@
+Enabling Vue.js (``vue-loader``)
+================================
+
+.. admonition:: Screencast
+ :class: screencast
+
+ Do you prefer video tutorials? Check out the `Vue screencast series`_.
+
+Want to use `Vue.js`_? No problem! First enable it in ``webpack.config.js``:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+ .addEntry('main', './assets/main.js')
+
+ + .enableVueLoader()
+ ;
+
+Then restart Encore. When you do, it will give you a command you can run to
+install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+Any ``.vue`` files that you require will be processed correctly. You can also
+configure the `vue-loader options`_ by passing an options callback to
+``enableVueLoader()``. See the `Encore's index.js file`_ for detailed documentation.
+
+Hot Module Replacement (HMR)
+----------------------------
+
+The ``vue-loader`` supports hot module replacement: just update your code and watch
+your Vue.js app update *without* a browser refresh! To activate it, just use the
+``dev-server`` with the ``--hot`` option:
+
+.. code-block:: terminal
+
+ $ yarn encore dev-server --hot
+
+That's it! Change one of your ``.vue`` files and watch your browser update. But
+note: this does *not* currently work for *style* changes in a ``.vue`` file. Seeing
+updated styles still requires a page refresh.
+
+See :doc:`/frontend/encore/dev-server` for more details.
+
+JSX Support
+-----------
+
+You can enable `JSX with Vue.js`_ by configuring the second parameter of the
+``.enableVueLoader()`` method:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+ .addEntry('main', './assets/main.js')
+
+ - .enableVueLoader()
+ + .enableVueLoader(() => {}, {
+ + useJsx: true
+ + })
+ ;
+
+Next, run or restart Encore. When you do, you will see an error message helping
+you install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+Your ``.jsx`` files will now be transformed through ``@vue/babel-preset-jsx``.
+
+Using styles
+~~~~~~~~~~~~
+
+You can't use ``
+ {{ message }}
{% endfor %}
{% endfor %}
+ {# read and display all flash messages #}
+ {% for label, messages in app.flashes %}
+ {% for message in messages %}
+
+ {{ message }}
+
+ {% endfor %}
+ {% endfor %}
+
+.. versionadded:: 3.3
+
+ The ``app.flashes()`` Twig function was introduced in Symfony 3.3. Prior,
+ you had to use ``app.session.flashBag()``.
+
.. note::
It's common to use ``notice``, ``warning`` and ``error`` as the keys of the
@@ -470,7 +601,7 @@ the ``Request`` class::
{
$request->isXmlHttpRequest(); // is it an Ajax request?
- $request->getPreferredLanguage(array('en', 'fr'));
+ $request->getPreferredLanguage(['en', 'fr']);
// retrieves GET and POST variables respectively
$request->query->get('page');
@@ -509,16 +640,12 @@ headers and content that's sent back to the client::
// creates a simple Response with a 200 status code (the default)
$response = new Response('Hello '.$name, Response::HTTP_OK);
- // JsonResponse is a sub-class of Response
- $response = new JsonResponse(array('name' => $name));
- // sets a header!
- $response->headers->set('X-Rate-Limit', 10);
+ // creates a CSS-response with a 200 status code
+ $response = new Response('');
+ $response->headers->set('Content-Type', 'text/css');
There are special classes that make certain kinds of responses easier:
-* For JSON, there is :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`.
- See :ref:`component-http-foundation-json-response`.
-
* For files, there is :class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`.
See :ref:`component-http-foundation-serving-files`.
@@ -532,6 +659,61 @@ There are special classes that make certain kinds of responses easier:
``Request`` and ``Response`` object in the
:ref:`HttpFoundation component documentation You did it! You registered!
@@ -150,11 +153,6 @@ template might look something like this: {# Makes an absolute URL to the /images/logo.png file #}
-.. versionadded:: 2.7
- The ``absolute_url()`` function was introduced in Symfony 2.7. Prior
- to 2.7, the ``asset()`` function has an argument to enable returning
- an absolute URL.
-
The ``$message`` object supports many more options, such as including attachments,
adding HTML content, and much more. Fortunately, Swift Mailer covers the topic
of `Creating Messages`_ in great detail in its documentation.
diff --git a/email/cloud.rst b/email/cloud.rst
index d7ddbd33f3b..51103f1190d 100644
--- a/email/cloud.rst
+++ b/email/cloud.rst
@@ -12,8 +12,8 @@ option. If setting up and maintaining your own reliable mail server causes
you a headache there's a simple solution: Leverage the cloud to send your
emails.
-This article shows how easy it is to integrate
-`Amazon's Simple Email Service (SES)`_ into Symfony.
+This article shows how to integrate `Amazon's Simple Email Service (SES)`_
+into Symfony.
.. note::
@@ -47,9 +47,9 @@ and complete the configuration with the provided ``username`` and ``password``:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
- http://symfony.com/schema/dic/services/services-1.0.xsd
+ https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/swiftmailer
- http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+ https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+ {# assets/images/subdir/logo.png was copied to web/build/subdir/logo.png #}
+
+
+Make sure you've enabled the :ref:`json_manifest_path
+
+
+
+.. _`accessing data attributes from JavaScript`: https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes
diff --git a/frontend/encore/shared-entry.rst b/frontend/encore/shared-entry.rst
new file mode 100644
index 00000000000..6693b649d8d
--- /dev/null
+++ b/frontend/encore/shared-entry.rst
@@ -0,0 +1,42 @@
+Creating a Shared Commons Entry
+===============================
+
+.. caution::
+
+ While this method still works, see :doc:`/frontend/encore/split-chunks` for
+ the preferred solution to sharing assets between multiple entry files.
+
+Suppose you have multiple entry files and *each* requires ``jquery``. In this
+case, *each* output file will contain jQuery, slowing down your user's experience.
+To solve this, you can *extract* the common libraries to a "shared" entry file
+that's included on every page.
+
+Suppose you already have an entry called ``app`` that's included on every page.
+Update your code to use ``createSharedEntry()``:
+
+.. code-block:: diff
+
+ Encore
+ // ...
+ - .addEntry('app', './assets/js/app.js')
+ + .createSharedEntry('app', './assets/js/app.js')
+ .addEntry('homepage', './assets/js/homepage.js')
+ .addEntry('blog', './assets/js/blog.js')
+ .addEntry('store', './assets/js/store.js')
+
+Before making this change, if both ``app.js`` and ``store.js`` require ``jquery``,
+then ``jquery`` would be packaged into *both* files, which is wasteful. By making
+``app.js`` your "shared" entry, *any* code required by ``app.js`` (like jQuery) will
+*no longer* be packaged into any other files. The same is true for any CSS.
+
+Because ``app.js`` contains all the common code that other entry files depend on,
+its script (and link) tag must be on every page.
+
+.. tip::
+
+ The ``app.js`` file works best when its contents are changed *rarely*
+ and you're using :ref:`long-term caching '+greet('jill')+'
'); + + }); + +That's it! If you previously ran ``encore dev --watch``, your final, built files +have already been updated: jQuery and ``greet.js`` have been automatically +added to the output file (``app.js``). Refresh to see the message! + +The import and export Statements +-------------------------------- + +Instead of using ``require()`` and ``module.exports`` like shown above, JavaScript +provides an alternate syntax based on the `ECMAScript 6 modules`_ that includes +the ability to use dynamic imports. + +To export values, use ``export``: + +.. code-block:: diff + + // assets/js/greet.js + - module.exports = function(name) { + + export default function(name) { + return `Yo yo ${name} - welcome to Encore!`; + }; + +To import values, use ``import``: + +.. code-block:: diff + + // assets/js/app.js + - require('../css/app.css'); + + import '../css/app.css'; + + - var $ = require('jquery'); + + import $ from 'jquery'; + + - var greet = require('./greet'); + + import greet from './greet'; + +.. _multiple-javascript-entries: + +Page-Specific JavaScript or CSS (Multiple Entries) +-------------------------------------------------- + +So far, you only have one final JavaScript file: ``app.js``. For small applications +or SPA's (Single Page Applications), that might be fine! However, as your app grows, +you may want to have page-specific JavaScript or CSS (e.g. checkout, account, +etc.). To handle this, create a new "entry" JavaScript file for each page: + +.. code-block:: javascript + + // assets/js/checkout.js + // custom code for your checkout page + +.. code-block:: javascript + + // assets/js/account.js + // custom code for your account page + +Next, use ``addEntry()`` to tell Webpack to read these two new files when it builds: + +.. code-block:: diff + + // webpack.config.js + Encore + // ... + .addEntry('app', './assets/js/app.js') + + .addEntry('checkout', './assets/js/checkout.js') + + .addEntry('account', './assets/js/account.js') + // ... + +And because you just changed the ``webpack.config.js`` file, make sure to stop +and restart Encore: + +.. code-block:: terminal + + $ yarn run encore dev --watch + +Webpack will now output a new ``checkout.js`` file and a new ``account.js`` file +in your build directory. And, if any of those files require/import CSS, Webpack +will *also* output ``checkout.css`` and ``account.css`` files. + +Finally, include the ``script`` and ``link`` tags on the individual pages where +you need them: + +.. code-block:: diff + + {# templates/.../checkout.html.twig #} + {% extends 'base.html.twig' %} + + + {% block stylesheets %} + + {{ parent() }} + + {{ encore_entry_link_tags('checkout') }} + + {% endblock %} + + + {% block javascripts %} + + {{ parent() }} + + {{ encore_entry_script_tags('checkout') }} + + {% endblock %} + +Now, the checkout page will contain all the JavaScript and CSS for the ``app`` entry +(because this is included in ``base.html.twig`` and there is the ``{{ parent() }}`` call) +*and* your ``checkout`` entry. + +See :doc:`/frontend/encore/page-specific-assets` for more details. To avoid duplicating +the same code in different entry files, see :doc:`/frontend/encore/split-chunks`. + +Using Sass/LESS/Stylus +---------------------- + +You've already mastered the basics of Encore. Nice! But, there are *many* more +features that you can opt into if you need them. For example, instead of using plain +CSS you can also use Sass, LESS or Stylus. To use Sass, rename the ``app.css`` +file to ``app.scss`` and update the ``import`` statement: + +.. code-block:: diff + + // assets/js/app.js + - import '../css/app.css'; + + import '../css/app.scss'; + +Then, tell Encore to enable the Sass pre-processor: + +.. code-block:: diff + + // webpack.config.js + Encore + // ... + + + .enableSassLoader() + ; + +Because you just changed your ``webpack.config.js`` file, you'll need to restart +Encore. When you do, you'll see an error! + +.. code-block:: terminal + + > Error: Install sass-loader & node-sass to use enableSassLoader() + > yarn add sass-loader@^8.0.0 node-sass --dev + +Encore supports many features. But, instead of forcing all of them on you, when +you need a feature, Encore will tell you what you need to install. Run: + +.. code-block:: terminal + + $ yarn add sass-loader@^8.0.0 node-sass --dev + $ yarn encore dev --watch + +Your app now supports Sass. Encore also supports LESS and Stylus. See +:doc:`/frontend/encore/css-preprocessors`. + +Compiling Only a CSS File +------------------------- + +.. caution:: + + Using ``addStyleEntry()`` is supported, but not recommended. A better option + is to follow the pattern above: use ``addEntry()`` to point to a JavaScript + file, then require the CSS needed from inside of that. + +If you want to only compile a CSS file, that's possible via ``addStyleEntry()``: + +.. code-block:: javascript + + // webpack.config.js + Encore + // ... + + .addStyleEntry('some_page', './assets/css/some_page.css') + ; + +This will output a new ``some_page.css``. + +Keep Going! +----------- + +Encore supports many more features! For a full list of what you can do, see +`Encore's index.js file`_. Or, go back to :ref:`list of Encore articles
+
+Troubleshooting
+---------------
+
+Asset Versioning and Deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When deploying a new version of your application, versioned assets will include
+a new hash, making the previous assets no longer available. This is usually not
+a problem when deploying applications using a rolling update, blue/green or
+symlink strategies.
+
+However, even when applying those techniques, there could be a lapse of time
+when some publicly/privately cached response requests the previous version of
+the assets. If your application can't afford to serve any broken asset, the best
+solution is to use a CDN (or custom made service) that keeps all the old assets
+cached for some time.
+
+Learn more
+----------
+
+* :doc:`/components/asset`
diff --git a/frontend/encore/versus-assetic.rst b/frontend/encore/versus-assetic.rst
new file mode 100644
index 00000000000..afc2373b2b7
--- /dev/null
+++ b/frontend/encore/versus-assetic.rst
@@ -0,0 +1,56 @@
+Encore Versus Assetic?
+======================
+
+Symfony originally shipped with support for :doc:`Assetic `: a
+pure PHP library capable of processing, combining and minifying CSS and JavaScript
+files. And while Encore is now the recommended way of processing your assets, Assetic
+still works well.
+
+So what are the differences between Assetic and Encore?
+
++----------------------------------+-------------------------------+-------------------------+
+| | Assetic | Encore +
++----------------------------------+-------------------------------+-------------------------+
+| Language | Pure PHP, relies on other | Node.js |
+| | language tools for some tasks | |
++----------------------------------+-------------------------------+-------------------------+
+| Combine assets? | Yes | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| Minify assets? | Yes (when configured) | Yes (out-of-the-box) |
++----------------------------------+-------------------------------+-------------------------+
+| Process Sass/Less? | Yes | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| Loads JS Modules? [1]_ | No | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| Load CSS dependencies in JS? [1] | No | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| React, Vue.js support? | No [2]_ | Yes |
++----------------------------------+-------------------------------+-------------------------+
+| Support | Not actively maintained | Actively maintained |
++----------------------------------+-------------------------------+-------------------------+
+
+.. [1] JavaScript modules allow you to organize your JavaScript into small files
+ called modules and import them:
+
+ .. code-block:: javascript
+
+ // require third-party modules
+ var $ = require('jquery');
+
+ // require your own CoolComponent.js modules
+ var coolComponent = require('./components/CoolComponent');
+
+ Encore (via Webpack) parses these automatically and creates a JavaScript
+ file that contains all needed dependencies. You can even require CSS or
+ images.
+
+.. [2] Assetic has outdated support for React.js only. Encore ships with modern
+ support for React.js, Vue.js, TypeScript, etc.
+
+Should I Upgrade from Assetic to Encore
+---------------------------------------
+
+If you already have Assetic working in an application, and haven't needed any of
+the features that Encore offers over Assetic, continuing to use Assetic is fine.
+If you *do* start to need more features, then you might have a business case for
+changing to Encore.
diff --git a/frontend/encore/virtual-machine.rst b/frontend/encore/virtual-machine.rst
new file mode 100644
index 00000000000..068d5c8451f
--- /dev/null
+++ b/frontend/encore/virtual-machine.rst
@@ -0,0 +1,121 @@
+Using Encore in a Virtual Machine
+=================================
+
+Encore is compatible with virtual machines such as `VirtualBox`_ and `VMWare`_
+but you may need to make some changes to your configuration to make it work.
+
+File Watching Issues
+--------------------
+
+When using a virtual machine, your project root directory is shared with the
+virtual machine using `NFS`_. This introduces issues with files watching, so
+you must enable the `polling`_ option to make it work:
+
+.. code-block:: javascript
+
+ // webpack.config.js
+
+ // ...
+
+ // will be applied for `encore dev --watch` and `encore dev-server` commands
+ Encore.configureWatchOptions(watchOptions => {
+ watchOptions.poll = 250; // check for changes every 250 milliseconds
+ });
+
+Development Server Issues
+-------------------------
+
+Configure the Public Path
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+ You can skip this section if your application is running on
+ ``http://localhost`` instead a custom local domain-name like
+ ``http://app.vm``.
+
+When running the development server, you will probably see the following errors
+in the web console:
+
+.. code-block:: text
+
+ GET http://localhost:8080/build/vendors~app.css net::ERR_CONNECTION_REFUSED
+ GET http://localhost:8080/build/runtime.js net::ERR_CONNECTION_REFUSED
+ ...
+
+If your Symfony application is running on a custom domain (e.g.
+``http://app.vm``), you must configure the public path explicitly in your
+``package.json``:
+
+.. code-block:: diff
+
+ {
+ ...
+ "scripts": {
+ - "dev-server": "encore dev-server",
+ + "dev-server": "encore dev-server --public http://app.vm:8080",
+ ...
+ }
+ }
+
+After restarting Encore and reloading your web page, you will probably see
+different issues in the web console:
+
+.. code-block:: text
+
+ GET http://app.vm:8080/build/vendors~app.css net::ERR_CONNECTION_REFUSED
+ GET http://app.vm:8080/build/runtime.js net::ERR_CONNECTION_REFUSED
+
+You still need to make other configuration changes, as explained in the
+following sections.
+
+Allow External Access
+~~~~~~~~~~~~~~~~~~~~~
+
+Add the ``--host 0.0.0.0`` argument to the ``dev-server`` configuration in your
+``package.json`` file to make the development server accept all incoming
+connections:
+
+.. code-block:: diff
+
+ {
+ ...
+ "scripts": {
+ - "dev-server": "encore dev-server --public http://app.vm:8080",
+ + "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0",
+ ...
+ }
+ }
+
+.. caution::
+
+ Make sure to run the development server inside your virtual machine only;
+ otherwise other computers can have access to it.
+
+Fix "Invalid Host header" Issue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Webpack will respond ``Invalid Host header`` when trying to access files from
+the dev-server. To fix this, add the argument ``--disable-host-check``:
+
+.. code-block:: diff
+
+ {
+ ...
+ "scripts": {
+ - "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0",
+ + "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0 --disable-host-check",
+ ...
+ }
+ }
+
+.. caution::
+
+ Beware that `it's not recommended to disable host checking`_ in general, but
+ here it's required to solve the issue when using Encore in a virtual machine.
+
+.. _`VirtualBox`: https://www.virtualbox.org/
+.. _`VMWare`: https://www.vmware.com
+.. _`NFS`: https://en.wikipedia.org/wiki/Network_File_System
+.. _`polling`: https://webpack.js.org/configuration/watch/#watchoptionspoll
+.. _`it's not recommended to disable host checking`: https://webpack.js.org/configuration/dev-server/#devserverdisablehostcheck
diff --git a/frontend/encore/vuejs.rst b/frontend/encore/vuejs.rst
new file mode 100644
index 00000000000..4c67362ada1
--- /dev/null
+++ b/frontend/encore/vuejs.rst
@@ -0,0 +1,162 @@
+Enabling Vue.js (``vue-loader``)
+================================
+
+.. admonition:: Screencast
+ :class: screencast
+
+ Do you prefer video tutorials? Check out the `Vue screencast series`_.
+
+Want to use `Vue.js`_? No problem! First enable it in ``webpack.config.js``:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+ .addEntry('main', './assets/main.js')
+
+ + .enableVueLoader()
+ ;
+
+Then restart Encore. When you do, it will give you a command you can run to
+install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+Any ``.vue`` files that you require will be processed correctly. You can also
+configure the `vue-loader options`_ by passing an options callback to
+``enableVueLoader()``. See the `Encore's index.js file`_ for detailed documentation.
+
+Hot Module Replacement (HMR)
+----------------------------
+
+The ``vue-loader`` supports hot module replacement: just update your code and watch
+your Vue.js app update *without* a browser refresh! To activate it, just use the
+``dev-server`` with the ``--hot`` option:
+
+.. code-block:: terminal
+
+ $ yarn encore dev-server --hot
+
+That's it! Change one of your ``.vue`` files and watch your browser update. But
+note: this does *not* currently work for *style* changes in a ``.vue`` file. Seeing
+updated styles still requires a page refresh.
+
+See :doc:`/frontend/encore/dev-server` for more details.
+
+JSX Support
+-----------
+
+You can enable `JSX with Vue.js`_ by configuring the second parameter of the
+``.enableVueLoader()`` method:
+
+.. code-block:: diff
+
+ // webpack.config.js
+ // ...
+
+ Encore
+ // ...
+ .addEntry('main', './assets/main.js')
+
+ - .enableVueLoader()
+ + .enableVueLoader(() => {}, {
+ + useJsx: true
+ + })
+ ;
+
+Next, run or restart Encore. When you do, you will see an error message helping
+you install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+Your ``.jsx`` files will now be transformed through ``@vue/babel-preset-jsx``.
+
+Using styles
+~~~~~~~~~~~~
+
+You can't use ``