This PR was merged into the master branch.
Discussion
----------
[2.3][Session] Give greater control over how and when session starts
| Q | A
| ------------- | ---
| Bug fix? | no
| New feature? | yes
| BC breaks? | no
| Deprecations? | no
| Tests pass? | yes
| Fixed tickets | na
| License | MIT
| Doc PR | symfony/symfony-docs#2475
Refs #6036
Gives control over how start on demand works: allowing to turn it on or off and to allow bag access when session is off.
Commits
-------
f431cb0 Fix tests
1f521d8 Coding standards
2583c26 [HttpFoundation][FrameworkBundle] Keep save auto_start behaviour as in 2.2 and make component values consistent with FrameworkBundle's configuration options.
ceaf69b [FrameworkBundle] Use more sophisticated validation and configuration.
af0a140 [FrameworkBundle] Add configuration to allow control over session start on demand.
8fc2397 [HttpFoundation] Give control over how session start on demand.
This PR was squashed before being merged into the master branch (closes#7571).
Discussion
----------
[2.3] Handle PHP sessions started outside of Symfony
| Q | A
| ------------- | ---
| Bug fix? | no
| New feature? | yes
| BC breaks? | no
| Deprecations? | no
| Tests pass? | yes
| Fixed tickets |
| License | MIT
| Doc PR | symfony/symfony-docs#2474
This PR brings a way to allow Symfony2 to manage a session started outside of Symfony in such a way that quite explicit. It also introduces more robust detection of previously started sessions under PHP 5.3 and supports real session status detection under PHP 5.4
Commits
-------
df99902 [2.3] Handle PHP sessions started outside of Symfony
This PR was merged into the master branch.
Discussion
----------
[2.3] [FrameworkBundle] [Templating] added Stopwatch support to the PHP engine
| Q | A
| ------------- | ---
| Bug fix? | no
| New feature? | yes
| BC breaks? | no
| Deprecations? | no
| Tests pass? | yes
| License | MIT
I did not include tests nor documentation because there weren't any for TimedTwigEngine (I took it as an example). If I'm mistaken and they are needed, I'll gladly write them.
Commits
-------
3c3d34d [FrameworkBundle] [Templating] added Stopwatch support to the PHP engine
This PR was merged into the master branch.
Discussion
----------
[2.3] [WIP] Synchronized services...
| Q | A
| ------------- | ---
| Bug fix? | no
| New feature? | no
| BC breaks? | no
| Deprecations? | no
| Tests pass? | yes
| Fixed tickets | #5300, #6756
| License | MIT
| Doc PR | symfony/symfony-docs#2343
Todo:
- [x] update documentation
- [x] find a better name than contagious (synchronized)?
refs #6932, refs #5012
This PR is a proof of concept that tries to find a solution for some problems we have with scopes and services depending on scoped services (mostly the request service in Symfony).
Basically, whenever you want to inject the Request into a service, you have two possibilities:
* put your own service into the request scope (a new service will be created whenever a sub-request is run, and the service is not available outside the request scope);
* set the request service reference as non-strict (your service is always available but the request you have depends on when the service is created the first time).
This PR addresses this issue by allowing to use the second option but you service still always has the right Request service (see below for a longer explanation on how it works).
There is another issue that this PR fixes: edge cases and weird behaviors. There are several bug reports about some weird behaviors, and most of the time, this is related to the sub-requests. That's because the Request is injected into several Symfony objects without being updated correctly when leaving the request scope. Let me explain that: when a listener for instance needs the Request object, it can listen to the `kernel.request` event and store the request somewhere. So, whenever you enter a sub-request, the listener will get the new one. But when the sub-request ends, the listener has no way to know that it needs to reset the request to the master one. In practice, that's not really an issue, but let me show you an example of this issue in practice:
* You have a controller that is called with the English locale;
* The controller (probably via a template) renders a sub-request that uses the French locale;
* After the rendering, and from the controller, you try to generate a URL. Which locale the router will use? Yes, the French locale, which is wrong.
To fix these issues, this PR introduces a new notion in the DIC: synchronized services. When a service is marked as synchronized, all method calls involving this service will be called each time this service is set. When in a scope, methods are also called to restore the previous version of the service when the scope leaves.
If you have a look at the router or the locale listener, you will see that there is now a `setRequest` method that will called whenever the request service changes (because the `Container::set()` method is called or because the service is changed by a scope change).
Commits
-------
17269e1 [DependencyInjection] fixed management of scoped services with an invalid behavior set to null
bb83b3e [HttpKernel] added a safeguard for when a fragment is rendered outside the context of a master request
5d7b835 [FrameworkBundle] added some functional tests
ff9d688 fixed Request management for FragmentHandler
1b98ad3 fixed Request management for LocaleListener
a7b2b7e fixed Request management for RequestListener
0892135 [HttpKernel] ensured that the Request is null when outside of the Request scope
2ffcfb9 [FrameworkBundle] made the Request service synchronized
ec1e7ca [DependencyInjection] added a way to automatically update scoped services
This change allows any service to depend on the Request (via a method
call) and always have the right Request instance without the need for
the service to be in the request scope (you still need to set the
Request reference as non-strict).
* 2.2: (70 commits)
change wrapped exception message to be more usefull
updated VERSION for 2.0.23
update CONTRIBUTORS for 2.0.23
updated CHANGELOG for 2.0.23
[Form] fixed failing test
[DomCrawler] added support for query string with slash
Fixed invalid file path for hiddeninput.exe on Windows.
fix xsd definition for strict-requirements
[WebProfilerBundle] Fixed the toolbar styles to apply them in IE8
[ClassLoader] fixed heredocs handling
fixed handling of heredocs
Add a public modifier to an interface method
removing xdebug extension
[HttpRequest] fixes Request::getLanguages() bug
[HttpCache] added a test (cached content should be kept after purging)
[DoctrineBridge] Fixed non-utf-8 recognition
[Security] fixed HttpUtils class tests
replaced new occurences of 'Request::create()' with '::create()'
changed sub-requests creation to '::create()'
fixed merge issue
...
Conflicts:
src/Symfony/Bundle/FrameworkBundle/Command/TranslationUpdateCommand.php
src/Symfony/Bundle/WebProfilerBundle/Resources/views/Profiler/toolbar.html.twig
src/Symfony/Component/DomCrawler/Link.php
src/Symfony/Component/Translation/Translator.php
This PR was squashed before being merged into the master branch (closes#7202).
Commits
-------
817453c [2.2] add http_method_override option to ease setup
Discussion
----------
[2.2] add http_method_override option to ease setup
| Q | A
| ------------- | ---
| Bug fix? | no
| New feature? | yes
| BC breaks? | no
| Deprecations? | no
| Tests pass? | yes
| License | MIT
HttpContentRenderer has been renamed to FragmentHandler.
The RendererStrategy subnamespace has been renamed to Fragment.
The strategy classes now have Fragment in their names.
ProxyRouterListener has been renamed to FragmentListener
The router_proxy configuration entry has been renamed to fragments.
This PR was merged into the master branch.
Commits
-------
76fefe3 updated CHANGELOG and UPGRADE files
f7da1f0 added some unit tests (and fixed some bugs)
f17f586 moved the container aware HTTP kernel to the HttpKernel component
2eea768 moved the deprecation logic calls outside the new HttpContentRenderer class
bd102c5 made the content renderer work even when ESI is disabled or when no templating engine is available (the latter being mostly useful when testing)
a8ea4e4 [FrameworkBundle] deprecated HttpKernel::forward() (it is only used once now and not part of any interface anyway)
1240690 [HttpKernel] made the strategy a regular parameter in HttpContentRenderer::render()
adc067e [FrameworkBundle] made some services private
1f1392d [HttpKernel] simplified and enhanced code managing the hinclude strategy
403bb06 [HttpKernel] added missing phpdoc and tweaked existing ones
892f00f [HttpKernel] added a URL signer mechanism for hincludes
a0c49c3 [TwigBridge] added a render_* function to ease usage of custom rendering strategies
9aaceb1 moved the logic from HttpKernel in FrameworkBundle to the HttpKernel component
Discussion
----------
[WIP] Kernel refactor
Currently, the handling of sub-requests (including ESI and hinclude) is mostly done in FrameworkBundle. It makes these important features harder to implement for people using only HttpKernel (like Drupal and Silex for instance).
This PR moves the code to HttpKernel instead. The code has also been refactored to allow easier integration of other rendering strategies (refs #6108).
The internal route has been re-introduced but it can only be used for trusted IPs (so for the internal rendering which is managed by Symfony itself, or by a trusted reverse proxy like Varnish for ESI handling). For the hinclude strategy, when using a controller, the URL is automatically signed (see #6463).
The usage of a listener instead of a controller to handle internal sub-requests speeds up things quite a lot as it saves one sub-request handling. In Symfony 2.0 and 2.1, the handling of a sub-request actually creates two sub-requests.
Rendering a sub-request from a controller can be done with the following code:
```jinja
{# default strategy #}
{{ render(path("partial")) }}
{{ render(controller("SomeBundle:Controller:partial")) }}
{# ESI strategy #}
{{ render(path("partial"), { strategy: 'esi' }) }}
{{ render(controller("SomeBundle:Controller:partial"), { strategy: 'esi' }) }}
{# hinclude strategy #}
{{ render(path("default1"), { strategy: 'hinclude' }) }}
```
The second commit allows to simplify the calls a little bit thanks to some nice syntactic sugar:
```jinja
{# default strategy #}
{{ render(path("partial")) }}
{{ render(controller("SomeBundle:Controller:partial")) }}
{# ESI strategy #}
{{ render_esi(path("partial")) }}
{{ render_esi(controller("SomeBundle:Controller:partial")) }}
{# hinclude strategy #}
{{ render_hinclude(path("default1")) }}
```
---------------------------------------------------------------------------
by fabpot at 2013-01-03T17:58:49Z
I've just pushed a new version of the code that actually works in my browser (but I've not yet written any unit tests). I've updated the PR description accordingly.
All comments welcome!
---------------------------------------------------------------------------
by Koc at 2013-01-03T20:11:43Z
what about `render(controller="SomeBundle:Controller:partial", strategy="esi")`?
---------------------------------------------------------------------------
by stof at 2013-01-04T09:01:01Z
shouldn't we have interfaces for the UriSigner and the HttpContentRenderer ?
---------------------------------------------------------------------------
by lsmith77 at 2013-01-04T19:28:09Z
btw .. as mentioned in #6213 i think it would make sense to refactor the HttpCache to use a cache layer to allow more flexibility in where to cache the data (including clustering) and better invalidation. as such if you are refactoring HttpKernel .. it might also make sense to explore splitting off HttpCache.
---------------------------------------------------------------------------
by fabpot at 2013-01-04T19:30:07Z
@lsmith77 This is a totally different topic. This PR is just about moving things from FrameworkBundle to HttpKernel to make them more reusable outside of the full-stack framework.
---------------------------------------------------------------------------
by fabpot at 2013-01-05T09:39:52Z
I think this PR is almost ready now. I still need to update the docs and add some unit tests. Any other comments on the whole approach? The class names? The `controller` function thingy? The URI signer mechanism? The proxy protection for the internal controller? The proxy to handle internal routes?
---------------------------------------------------------------------------
by sstok at 2013-01-05T10:08:25Z
Looks good to me 👍
---------------------------------------------------------------------------
by sdboyer at 2013-01-07T18:17:08Z
@Crell asked me to weigh in, since i'm one of the Drupal folks who's likely to work most with this.
i think i've grokked about 60% of the big picture here, and i'm generally happy with what i see. the assumption that the HInclude strategy makes about working with templates probably isn't one that we'll be able to use (and so, would need to write our own), but that's not a big deal since the whole goal here is to make strategies pluggable.
so, yeah. +1.
---------------------------------------------------------------------------
by winzou at 2013-01-09T20:21:44Z
Just for my information: will this PR be merged for 2.2 version? Thanks.
---------------------------------------------------------------------------
by stof at 2013-01-09T20:41:04Z
@winzou according to the blog post announcing the beta 1 release, yes. It is explicitly listed as being one of the reason to make it a beta instead of the first RC.
---------------------------------------------------------------------------
by winzou at 2013-01-09T20:49:36Z
OK thanks, I've totally skipped this blog post.
---------------------------------------------------------------------------
by fabpot at 2013-01-10T15:26:15Z
I've just added a bunch of unit tests and fix some bugs I found while writing the tests.
This PR was merged into the master branch.
Commits
-------
586a16e [Validator] Changed DefaultTranslator::getLocale() to always return 'en'
58bfd60 [Validator] Improved the inline documentation of DefaultTranslator
cd662cc [Validator] Added ExceptionInterface, BadMethodCallException and InvalidArgumentException
e00e5ec [Validator] Fixed failing test
cc0df0a [Validator] Changed validator to support pluralized messages by default
56d61eb [Form][Validator] Added BC breaks in unstable code to the CHANGELOG
1e34e91 [Form] Added upgrade instructions to the UPGRADE file
b94a256 [DoctrineBridge] Adapted DoctrineBridge to translator integration in the validator
c96a051 [FrameworkBundle] Adapted FrameworkBundle to translator integration in the validator
92a3b27 [TwigBridge] Adapted TwigBridge to translator integration in the validator
e7eb5b0 [Form] Adapted Form component to translator integration in the validator
46f751c [Validator] Extracted message interpolation logic of ConstraintViolation and used the Translation component for that
Discussion
----------
[Validator] Integrated the Translator in the Validator component
Bug fix: no
Feature addition: no
Backwards compatibility break: yes
Symfony2 tests pass: yes
Fixes the following tickets: #5844, #6117
Todo: -
License of the code: MIT
Documentation PR: -
This PR allows to replace the default message substitution strategy in the validator (`strtr()`) by passing an implementation of `Symfony\Component\Translation\TranslatorInterface`. The motivation for this are both #5844 and the need to replace the translation strategy in Drupal's integration of the Validator.
In the stand-alone usage of the validator, both the translator and the default translation domain can now be passed to `ValidatorBuilderInterface`:
```php
$validator = Validation::createValidatorBuilder()
->setTranslator(new MyTranslator())
->setTranslationDomain('validators')
->getValidator();
```
References:
* #5844
* #6117
* #6129
* [Add a validation framework to Drupal 8](http://drupal.org/node/1845546)
* [Add the symfony validator component to core despite Symfony potentially releasing BC-breaking updates after 2.3.](http://drupal.org/node/1849564)
---------------------------------------------------------------------------
by Tobion at 2012-11-28T08:53:25Z
no BC break? Looking at ValidatorBuilderInterface there is definitely one.
---------------------------------------------------------------------------
by bschussek at 2012-11-28T08:55:01Z
ValidatorBuilderInterface is not part of the stable API. You are not supposed to implement this interface.
---------------------------------------------------------------------------
by Tobion at 2012-11-28T09:01:07Z
We're not only documenting bc breaks for stable API, otherwise we could remove 90% of the upgrade file since few methods are tagged with API.
An interface that nobody should implement?
---------------------------------------------------------------------------
by bschussek at 2012-11-28T09:30:02Z
The question is what to consider a BC break. Something will always break for someone. Should we consequently mark everything as BC break? I don't think so.
For example, since 2.1, you are supposed to use `Validation::createValidator*()` for creating a validator. Because of that, I won't consider changing the constructor signature of `Validator` a BC break anymore from 2.1 on.
The same for the unstable interfaces. These are currently meant to be used only, that is, type hint against them and call their methods. But we don't guarantee that we won't add methods to them.
---------------------------------------------------------------------------
by Tobion at 2012-11-28T09:38:19Z
I agree that almost any change could be considered a BC break. So we probably need to better define what a BC break is and what not. Otherwise Symfony will stop evolving after 2.3 because from then on Fabien wanted to prevent BC breaks which is almost impossible in a strict definition of bc break.
---------------------------------------------------------------------------
by fabpot at 2012-11-28T11:37:22Z
BC breaks should always be documented, and we guarantee BC only for things tagged with @api. I'm going to update the docs to make things clearer.
---------------------------------------------------------------------------
by bschussek at 2012-11-28T13:09:57Z
@fabpot I documented these changes now in the CHANGELOG: af99ebb1206ac92889b7193ba1ecc12bf2617e85
Are we sure we want to document *all* BC breaks from now on, even in non-@api code? This could rather scare people looking at our changelogs (lots of BC BREAKS there).
---------------------------------------------------------------------------
by fago at 2012-11-28T17:29:58Z
Unfortunately, it turns out the symfony translator interface does not mach the Drupal translation system as well as we initally thought, see http://drupal.org/node/1852106. Given that, this would integrating the validator component into Drupal even harder, because it introduces the dependency on the (unwanted) translation component. :(
---------------------------------------------------------------------------
by stof at 2012-11-28T18:19:36Z
If this does not help Drupal anyway, maybe #5844 is a better way to manage translations for people using the validator outside forms ?
and the Drupal guys would simply follow a similar approach, but based on their own translator instead of the symfony one.
---------------------------------------------------------------------------
by fago at 2012-11-28T18:50:12Z
Yeah. The only problem I see with the approach of #5844 is that *after* validation only the translated messages are available. We'd need to have access to the untranslated messages also.
---------------------------------------------------------------------------
by fago at 2012-11-29T09:49:47Z
As our translation system handles translating pluralized messages differently, the current ExecutionContextInterface::addViolation() method poses a problem also. We need to pass on - both the single and plural - message, as the message gets chosen during translation, see http://api.drupal.org/api/drupal/core!includes!common.inc/function/format_plural/8
So maybe, we could allow adding an already created ConstraintViolation object also? Then, we could implement a "PluralConstraintViolation" class that takes both message templates.
---------------------------------------------------------------------------
by bschussek at 2012-12-03T15:52:36Z
I updated this PR to support pluralized messages by default in the validator. This should solve the problem of the Drupal guys, because their implementation of `TranslatorInterface::transChoice($id, $number, ...)` can now simply split the $id by pipes (`|`) and pass the parts to their own `format_plural($count, $singular, $plural, ...)` function.
For us, it breaks BC because translation catalog sources had to be adapted.
---------------------------------------------------------------------------
by fabpot at 2012-12-03T16:25:52Z
Most of the XLF files are broken (the end is missing now).
IIUC, we now have a hard dependency on the Translation component, which is something we wanted to avoid.
---------------------------------------------------------------------------
by fabpot at 2012-12-03T16:27:56Z
Oops, clicked on the "comment" button too fast.
So, the dependency is hard (you need to install the dep) but light as we only rely on the translation interface from the component (when using the default translator). It looks acceptable to me, especially because we now use Composer to manage dependencies.
---------------------------------------------------------------------------
by bschussek at 2012-12-03T16:54:10Z
@fabpot Thanks for the hint. Going to fix this.
---------------------------------------------------------------------------
by bschussek at 2012-12-04T11:34:43Z
@fabpot Fixed.
---------------------------------------------------------------------------
by bschussek at 2012-12-07T12:40:24Z
Is there anything missing for this PR to be merged?
* 2.1:
[Console] Fix style escaping parsing
[Console] Make style formatter matching less greedy to avoid having to escape when not needed
[Bundle] [FrameworkBundle] fixed indentation in esi.xml services file.
[Component] [Security] fixed PSR-2 coding violation in ClassUtilsTest class.
[Form] Fixed EntityChoiceList when loading objects with negative integer IDs
[TwigBundle] There is no CSS visibility of display, should be visible instead
[Form] corrected source node for a Danish translation
[DependencyInjection] fixed a bug where the strict flag on references were lost (closes#6607)
[HttpFoundation] Check if required shell functions for `FileBinaryMimeTypeGuesser` are not disabled
[CssSelector] added css selector with empty string
[HttpFoundation] Docblock for Request::isXmlHttpRequest() now points to Wikipedia
[DependencyInjection] refactored code to avoid logic duplication
[Form] Deleted references in FormBuilder::getFormConfig() to improve performance
[HttpFoundation] Update docblock for non-working method
Conflicts:
src/Symfony/Bundle/TwigBundle/Resources/views/Exception/trace.html.twig
src/Symfony/Bundle/TwigBundle/Resources/views/Exception/traces.html.twig
* 2.0:
[Bundle] [FrameworkBundle] fixed indentation in esi.xml services file.
[TwigBundle] There is no CSS visibility of display, should be visible instead
[DependencyInjection] fixed a bug where the strict flag on references were lost (closes#6607)
[HttpFoundation] Check if required shell functions for `FileBinaryMimeTypeGuesser` are not disabled
[CssSelector] added css selector with empty string
[HttpFoundation] Docblock for Request::isXmlHttpRequest() now points to Wikipedia
[DependencyInjection] refactored code to avoid logic duplication
Conflicts:
src/Symfony/Bundle/FrameworkBundle/Resources/config/esi.xml
src/Symfony/Component/DependencyInjection/Dumper/PhpDumper.php
src/Symfony/Component/HttpFoundation/File/MimeType/FileBinaryMimeTypeGuesser.php
This PR was merged into the master branch.
Commits
-------
5e359d3 made the kernel optional in all data collectors
Discussion
----------
made the kernel optional in all data collectors
* 2.1:
fixed typo
[FrameworkBundle] fixed ESI calls
[FrameworkBundle] fixed ESI calls
bumped Symfony version to 2.1.6-DEV
updated VERSION for 2.1.5
updated CHANGELOG for 2.1.5
bumped Symfony version to 2.0.21-DEV
[FrameworkBundle] fixed trusted_proxies configuration for some edge cases
[FrameworkBundle] fixed XSD for the trusted-proxies setting
updated VERSION for 2.0.20
update CONTRIBUTORS for 2.0.20
updated CHANGELOG for 2.0.20
Conflicts:
src/Symfony/Bundle/FrameworkBundle/HttpKernel.php
src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/ConfigurationTest.php
src/Symfony/Component/HttpKernel/Kernel.php
* 2.0:
bumped Symfony version to 2.0.21-DEV
[FrameworkBundle] fixed trusted_proxies configuration for some edge cases
[FrameworkBundle] fixed XSD for the trusted-proxies setting
updated VERSION for 2.0.20
update CONTRIBUTORS for 2.0.20
updated CHANGELOG for 2.0.20
Conflicts:
CONTRIBUTORS.md
src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/ConfigurationTest.php
src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/Fixtures/xml/full.xml
src/Symfony/Component/HttpKernel/Kernel.php
The ContainerAwareTraceableEventDispatcher class was tied to both the
Symfony container and the HttpKernel profiler. It made it non reusable
in another context.
The new TraceableEventDispatcher only keeps the HttpKernel profiler
integration and is able to wrap any other event dispatcher. It makes it
reusable in frameworks using the Symfony HttpKernel component like
Silex.
The only drawback is that we don't have access to the listener
priorities in the collected data anymore (but the listeners are still
ordered correctly). The change is still worth it I think.
Commits
-------
22e9036 updated CHANGELOG
bafe890 [FrameworkBundle] changed Client::enableProfiler() behavior to fail silently when the profiler is not available (it makes it easier to write functional tests)
f41872b [FrameworkBundle] added a way to enable the profiler for the very next request in functional tests (closes#4307)
67b91e5 [HttpKernel] added a way to enable a disable Profiler
Discussion
----------
[2.2] added a way to enable the profiler for the very next request in a functional test
Bug fix: yes/no
Feature addition: yes
Backwards compatibility break: no
Symfony2 tests pass: yes
Fixes the following tickets: #4307
Todo: -
License of the code: MIT
Documentation PR: should be done before merging
After merging this PR, we need to disable the profiler in the test environment in Symfony SE.
Commits
-------
cd7835d [Form] Cached the form type hierarchy in order to improve performance
2ca753b [Form] Fixed choice list hashing in DoctrineType
2bf4d6c [Form] Fixed FormFactory not to set "data" option if not explicitely given
7149d26 [Form] Removed invalid PHPDoc text
Discussion
----------
[Form] WIP Improved performance of form building
Bug fix: no
Feature addition: no
Backwards compatibility break: no
Symfony2 tests pass: yes
Fixes the following tickets: -
Todo: **Update the Silex extension**
This PR is work in progress and up for discussion. It increases the performance of FormFactory::createForm() on a specific, heavy-weight form from **0.848** to **0.580** seconds.
Before, the FormFactory had to traverse the hierarchy and calculate the default options of each FormType everytime a form was created of that type.
Now, FormTypes are wrapped within instances of a new class `ResolvedFormType`, which caches the parent type, the type's extensions and its default options.
The updated responsibilities: `FormFactory` is a registry and proxy for `ResolvedFormType` objects, `FormType` specifies how a form can be built on a specific layer of the type hierarchy (e.g. "form", or "date", etc.) and `ResolvedFormType` *does the actual building* across all layers of the hierarchy (by delegating to the parent type, which delegates to its parent type etc.).
---------------------------------------------------------------------------
by schmittjoh at 2012-07-12T18:25:40Z
Maybe ResolvedFormType
---------------------------------------------------------------------------
by jmather at 2012-07-13T02:56:38Z
I really like ResolvedFormType. That's the naming method I took for my tag parser that handes the same conceptual issue.
---------------------------------------------------------------------------
by axelarge at 2012-07-13T05:25:00Z
ResolvedFormType sounds very clear.
This change is great and I desperately hope to see more of this kind
---------------------------------------------------------------------------
by Baachi at 2012-07-13T06:41:26Z
Yes `ResolvedFormType` sounds good :) 👍
---------------------------------------------------------------------------
by fabpot at 2012-07-13T07:11:33Z
I like `ResolvedFormType` as well.
---------------------------------------------------------------------------
by henrikbjorn at 2012-07-13T07:46:48Z
👍 `ResolvedFormType` :shipit:
---------------------------------------------------------------------------
by stof at 2012-07-13T18:01:51Z
This looks good to me
The charset was configurable in a configuration file but it never worked:
framework:
charset: ISO-8859-1
Now, like for the cache and log dirs, you can configure the charset by
overriding the getCharset() method in the app kernel:
public function getCharset()
{
return 'ISO-8859-1';
}
Commits
-------
7464dcd added phpdoc
c413e7b [Routing] remove RequestContextAwareInterface from RequestMatcherInterface
921be34 [Routing] fix phpdoc
Discussion
----------
[Routing] RequestMatcherInterface doesn't need context
Matchers that implement RequestMatcherInterface should match a Request, thus they don't need the request context.
---------------------------------------------------------------------------
by travisbot at 2012-06-14T21:39:48Z
This pull request [fails](http://travis-ci.org/symfony/symfony/builds/1624496) (merged f5ff1fe0 into 7c91ee57).
---------------------------------------------------------------------------
by schmittjoh at 2012-06-15T13:32:59Z
I think it makes sense to remove the RequestContext from the RequestMatcher.
---------------------------------------------------------------------------
by travisbot at 2012-06-15T15:54:28Z
This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1628931) (merged 7464dcd2 into f881d282).
---------------------------------------------------------------------------
by Tobion at 2012-06-26T12:32:06Z
Anything missing?
$_SERVER['REQUEST_URI'] will contain the query params so is_file will fail.
Change it to use $_SERVER['SCRIPT_NAME'] instead which only contains the
relative filename of the the script.
CSRF fields are now only added when the view is built. For this reason we already know if
the form is the root form and avoid to create unnecessary CSRF fields for nested fields.
Commits
-------
cdba4cf [FrameworkBundle] Change XSD to allow string replacements on session args.
52f7955 [FrameworkBundle] Remove default from gc_* session configuration keys.
749593d [FrameworkBundle] Allow configuration of session garbage collection for session 'keep-alive'.
Discussion
----------
[2.1][FrameworkBundle] Allow configuration of session garbage collection
Bug fix: no
Feature addition: yes
Backwards compatibility break: no
Symfony2 tests pass: yes
Fixes the following tickets: #2171
Todo: -
---------------------------------------------------------------------------
by drak at 2012-03-21T21:56:20Z
@fabpot - this PR is ready for merge. It basically allows configuration of some session ini values that are necessary in controlling the session behaviour.
---------------------------------------------------------------------------
by dlsniper at 2012-03-21T22:57:18Z
@drak shouldn't all the options here: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpFoundation/Session/Storage/NativeSessionStorage.php#L266 be available for configuration, or am I just reading the source wrong and they already are?
In this case should I make a separate PR to cover the rest or could you do it in this one?
---------------------------------------------------------------------------
by fabpot at 2012-03-23T14:56:22Z
@drak: the discussion is the ticket is very interesting and I think it should be part of a cookbook in the documentation. Can you take care of that before I merge this PR? Thanks.
---------------------------------------------------------------------------
by drak at 2012-03-25T15:32:59Z
@fabpot - yes - it's on the todo list. Will update this PR when done.
---------------------------------------------------------------------------
by drak at 2012-03-26T19:45:13Z
@fabpot - this is ready for merging, the documentation is done (the PR is in but I'll tweak it, but no need to wait to merge this PR). I will also add something extra to cookbook (I wrote docs for the component).
Commits
-------
df11e62 [FrameworkBundle] Used $output->write() instead of echo
c3bf479 [FrameworkBundle] Used Process component
cfa2dff [FrameworkBundle] Changed server:run command description
e7d38c1 [FrameworkBundle] Changed PHP version detection (see: #3529)
4a3f6d5 [FrameworkBundle] Removed global variable from router script
519d431 [FrameworkBundle] Fixed built-in server router script
d9a0a17 [FrameworkBundle] Added server:run command
Discussion
----------
[FrameworkBundle] Added server:run command (PHP 5.4 built-in web server)
Bug fix: no
Feature addition: yes
Backwards compatibility break: no
Symfony2 tests pass: [](http://travis-ci.org/michal-pipa/symfony)
Fixes the following tickets: -
Todo: -
PHP 5.4 comes with [built-in web server](http://www.php.net/manual/en/features.commandline.webserver.php). I've created command which allows to easily run Symfony2 application using this new feature.
Usage:
server:run [-d|--docroot="..."] [-r|--router="..."] [address]
Arguments:
address Address:port (default: 'localhost:8000')
Options:
--docroot (-d) Document root (default: 'web/')
--router (-r) Path to custom router script
Help:
The server:run runs Symfony2 application using PHP built-in web server:
app/console server:run
To change default bind address and port use the address argument:
app/console server:run 127.0.0.1:8080
To change default docroot directory use the --docroot option:
app/console server:run --docroot=htdocs/
If you have custom docroot directory layout, you can specify your own
router script using --router option:
app/console server:run --router=app/config/router.php
See also: http://www.php.net/manual/en/features.commandline.webserver.php
It requires PHP 5.4, otherwise this command will be disabled.
I think that this is very convenient (especially for new users). All you have to do is download Symfony, install vendors and run this command. You don't have to configure "real" web server, in fact any other server is not required. You don't have cache and logs permission problem, because server runs with your local user permissions.
---------------------------------------------------------------------------
by blogsh at 2012-03-06T17:38:10Z
Great feature! I was about to write something like this when I saw that you have already started implementing this :)
Some issues:
1. Missing newlines at the end of the files
2. If I try this server command with the default Symfony Standard Edition Acme demo the links on the main page do not work. The demo link links to "//demo" and the configurator link to "//_configurator". If I go to `localhost:8000/demo` directly the page is rendered as usual and all sub links are generated correctly. I could solve the problem by adding one line:
$_SERVER['SCRIPT_FILENAME'] = 'ANYTHING';
require 'app_dev.php';
I'm not sure where this problem comes from. Do you experience the same behaviour? Otherwise I'll do some more investigations to find the source of the problem.
3 . I think it would be a nice feature if you would generate a router.php based on the setting of the --env flag if no custom router file has been specified. This way it would be easy to switch between dev and prod.
---------------------------------------------------------------------------
by michal-pipa at 2012-03-06T19:00:24Z
@blogsh
> Missing newlines at the end of the files
I've checked and I can see newlines at the end of files. Are you sure about this?
> If I try this server command with the default Symfony Standard Edition Acme demo the links on the main page do not work. The demo link links to "//demo" and the configurator link to "//_configurator". If I go to localhost:8000/demo directly the page is rendered as usual and all sub links are generated correctly. I could solve the problem by adding one line:
>
> $_SERVER['SCRIPT_FILENAME'] = 'ANYTHING';
> require 'app_dev.php';
>
> I'm not sure where this problem comes from. Do you experience the same behaviour? Otherwise I'll do some more investigations to find the source of the problem.
I can reproduce this by changing front controller name from `app.php` to `app_dev.php`. I'll investigate on this.
> I think it would be a nice feature if you would generate a router.php based on the setting of the --env flag if no custom router file has been specified. This way it would be easy to switch between dev and prod.
You can easily change environment specifying front controller in URL. It works exactly the same way as default Apache configuration. This is intended behavior, as it would be misleading if every server had different rewrite rules.
If you really want to change it, then you can write your own router and pass it as a value to `router` option.
---------------------------------------------------------------------------
by blogsh at 2012-03-06T19:13:55Z
Wasn't aware that github omits the trailing white line, sorry.
Normally I use a rather inflexible nginx configuration, so I also wasn't aware of this (rather obvious) trick of changing the url. Thanks for that.
---------------------------------------------------------------------------
by stof at 2012-03-06T22:12:16Z
@blogsh it does not omit it. It displays it in the Linux way where the newline char is part of the line (and so there is a message ``no newline at end of file`` in the diff when it is missing).
---------------------------------------------------------------------------
by michal-pipa at 2012-03-07T07:18:23Z
@blogsh I've fixed router script. Now you can use both front controllers.
---------------------------------------------------------------------------
by michal-pipa at 2012-03-07T07:34:58Z
I've also hardcoded front controller name in router script and removed global variable, as there was no way to unset it.
---------------------------------------------------------------------------
by michal-pipa at 2012-03-13T07:57:04Z
I've used Process component, but now I don't get any stdout output (only stderr).
---------------------------------------------------------------------------
by michal-pipa at 2012-03-13T18:01:58Z
I've replaced `echo` by `$output->write()` and removed `$process` as it was not used actually.
Revert service back to session.storage.native
Rename session.storage.native_file to session.handler.native_file (which is the default so no BC break from 2.0)
Commits
-------
cea2c7e removed unneeded local variable
924f378 updated changelog
72d5805 changed route name
41cc0d6 [FrameworkBundle] added support for HInclude
Discussion
----------
[FrameworkBundle] added support for HInclude
Bug fix: no
Feature addition: yes
Backwards compatibility break: no
Symfony2 tests pass: yes
Fixes the following tickets: -
Todo: discuss
Example: https://github.com/kbond/symfony-standard/tree/hinclude
**Reopened this as I broke #2903**
References:
- http://groups.google.com/group/symfony-devs/browse_thread/thread/b74e587d6f2f87b0
- http://groups.google.com/group/symfony-devs/browse_thread/thread/8776a9833d4a5f79
- #2903
- #2865
[](http://travis-ci.org/kbond/symfony)
---------------------------------------------------------------------------
by kbond at 2012-02-11T20:27:22Z
unless there is anything else I think this is ready, want me to squash again?
---------------------------------------------------------------------------
by fabpot at 2012-02-11T21:07:33Z
@kbond: Can you add some information about the changes in the CHANGELOG?
---------------------------------------------------------------------------
by Tobion at 2012-02-11T21:33:32Z
Do I see it correctly that we cannot set a default template on a per hinclude tag basis? But only global?
That's not really usefull when javascript is disabled because it should resemble the content to be included as an alternative.
---------------------------------------------------------------------------
by stof at 2012-02-11T21:42:15Z
@Tobion currently it is not possible. But changing the content on a tag basis may require changing the way the render tag look like (as there is no content in the tag currently) so this needs further discussion and @fabpot said he wants to merge a first implementation without it. See the discussion above.
Commits
-------
887c0e9 moved EngineInterface::stream() to a new StreamingEngineInterface to keep BC with 2.0
473741b added the possibility to change a StreamedResponse callback after its creation
8717d44 moved a test in the constructor
e44b8ba made some cosmetic changes
0038d1b [HttpFoundation] added support for streamed responses
Discussion
----------
[HttpFoundation] added support for streamed responses
To stream a Response, use the StreamedResponse class instead of the
standard Response class:
$response = new StreamedResponse(function () {
echo 'FOO';
});
$response = new StreamedResponse(function () {
echo 'FOO';
}, 200, array('Content-Type' => 'text/plain'));
As you can see, a StreamedResponse instance takes a PHP callback instead of
a string for the Response content. It's up to the developer to stream the
response content from the callback with standard PHP functions like echo.
You can also use flush() if needed.
From a controller, do something like this:
$twig = $this->get('templating');
return new StreamedResponse(function () use ($templating) {
$templating->stream('BlogBundle:Annot:streamed.html.twig');
}, 200, array('Content-Type' => 'text/html'));
If you are using the base controller, you can use the stream() method instead:
return $this->stream('BlogBundle:Annot:streamed.html.twig');
You can stream an existing file by using the PHP built-in readfile() function:
new StreamedResponse(function () use ($file) {
readfile($file);
}, 200, array('Content-Type' => 'image/png');
Read http://php.net/flush for more information about output buffering in PHP.
Note that you should do your best to move all expensive operations to
be "activated/evaluated/called" during template evaluation.
Templates
---------
If you are using Twig as a template engine, everything should work as
usual, even if are using template inheritance!
However, note that streaming is not supported for PHP templates. Support
is impossible by design (as the layout is rendered after the main content).
Exceptions
----------
Exceptions thrown during rendering will be rendered as usual except that
some content might have been rendered already.
Limitations
-----------
As the getContent() method always returns false for streamed Responses, some
event listeners won't work at all:
* Web debug toolbar is not available for such Responses (but the profiler works fine);
* ESI is not supported.
Also note that streamed responses cannot benefit from HTTP caching for obvious
reasons.
---------------------------------------------------------------------------
by Seldaek at 2011/12/21 06:34:13 -0800
Just an idea: what about exposing flush() to twig? Possibly in a way that it will not call it if the template is not streaming. That way you could always add a flush() after your </head> tag to make sure that goes out as fast as possible, but it wouldn't mess with non-streamed responses. Although it appears flush() doesn't affect output buffers, so I guess it doesn't need anything special.
When you say "ESI is not supported.", that means only the AppCache right? I don't see why this would affect Varnish, but then again as far as I know Varnish will buffer if ESI is used so the benefit of streaming there is non-existent.
---------------------------------------------------------------------------
by cordoval at 2011/12/21 08:04:21 -0800
wonder what the use case is for streaming a response, very interesting.
---------------------------------------------------------------------------
by johnkary at 2011/12/21 08:19:48 -0800
@cordoval Common use cases are present fairly well by this RailsCast video: http://railscasts.com/episodes/266-http-streaming
Essentially it allows faster fetching of web assets (JS, CSS, etc) located in the <head></head>, allowing those assets to be fetched as soon as possible before the remainder of the content body is computed and sent to the browser. The end goal is to improve page load speed.
There are other uses cases too like making large body content available quickly to the service consuming it. Think if you were monitoring a live feed of JSON data of newest Twitter comments.
---------------------------------------------------------------------------
by lsmith77 at 2011/12/21 08:54:35 -0800
How does this relate the limitations mentioned in:
http://yehudakatz.com/2010/09/07/automatic-flushing-the-rails-3-1-plan/
Am I right to understand that due to how twig works we are not really streaming the content pieces when we call render(), but instead the entire template with its layout is rendered and only then will we flush? or does it mean that the render call will work its way to the top level layout template and form then on it can send the content until it hits another block, which it then first renders before it continues to send the data?
---------------------------------------------------------------------------
by stof at 2011/12/21 09:02:53 -0800
@lsmith77 this is why the ``stream`` method calls ``display`` in Twig instead of ``render``. ``display`` uses echo to print the output of the template line by line (and blocks are simply method calls in the middle). Look at your compiled templates to see it (the ``doDisplay`` method)
Rendering a template with Twig simply use an output buffer around the rendering.
---------------------------------------------------------------------------
by fabpot at 2011/12/21 09:24:33 -0800
@lsmith77: We don't have the Rails problem thanks to Twig as the order of execution is the right one by default (the layout is executed first); it means that we can have the flush feature without any change to how the core works. As @stof mentioned, we are using `display`, not `render`, so we are streaming your templates for byte one.
---------------------------------------------------------------------------
by fabpot at 2011/12/21 09:36:41 -0800
@Seldaek: yes, I meant ESI with the PHP reverse proxy.
---------------------------------------------------------------------------
by fabpot at 2011/12/21 09:37:34 -0800
@Seldaek: I have `flush()` support for Twig on my todo-list. As you mentioned, It should be trivial to implement.
---------------------------------------------------------------------------
by fzaninotto at 2011/12/21 09:48:18 -0800
How do streaming responses deal with assets that must be called in the head, but are declared in the body?
---------------------------------------------------------------------------
by fabpot at 2011/12/21 09:52:12 -0800
@fzaninotto: What do you mean?
With Twig, your layout is defined with blocks ("holes"). These blocks are overridden by child templates, but evaluated as they are encountered in the layout. So, everything works as expected.
As noted in the commit message, this does not work with PHP templates for the problems mentioned in the Rails post (as the order of execution is not the right one -- the child template is first evaluated and then the layout).
---------------------------------------------------------------------------
by fzaninotto at 2011/12/21 10:07:35 -0800
I was referring to using Assetic. Not sure if this compiles to Twig the same way as javascript and stylesheet blocks placed in the head - and therefore executed in the right way.
---------------------------------------------------------------------------
by fabpot at 2011/12/21 10:34:59 -0800
@Seldaek: I've just added a `flush` tag in Twig 1.5: 1d6dfad4f5
---------------------------------------------------------------------------
by catchamonkey at 2011/12/21 13:29:22 -0800
I'm really happy you've got this into the core, it's a great feature to have! Good work.
Commits
-------
4afc6ac Updated CHANGELOG-2.1
3d3239c Added Filesystem Component mention in composer.json
5775a0a Added composer.json
b26ae4a Added README
fbe9507 Added LICENSE
818a332 [Component] Moved Filesystem class to its own component
Discussion
----------
Filesystem component
Related to #2946
William
---------------------------------------------------------------------------
by stof at 2011/12/22 10:58:25 -0800
you need to add the new component in the ``replace`` section of the main composer.json, and you also need to add it as a dependency for FrameworkBundle as it defines a service using it.
---------------------------------------------------------------------------
by stof at 2011/12/22 10:59:34 -0800
and you need to update the changelog file
---------------------------------------------------------------------------
by willdurand at 2011/12/22 11:06:04 -0800
@stof thanks. Is it ok ?
---------------------------------------------------------------------------
by stof at 2011/12/22 11:13:31 -0800
mentioning the move only once in the changelog would probably be enough (and it is especially not needed in the FrameworkBundle section IMO) but otherwise it's fine
To stream a Response, use the StreamedResponse class instead of the
standard Response class:
$response = new StreamedResponse(function () {
echo 'FOO';
});
$response = new StreamedResponse(function () {
echo 'FOO';
}, 200, array('Content-Type' => 'text/plain'));
As you can see, a StreamedResponse instance takes a PHP callback instead of
a string for the Response content. It's up to the developer to stream the
response content from the callback with standard PHP functions like echo.
You can also use flush() if needed.
From a controller, do something like this:
$twig = $this->get('templating');
return new StreamedResponse(function () use ($templating) {
$templating->stream('BlogBundle:Annot:streamed.html.twig');
}, 200, array('Content-Type' => 'text/html'));
If you are using the base controller, you can use the stream() method instead:
return $this->stream('BlogBundle:Annot:streamed.html.twig');
You can stream an existing file by using the PHP built-in readfile() function:
new StreamedResponse(function () use ($file) {
readfile($file);
}, 200, array('Content-Type' => 'image/png');
Read http://php.net/flush for more information about output buffering in PHP.
Note that you should do your best to move all expensive operations to
be "activated/evaluated/called" during template evaluation.
Templates
---------
If you are using Twig as a template engine, everything should work as
usual, even if are using template inheritance!
However, note that streaming is not supported for PHP templates. Support
is impossible by design (as the layout is rendered after the main content).
Exceptions
----------
Exceptions thrown during rendering will be rendered as usual except that
some content might have been rendered already.
Limitations
-----------
As the getContent() method always returns false for streamed Responses, some
event listeners won't work at all:
* Web debug toolbar is not available for such Responses (but the profiler works fine);
* ESI is not supported.
Also note that streamed responses cannot benefit from HTTP caching for obvious
reasons.
Commits
-------
3ae976c fixed CS
84ad40d added cache clear hook
Discussion
----------
[Cache][2.1] Added cache clear hook
Allows bundles to hook into the `cache:clear` command by using the `kernel.cache_clearer` tag instead of using the `event_dispatcher` service.
See #1884
Bug fix: No
Feature addition: Yes
Backwards compatibility break: No
Symfony2 tests pass: Yes
Fixes the following tickets: #1884
References the following tickets: #1884
---------------------------------------------------------------------------
by dustin10 at 2011/12/16 11:03:54 -0800
Rebased to squash all commits into one.
---------------------------------------------------------------------------
by lsmith77 at 2011/12/17 05:27:29 -0800
@fabpot: we figured that priorities wouldn't be needed for cleaning .. haven't tested the PR, but conceptually it looks good to me and aside from the priority stuff its modeled after the cache warners.
---------------------------------------------------------------------------
by dustin10 at 2011/12/19 09:46:26 -0800
@fabpot Updated to pass cache dir to `clear` method.
---------------------------------------------------------------------------
by dustin10 at 2011/12/19 10:02:21 -0800
@stof and @fabpot Another thought I just had. Should the `$this->getContainer()->get('cache_clearer')->clear($realCacheDir);` call in the `CacheClearCommand` be done before the warming?
---------------------------------------------------------------------------
by stof at 2011/12/19 10:03:59 -0800
indeed. the clearing should be done before the warming.
---------------------------------------------------------------------------
by dustin10 at 2011/12/19 10:19:28 -0800
Squashed all commits into one. Let me know if there is anything else.
---------------------------------------------------------------------------
by dustin10 at 2011/12/19 10:31:50 -0800
Fixed extra lines.
Commits
-------
d974a4a Merge pull request #4 from stealth35/test_mo_loader
cf05646 delete useless tests
19f9de9 [Translation] fix gettext tests
965f2bf Merge pull request #3 from stealth35/test_mo_loader
9c2a26d [Translation] add Mo loader tests
9af2342 [Translation] Added the gettext loaders
Discussion
----------
[Translation] Added the gettext loaders
This is the squashed version of the work done by @xaav in #634.
@stealth35 you said you will work on the dumpers. do you have some stuff on it ?
---------------------------------------------------------------------------
by drak at 2011/10/24 19:28:43 -0700
Is there any more progress with this?
---------------------------------------------------------------------------
by stealth35 at 2011/10/25 00:57:19 -0700
I work on the dumpers, but the Po loader is wrong, caus' the Po ressource can be multiline,
msgid ""
"Here is an example of how one might continue a very long string\n"
"for the common case the string represents multi-line output.\n"
http://www.gnu.org/software/gettext/manual/gettext.html#PO-Files
Anyway the Po format is an intermediate format to Mo file, (like .txt to .res file for ICU), IMO we can just support the real gettext format : Mo
---------------------------------------------------------------------------
by stealth35 at 2011/11/03 02:00:24 -0700
@stof The MO Dumper is ready (stealth35/symfony@f2d1d5b4de), should we keep the PO format ?
---------------------------------------------------------------------------
by fabpot at 2011/11/07 08:50:59 -0800
@stealth35: The PO is what people will use for their translations. They will then dump it to MO. So, we need both PO and MO loaders and dumpers.
---------------------------------------------------------------------------
by stealth35 at 2011/11/08 01:25:39 -0800
@fabpot, I'm ready for both dumpers, you can merge this, and I'll open a PR for the dumpers
---------------------------------------------------------------------------
by fabpot at 2011/11/08 22:37:47 -0800
I've just had a look at this PR code again and I see that the unit tests are pretty slim. Is it possible to add some tests for the mo loader?
---------------------------------------------------------------------------
by stealth35 at 2011/11/09 01:15:25 -0800
@fabpot test send to @stof ✌️
---------------------------------------------------------------------------
by stof at 2011/11/09 02:22:55 -0800
and merged in this branch
---------------------------------------------------------------------------
by fabpot at 2011/11/09 02:39:09 -0800
The tests do not pass for me:
There was 1 error:
1) Symfony\Tests\Component\Translation\Loader\MoFileLoaderTest::testLoadDoesNothingIfEmpty
InvalidArgumentException: MO stream content has an invalid format.
/Users/fabien/work/symfony/git/symfony/src/Symfony/Component/Translation/Loader/MoFileLoader.php:79
/Users/fabien/work/symfony/git/symfony/src/Symfony/Component/Translation/Loader/MoFileLoader.php:46
/Users/fabien/work/symfony/git/symfony/tests/Symfony/Tests/Component/Translation/Loader/MoFileLoaderTest.php:34
--
There was 1 failure:
1) Symfony\Tests\Component\Translation\Loader\PoFileLoaderTest::testLoad
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
Array (
- 'foo' => 'bar'
)
/Users/fabien/work/symfony/git/symfony/tests/Symfony/Tests/Component/Translation/Loader/PoFileLoaderTest.php:25
If a request listener returns a response before calling the profiler
listener, the request will not be added in the stack leading to an error
during the handling of the kernel.response event. The profiler listener
should ideally be run first.
