8000 Merge branch '3.2' · symfony/symfony-docs@17c05f6 · GitHub
[go: up one dir, main page]
Skip to content

Commit 17c05f6

Browse files
wouterjwouterj
committed
Merge branch '3.2'
2 parents b8da0dd + de04468 commit 17c05f6

33 files changed

+220
-95
lines changed

‎.platform.app.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,5 +56,5 @@ hooks:
5656
# Platform.sh currently sets PIP_USER=1.
5757
export PIP_USER=
5858
pip install pip==9.0.1 wheel==0.29.0
59-
pip install -r requirements.txt
59+
pip install -r _build/.requirements.txt
6060
make -C _build html

‎requirements.txt renamed to ‎_build/.requirements.txt

File renamed without changes.

‎_build/make.bat

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ REM Command file for Sphinx documentation
55
if "%SPHINXBUILD%" == "" (
66
set SPHINXBUILD=sphinx-build
77
)
8-
set BUILDDIR=_build
9-
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
8+
set BUILDDIR=.
9+
set ALLSPHINXOPTS=-c %BUILDDIR% -d %BUILDDIR%/doctrees %SPHINXOPTS% ..
1010
set I18NSPHINXOPTS=%SPHINXOPTS% .
1111
if NOT "%PAPER%" == "" (
1212
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%

‎assetic/jpeg_optimize.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -308,4 +308,4 @@ file:
308308
`LiipImagineBundle`_ community bundle.
309309

310310
.. _`Jpegoptim`: http://www.kokkonen.net/tjko/projects.html
311-
.. _`LiipImagineBundle`: http://knpbundles.com/liip/LiipImagineBundle
311+
.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle

‎best_practices/configuration.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,31 @@ whereas they cannot access the container parameters:
153153
The only notable disadvantage of using constants for this kind of configuration
154154
values is that you cannot redefine them easily in your tests.
155155

156+
Parameter Naming
157+
----------------
158+
159+
.. best-practice::
160+
161+
The name of your configuration parameters should be as short as possible and
162+
should include a common prefix for the entire application.
163+
164+
Using ``app.`` as the prefix of your parameters is a common practice to avoid
165+
collisions with Symfony and third-party bundles/libraries parameters. Then, use
166+
just one or two words to describe the purpose of the parameter:
167+
168+
.. code-block:: yaml
169+
170+
# app/config/config.yml
171+
parameters:
172+
# don't do this: 'dir' is too generic and it doesn't convey any meaning
173+
app.dir: '...'
174+
# do this: short but easy to understand names
175+
app.contents_dir: '...'
176+
# it's OK to use dots, underscores, dashes or nothing, but always
177+
# be consistent and use the same format for all the parameters
178+
app.dir.contents: '...'
179+
app.contents-dir: '...'
180+
156181
Semantic Configuration: Don't Do It
157182
-----------------------------------
158183

‎bundles.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@ of the most common elements of a bundle:
154154
Houses configuration, including routing configuration (e.g. ``routing.yml``).
155155

156156
``Resources/views/``
157-
Holds templates organized by controller name (e.g. ``Hello/index.html.twig``).
157+
Holds templates organized by controller name (e.g. ``Random/index.html.twig``).
158158

159159
``Resources/public/``
160160
Contains web assets (images, stylesheets, etc) and is copied or symbolically
@@ -181,4 +181,4 @@ Learn more
181181

182182
bundles/*
183183

184-
_`third-party bundles`: http://knpbundles.com
184+
_`third-party bundles`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

‎bundles/installation.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,7 @@ the bundle on the `Packagist.org`_ site.
2626

2727
.. tip::
2828

29-
Looking for bundles? Try searching at `KnpBundles.com`_: the unofficial
30-
archive of Symfony Bundles.
29+
Looking for bundles? Try searching for `symfony-bundle topic on GitHub`_.
3130

3231
2) Install the Bundle via Composer
3332
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -157,5 +156,5 @@ what to do next. Have fun!
157156
.. _their documentation: https://getcomposer.org/doc/00-intro.md
158157
.. _Packagist.org: https://packagist.org
159158
.. _FOSUserBundle: https://github.com/FriendsOfSymfony/FOSUserBundle
160-
.. _KnpBundles.com: http://knpbundles.com/
161159
.. _`composer require`: https://getcomposer.org/doc/03-cli.md#require
160+
.. _`symfony-bundle topic on GitHub`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

‎components/dependency_injection/workflow.rst

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,10 @@
44
Container Building Workflow
55
===========================
66

7-
In the preceding pages of this section, there has been little to say about
8-
where the various files and classes should be located. This is because this
9-
depends on the application, library or framework in which you want to use
10-
the container. Looking at how the container is configured and built in the
11-
Symfony full-stack Framework will help you see how this all fits together,
7+
The location of the files and classes related to the Dependency Injection
8+
component depends on the application, library or framework in which you want
9+
to use the container. Looking at how the container is configured and built
10+
in the Symfony full-stack Framework will help you see how this all fits together,
1211
whether you are using the full-stack framework or looking to use the service
1312
container in another application.
1413

‎components/dom_crawler.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ This allows you to use jQuery-like selectors to traverse::
8181

8282
$crawler = $crawler->filter('body > p');
8383

84-
Anonymous function can be used to filter with more complex criteria::
84+
An anonymous function can be used to filter with more complex criteria::
8585

8686
use Symfony\Component\DomCrawler\Crawler;
8787
// ...

‎components/form.rst

Lines changed: 75 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -460,19 +460,29 @@ builder:
460460
461461
.. code-block:: php-symfony
462462
463+
// src/Acme/TaskBundle/Controller/DefaultController.php
464+
namespace Acme\TaskBundle\Controller;
465+
466+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
463467
use Symfony\Component\Form\Extension\Core\Type\TextType;
464468
use Symfony\Component\Form\Extension\Core\Type\DateType;
465469
466-
// ...
470+
class DefaultController extends Controller
471+
{
472+
public function newAction(Request $request)
473+
{
474+
$defaults = array(
475+
'dueDate' => new \DateTime('tomorrow'),
476+
);
467477
468-
$defaults = array(
469-
'dueDate' => new \DateTime('tomorrow'),
470-
);
478+
$form = $this->createFormBuilder($defaults)
479+
->add('task', TextType::class)
480+
->add('dueDate', DateType::class)
481+
->getForm();
471482

472-
$form = $this->createFormBuilder($defaults)
473-
->add('task', TextType::class)
474-
->add('dueDate', DateType::class)
475-
->getForm();
483+
// ...
484+
}
485+
}
476486

477487
.. tip::
478488

@@ -532,18 +542,23 @@ by ``handleRequest()`` to determine whether a form has been submitted):
532542
533543
.. code-block:: php-symfony
534544
535-
use Symfony\Component\Form\Extension\Core\Type\FormType;
545+
// src/Acme/TaskBundle/Controller/DefaultController.php
546+
namespace Acme\TaskBundle\Controller;
536547
537-
// ...
548+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
549+
use Symfony\Component\Form\Extension\Core\Type\FormType;
538550
539-
public function searchAction()
551+
class DefaultController extends Controller
540552
{
541-
$formBuilder = $this->createFormBuilder(null, array(
542-
'action' => '/search',
543-
'method' => 'GET',
544-
));
553+
public function searchAction()
554+
{
555+
$formBuilder = $this->createFormBuilder(null, array(
556+
'action' => '/search',
557+
'method' => 'GET',
558+
));
545559
546-
// ...
560+
// ...
561+
}
547562
}
548563
549564
.. _component-form-intro-handling-submission:
@@ -560,8 +575,8 @@ method:
560575
561576
use Symfony\Component\HttpFoundation\Request;
562577
use Symfony\Component\HttpFoundation\RedirectResponse;
563-
use Symfony\Component\Form\Extension\Core\Type\TextType;
564578
use Symfony\Component\Form\Extension\Core\Type\DateType;
579+
use Symfony\Component\Form\Extension\Core\Type\TextType;
565580
566581
// ...
567582
@@ -589,29 +604,34 @@ method:
589604
590605
.. code-block:: php-symfony
591606
592-
use Symfony\Component\Form\Extension\Core\Type\TextType;
593-
use Symfony\Component\Form\Extension\Core\Type\DateType;
607+
// src/Acme/TaskBundle/Controller/DefaultController.php
608+
namespace Acme\TaskBundle\Controller;
594609
595-
// ...
610+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
611+
use Symfony\Component\Form\Extension\Core\Type\DateType;
612+
use Symfony\Component\Form\Extension\Core\Type\TextType;
596613
597-
public function newAction(Request $request)
614+
class DefaultController extends Controller
598615
{
599-
$form = $this->createFormBuilder()
600-
->add('task', TextType::class)
601-
->add('dueDate', DateType::class)
602-
->getForm();
616+
public function newAction(Request $request)
617+
{
618+
$form = $this->createFormBuilder()
619+
->add('task', TextType::class)
620+
->add('dueDate', DateType::class)
621+
->getForm();
603622

604-
$form->handleRequest($request);
623+
$form->handleRequest($request);
605624

606-
if ($form->isSubmitted() && $form->isValid()) {
607-
$data = $form->getData();
625+
if ($form->isSubmitted() && $form->isValid()) {
626+
$data = $form->getData();
608627

609-
// ... perform some action, such as saving the data to the database
628+
// ... perform some action, such as saving the data to the database
610629

611-
return $this->redirectToRoute('task_success');
612-
}
630+
return $this->redirectToRoute('task_success');
631+
}
613632

614-
// ...
633+
// ...
634+
}
615635
}
616636

617637
This defines a common form "workflow", which contains 3 different possibilities:
@@ -660,22 +680,33 @@ option when building each field:
660680
661681
.. code-block:: php-symfony
662682
683+
// src/Acme/TaskBundle/Controller/DefaultController.php
684+
namespace Acme\TaskBundle\Controller;
685+
686+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
663687
use Symfony\Component\Validator\Constraints\NotBlank;
664688
use Symfony\Component\Validator\Constraints\Type;
665-
use Symfony\Component\Form\Extension\Core\Type\TextType;
666689
use Symfony\Component\Form\Extension\Core\Type\DateType;
690+
use Symfony\Component\Form\Extension\Core\Type\TextType;
667691
668-
$form = $this->createFormBuilder()
669-
->add('task', TextType::class, array(
670-
'constraints' => new NotBlank(),
671-
))
672-
->add('dueDate', DateType::class, array(
673-
'constraints' => array(
674-
new NotBlank(),
675-
new Type(\DateTime::class),
676-
)
677-
))
678-
->getForm();
692+
class DefaultController extends Controller
693+
{
694+ 4E34
public function newAction(Request $request)
695+
{
696+
$form = $this->createFormBuilder()
697+
->add('task', TextType::class, array(
698+
'constraints' => new NotBlank(),
699+
))
700+
->add('dueDate', DateType::class, array(
701+
'constraints' => array(
702+
new NotBlank(),
703+
new Type(\DateTime::class),
704+
)
705+
))
706+
->getForm();
707+
// ...
708+
}
709+
}
679710

680711
When the form is bound, these validation constraints will be applied automatically
681712
and the errors will display next to the fields on error.

‎components/http_foundation.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,7 @@ represents an HTTP message. But when moving from a legacy system, adding
285285
methods or changing some default behavior might help. In that case, register a
286286
PHP callable that is able to create an instance of your ``Request`` class::
287287

288+
use AppBundle\Http\SpecialRequest;
288289
use Symfony\Component\HttpFoundation\Request;
289290

290291
Request::setFactory(function (

‎components/process.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,26 @@ are done doing other stuff::
143143
which means that your code will halt at this line until the external
144144
process is completed.
145145

146+
.. note::
147+
148+
If a ``Response`` is sent **before** a child process had a chance to complete,
149+
the server process will be killed (depending on your OS). It means that
150+
your task will be stopped right away. Running an asynchronous process
151+
is not the same as running a process that survives its parent process.
152+
153+
If you want your process to survive the request/response cycle, you can
154+
take advantage of the ``kernel.terminate`` event, and run your command
155+
**synchronously** inside this event. Be aware that ``kernel.terminate``
156+
is called only if you use PHP-FPM.
157+
158+
.. caution::
159+
160+
Beware also that if you do that, the said PHP-FPM process will not be
161+
available to serve any new request until the subprocess is finished. This
162+
means you can quickly block your FPM pool if you're not careful enough.
163+
That is why it's generally way better not to do any fancy things even
164+
after the request is sent, but to use a job queue instead.
165+
146166
:method:`Symfony\\Component\\Process\\Process::wait` takes one optional argument:
147167
a callback that is called repeatedly whilst the process is still running, passing
148168
in the output and its type::

‎configuration/micro_kernel_trait.rst

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -280,7 +280,20 @@ has one file in it::
280280

281281
Template files should live in the ``Resources/views`` directory of whatever directory
282282
your *kernel* lives in. Since ``AppKernel`` lives in ``app/``, this template lives
283-
at ``app/Resources/views/micro/random.html.twig``.
283+
at ``app/Resources/views/micro/random.html.twig``:
284+
285+
.. code-block:: html+twig
286+
287+
<!-- app/Resources/views/micro/random.html.twig -->
288+
<!DOCTYPE html>
289+
<html>
290+
<head>
291+
<title>Random action</title>
292+
</head>
293+
<body>
294+
<p>{{ number }}</p>
295+
</body>
296+
</html>
284297

285298
Finally, you need a front controller to boot and run the application. Create a
286299
``web/index.php``::
@@ -309,7 +322,6 @@ this:
309322
│ ├─ config/
310323
│ └─ Resources
311324
| └─ views
312-
| ├─ base.html.twig
313325
| └─ micro
314326
| └─ random.html.twig
315327
├─ src/

‎console.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,7 @@ console::
237237
// pass arguments to the helper
238238
'username' => 'Wouter',
239239

240-
// prefix the key with a double slash when passing options,
240+
// prefix the key with two dashes when passing options,
241241
// e.g: '--some-option' => 'option_value',
242242
));
243243

‎contributing/community/other.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,4 @@ these additional resources:
1212
.. _pull requests: https://github.com/symfony/symfony/pulls
1313
.. _commits: https://github.com/symfony/symfony/commits/master
1414
.. _bugs and enhancements: https://github.com/symfony/symfony/issues
15-
.. _bundles: http://knpbundles.com/
15+
.. _bundles: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

‎contributing/documentation/overview.rst

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -279,13 +279,9 @@ purposes following these steps:
279279

280280
.. code-block:: terminal
281281
282-
# Linux and macOS
283282
$ cd _build/
284283
$ make html
285284
286-
# Windows
287-
$ _build\make html
288-
289285
The generated documentation is available in the ``_build/html`` directory.
290286

291287
Frequently Asked Questions

‎deployment.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ other potential things like pushing assets to a CDN (see `Common Post-Deployment
203203
.. _`Fabric`: http://www.fabfile.org/
204204
.. _`Magallanes`: https://github.com/andres-montanez/Magallanes
205205
.. _`Ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant
206-
.. _`bundles that add deployment features`: http://knpbundles.com/search?q=deploy
206+
.. _`bundles that add deployment features`: https://github.com/search?utf8=✓&q=topic%3Asymfony-bundle+topic%3Adeploy&type=Repositories&ref=searchresults
207207
.. _`Memcached`: http://memcached.org/
208208
.. _`Redis`: http://redis.io/
209209
.. _`Symfony plugin`: https://github.com/capistrano/symfony/

‎doctrine/pdo_session_storage.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,6 @@ Microsoft SQL Server
245245
If the application stores large amounts of session data, this problem can
246246
be solved by increasing the column size (use ``BLOB`` or even ``MEDIUMBLOB``).
247247
When using MySQL as the database engine, you can also enable the `strict SQL mode`_
248-
to get noticed when such an error happens.
248+
to be notified when such an error happens.
249249

250250
.. _`strict SQL mode`: https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html

0 commit comments

Comments
 (0)
0