8000 Merge branch '2.7' into 2.8 · symfony/symfony-docs@82f28b4 · GitHub
[go: up one dir, main page]
Skip to content

Commit 82f28b4

Browse files
xabbuhxabbuh
committed
Merge branch '2.7' into 2.8
* 2.7: [#7939] revert some changes (revert them for 3.2) Minor reword Update twig_reference.rst [#7958] fix minor typo improve examples of how we create test doubles Minor reword Add default indication in input arguments/options description Improved the explanation about deployment + parameters.yml Explained how to run tests in multiple kernel apps Fixed the explanation about PHPUnit event listeners in PHPUnitBridge File example update [#8003] add XML and PHP config examples Reworded the help note adding note that CSRF protection has to be enabled in config follow best practices for template files Added a note about disabling FastCGI buffering in Nginx Add some doc on missing options of framework bundle configuration Reworded the explanation about the --router option
2 parents 0b78495 + 9c02ada commit 82f28b4

File tree

17 files changed

+198
-68
lines changed

17 files changed

+198
-68
lines changed

‎components/http_foundation.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -464,8 +464,12 @@ represented by a PHP callable instead of a string::
464464
you must call ``ob_flush()`` before ``flush()``.
465465

466466
Additionally, PHP isn't the only layer that can buffer output. Your web
467-
server might also buffer based on its configuration. What's more, if you
468-
use FastCGI, buffering can't be disabled at all.
467+
server might also buffer based on its configuration. Some servers, such as
468+
Nginx, let you disable buffering at config level or adding a special HTTP
469+
header in the response::
470+
471+
// disables FastCGI buffering in Nginx only for this response
472+
$response->headers->set('X-Accel-Buffering', 'no')
469473

470474
.. _component-http-foundation-serving-files:
471475

‎components/phpunit_bridge.rst

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,16 @@ You can install the component in 2 different ways:
3939
Usage
4040
-----
4141

42-
Once the component is installed, it automatically registers a
43-
`PHPUnit event listener`_ which in turn registers a `PHP error handler`_
44-
called :class:`Symfony\\Bridge\\PhpUnit\\DeprecationErrorHandler`. After
45-
running your PHPUnit tests, you will get a report similar to this one:
42+
Once the component is installed, a ``simple-phpunit`` script is created in the
43+
``vendor/`` directory to run tests. This script wraps the original PHPUnit binary
44+
to provide more features:
45+
46+
.. code-block:: terminal
47+
48+
$ cd my-project/
49+
$ ./vendor/bin/simple-phpunit
50+
51+
After running your PHPUnit tests, you will get a report similar to this one:
4652

4753
.. image:: /_images/components/phpunit_bridge/report.png
4854

@@ -59,6 +65,21 @@ The summary includes:
5965
Deprecation notices are all other (non-legacy) notices, grouped by message,
6066
test class and method.
6167

68+
.. note::
69+
70+
If you don't want to use the ``simple-phpunit`` script, register the following
71+
`PHPUnit event listener`_ in your PHPUnit configuration file to get the same
72+
report about deprecations (which is created by a `PHP error handler`_
73+
called :class:`Symfony\\Bridge\\PhpUnit\\DeprecationErrorHandler`):
74+
75+
.. code-block:: xml
76+
77+
<!-- phpunit.xml.dist -->
78+
<!-- ... -->
79+
<listeners>
80+
<listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
81+
</listeners>
82+
6283
Trigger Deprecation Notices
6384
---------------------------
6485

‎configuration/multiple_kernels.rst

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,43 @@ In order to solve this issue, add the following configuration to your kernel:
178178
# allows to use app/Resources/views/ templates in the ApiKernel
179179
"%kernel.root_dir%/../app/Resources/views": ~
180180
181+
Running Tests Using a Different Kernel
182+
--------------------------------------
183+
184+
In Symfony applications, functional tests extend by default from the
185+
:class:`Symfony\\Bundle\\FrameworkBundle\\Test\\WebTestCase` class. Inside that
186+
class, a method called ``getKernelClass()`` tries to find the class of the kernel
187+
to use to run the application during tests. The logic of this method does not
188+
support multiple kernel applications, so your tests won't use the right kernel.
189+
190+
The solution is to create a custom base class for functional tests extending
191+
from ``WebTestCase`` class and overriding the ``getKernelClass()`` method to
192+
return the fully qualified class name of the kernel to use::
193+
194+
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
195+
196+
// tests needing the ApiKernel to work, now must extend this
197+
// ApiTestCase class instead of the default WebTestCase class
198+
class ApiTestCase extends WebTestCase
199+
{
200+
protected static function getKernelClass()
201+
{
202+
return 'ApiKernel';
203+
}
204+
205+
// this is needed because the KernelTestCase class keeps a reference to
206+
// the previously created kernel in its static $kernel property. Thus,
207+
// if your functional tests do not run in isolated processes, a later run
208+
// test for a different kernel will reuse the previously created instance,
209+
// which points to a different kernel
210+
protected function tearDown()
211+
{
212+
parent::tearDown();
213+
214+
static::$class = null;
215+
}
216+
}
217+
181218
Adding more Kernels to the Application
182219
--------------------------------------
183220

‎console/input.rst

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -91,11 +91,12 @@ There are three argument variants you can use:
9191
provided;
9292

9393
``InputArgument::OPTIONAL``
94-
The argument is optional and therefore can be omitted;
94+
The argument is optional and therefore can be omitted. This is the default
95+
behavior of arguments;
9596

9697
``InputArgument::IS_ARRAY``
9798
The argument can contain any number of values. For that reason, it must be
98-
used at the end of the argument list
99+
used at the end of the argument list.
99100

100101
You can combine ``IS_ARRAY`` with ``REQUIRED`` and ``OPTIONAL`` like this::
101102

@@ -177,11 +178,15 @@ There are four option variants you can use:
177178

178179
``InputOption::VALUE_IS_ARRAY``
179180
This option accepts multiple values (e.g. ``--dir=/foo --dir=/bar``);
181+
180182
``InputOption::VALUE_NONE``
181-
Do not accept input for this option (e.g. ``--yell``);
183+
Do not accept input for this option (e.g. ``--yell``). This is the default
184+
behavior of options;
185+
182186
``InputOption::VALUE_REQUIRED``
183187
This value is required (e.g. ``--iterations=5``), the option itself is
184188
still optional;
189+
185190
``InputOption::VALUE_OPTIONAL``
186191
This option may or may not have a value (e.g. ``--yell`` or
187192
``--yell=loud``).

‎controller/service.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ Symfony's base controller::
174174
public function indexAction($name)
175175
{
176176
return $this->render(
177-
'@App/Hello/index.html.twig',
177+
'hello/index.html.twig',
178178
array('name' => $name)
179179
);
180180
}
@@ -210,7 +210,7 @@ service and use it directly::
210210
public function indexAction($name)
211211
{
212212
return $this->templating->renderResponse(
213-
'@App/Hello/index.html.twig',
213+
'hello/index.html.twig',
214214
array('name' => $name)
215215
);
216216
}

‎deployment.rst

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -120,11 +120,20 @@ Check if your server meets the requirements by running:
120120
121121
$ php app/check.php
122122
123-
B) Configure your ``app/config/parameters.yml`` File
124-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123+
.. _b-configure-your-app-config-parameters-yml-file:
125124

126-
This file should *not* be deployed, but managed through the automatic utilities
127-
provided by Symfony.
125+
B) Configure your Parameters File
126+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127+
128+
Most Symfony applications define configuration parameters in a file called
129+
``app/config/parameters.yml``. This file should *not* be deployed, because
130+
Symfony generates it automatically using the ``app/config/parameters.yml.dist``
131+
file as a template (that's why ``parameters.yml.dist`` must be committed and
132+
deployed).
133+
134+
If your application uses environment variables instead of these parameters, you
135+
must define those env vars in your production server using the tools provided by
136+
your hosting service.
128137

129138
C) Install/Update your Vendors
130139
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎form/direct_submit.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ submissions::
2828
return $this->redirectToRoute('task_success');
2929
}
3030

31-
return $this->render('@App/Default/new.html.twig', array(
31+
return $this->render('default/new.html.twig', array(
3232
'form' => $form->createView(),
3333
));
3434
}
@@ -67,7 +67,7 @@ method, pass the submitted data directly to
6767
}
6868
}
6969

70-
return $this->render('@App/Default/new.html.twig', array(
70+
return $this->render('default/new.html.twig', array(
7171
'form' => $form->createView(),
7272
));
7373
}
@@ -126,7 +126,7 @@ a convenient shortcut to the previous example::
126126
}
127127
}
128128

129-
return $this->render('@App/Default/new.html.twig', array(
129+
return $this->render('default/new.html.twig', array(
130130
'form' => $form->createView(),
131131
));
132132
}

‎form/dynamic_form_modification.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -569,7 +569,7 @@ your application. Assume that you have a sport meetup creation controller::
569569
}
570570

571571
return $this->render(
572-
'@App/Meetup/create.html.twig',
572+
'meetup/create.html.twig',
573573
array('form' => $form->createView())
574574
);
575575
}
@@ -584,7 +584,7 @@ field according to the current selection in the ``sport`` field:
584584

585585
.. code-block:: html+twig
586586

587-
{# app/Resources/views/Meetup/create.html.twig #}
587+
{# app/Resources/views/meetup/create.html.twig #}
588588
{{ form_start(form) }}
589589
{{ form_row(form.sport) }} {# <select id="meetup_sport" ... #}
590590
{{ form_row(form.position) }} {# <select id="meetup_position" ... #}

‎form/form_collections.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ In your controller, you'll create a new form from the ``TaskType``::
177177
// ... maybe do some form processing, like saving the Task and Tag objects
178178
}
179179 10000

180-
return $this->render('@App/Task/new.html.twig', array(
180+
return $this->render('task/new.html.twig', array(
181181
'form' => $form->createView(),
182182
));
183183
}
@@ -193,7 +193,7 @@ zero tags when first created).
193193

194194
.. code-block:: html+twig
195195

196-
{# src/AppBundle/Resources/views/Task/new.html.twig #}
196+
{# app/Resources/views/task/new.html.twig #}
197197

198198
{# ... #}
199199

‎profiler/data_collector.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,7 @@ block and set the value of two variables called ``icon`` and ``text``:
197197

198198
.. code-block:: twig
199199
200-
{{ include('@App/data_collector/icon.svg') }}
200+
{{ include('data_collector/icon.svg') }}
201201
202202
You are encouraged to use the latter technique for your own toolbar panels.
203203

‎reference/configuration/framework.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,9 @@ Configuration
6868
* `gc_divisor`_
6969
* `gc_probability`_
7070
* `gc_maxlifetime`_
71+
* `use_strict_mode`_
7172
* `save_path`_
73+
* `metadata_update_threshold`_
7274
* `assets`_
7375
* `base_path`_
7476
* `base_urls`_
@@ -826,6 +828,17 @@ This determines the number of seconds after which data will be seen as "garbage"
826828
and potentially cleaned up. Garbage collection may occur during session
827829
start and depends on `gc_divisor`_ and `gc_probability`_.
828830

831+
use_strict_mode
832+
...............
833+
834+
**type**: ``boolean`` **default**: ``false``
835+
836+
This specifies whether the session module will use the strict session id mode.
837+
If this mode is enabled, the module does not accept uninitialized session IDs.
838+
If an uninitialized session ID is sent from browser, a new session ID is sent
839+
to browser. Applications are protected from session fixation via session
840+
adoption with strict mode.
841+
829842
save_path
830843
.........
831844

@@ -872,6 +885,19 @@ setting the value to ``null``:
872885
),
873886
));
874887
888+
metadata_update_threshold
889+
.........................
890+
891+
**type**: ``integer`` **default**: ``0``
892+
893+
This is how many seconds to wait between two session metadata updates. It will
894+
also prevent the session handler to write if the session has not changed.
895+
896+
.. seealso::
897+
898+
You can see an example of the usage of this in
899+
:doc:`/session/limit_metadata_writes`.
900+
875901
assets
876902
~~~~~~
877903

‎reference/configuration/twig.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ TwigBundle Configuration ("twig")
2525
- foundation_5_layout.html.twig
2626
2727
# Example:
28-
- @App/form.html.twig
28+
- form.html.twig
2929
3030
globals:
3131
@@ -78,7 +78,7 @@ TwigBundle Configuration ("twig")
7878
optimizations="true"
7979
>
8080
<twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
81-
<twig:form-theme>@App/form.html.twig</twig:form-theme>
81+
<twig:form-theme>form.html.twig</twig:form-theme>
8282
8383
<twig:global key="foo" id="bar" type="service" />
8484
<twig:global key="pi">3.14</twig:global>
@@ -94,7 +94,7 @@ TwigBundle Configuration ("twig")
9494
$container->loadFromExtension('twig', array(
9595
'form_themes' => array(
9696
'form_div_layout.html.twig', // Default
97-
'@App/form.html.twig',
97+
'form.html.twig',
9898
),
9999
'globals' => array(
100100
'foo' => '@bar',

‎reference/forms/types/file.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ be used to move the ``attachment`` file to a permanent location::
5353
if ($form->isSubmitted() && $form->isValid()) {
5454
$someNewFilename = ...
5555

56-
$form['attachment']->getData()->move($dir, $someNewFilename);
56+
$file = $form['attachment']->getData();
57+
$file->move($dir, $someNewFilename);
5758

5859
// ...
5960
}

‎reference/twig_reference.rst

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -595,14 +595,14 @@ file_excerpt
595595

596596
.. code-block:: twig
597597
598-
{{ file|file_excerpt(line = null) }}
598+
{{ file|file_excerpt(line) }}
599599
600600
``file``
601601
**type**: ``string``
602-
``line`` *(optional)*
602+
``line``
603603
**type**: ``integer``
604604

605-
Generates an excerpt of seven lines around the given ``line``.
605+
Generates an excerpt of a code file around the given ``line`` number.
606606

607607
format_file
608608
~~~~~~~~~~~
@@ -639,12 +639,14 @@ file_link
639639

640640
.. code-block:: twig
641641
642-
{{ file|file_link(line = null) }}
642+
{{ file|file_link(line) }}
643643
644-
``line`` *(optional)*
644+
``file``
645+
**type**: ``string``
646+
``line``
645647
**type**: ``integer``
646648

647-
Generates a link to the provided file (and optionally line number) using
649+
Generates a link to the provided file and line number using
648650
a preconfigured scheme.
649651

650652
.. _reference-twig-tags:

0 commit comments

Comments
 (0)
0