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

Commit da83ca4

Browse files
xabbuhxabbuh
committed
Merge branch '2.7' into 2.8
* 2.7: (30 commits) [#7560] remove unused use statements Resolving $this usage outside a class on form.rst Fix some odd English in the PDOSessionHandler docs Fix typo Add the description for the HTTP status because it's not that common Update exception code status [#7592] some minor tweaks Fix link for Twig Extensions documentation Update framework.rst [Fix esi tag] Update render_without_controller.rst Update matchers.rst Update matchers.rst Update locale_sticky_session.rst Update framework.rst Update import.rst Update load_balancer_reverse_proxy.rst Moved the requirements file [#7509] add missing references Added a mention to APCu Polyfill in the performance article [#7497] minor rewording ...
2 parents 2d7ea6b + fb70182 commit da83ca4

28 files changed

+173
-93
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
@@ -153,7 +153,7 @@ of the most common elements of a bundle:
153153
Houses configuration, including routing configuration (e.g. ``routing.yml``).
154154

155155
``Resources/views/``
156-
Holds templates organized by controller name (e.g. ``Hello/index.html.twig``).
156+
Holds templates organized by controller name (e.g. ``Random/index.html.twig``).
157157

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

181181
bundles/*
182182

183-
_`third-party bundles`: http://knpbundles.com
183+
_`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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -142,5 +141,5 @@ what to do next. Have fun!
142141
.. _their documentation: https://getcomposer.org/doc/00-intro.md
143142
.. _Packagist.org: https://packagist.org
144143
.. _FOSUserBundle: https://github.com/FriendsOfSymfony/FOSUserBundle
145-
.. _KnpBundles.com: http://knpbundles.com/
146144
.. _`composer require`: https://getcomposer.org/doc/03-cli.md#require
145+
.. _`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
@@ -79,7 +79,7 @@ This allows you to use jQuery-like selectors to traverse::
7979

8080
$crawler = $crawler->filter('body > p');
8181

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

8484
use Symfony\Component\DomCrawler\Crawler;
8585
// ...

‎components/form.rst

Lines changed: 75 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -463,19 +463,29 @@ builder:
463463
464464
.. code-block:: php-symfony
465465
466+
// src/Acme/TaskBundle/Controller/DefaultController.php
467+
namespace Acme\TaskBundle\Controller;
468+
469+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
466470
use Symfony\Component\Form\Extension\Core\Type\TextType;
467471
use Symfony\Component\Form\Extension\Core\Type\DateType;
468472
469-
// ...
473+
class DefaultController extends Controller
474+
{
475+
public function newAction(Request $request)
476+
{
477+
$defaults = array(
478+
'dueDate' => new \DateTime('tomorrow'),
479+
);
470480
471-
$defaults = array(
472-
'dueDate' => new \DateTime('tomorrow'),
473-
);
481+
$form = $this->createFormBuilder($defaults)
482+
->add('task', TextType::class)
483+
->add('dueDate', DateType::class)
484+
->getForm();
474485

475-
$form = $this->createFormBuilder($defaults)
476-
->add('task', TextType::class)
477-
->add('dueDate', DateType::class)
478-
->getForm();
486+
// ...
487+
}
488+
}
479489

480490
.. tip::
481491

@@ -539,18 +549,23 @@ by ``handleRequest()`` to determine whether a form has been submitted):
539549
540550
.. code-block:: php-symfony
541551
542-
use Symfony\Component\Form\Extension\Core\Type\FormType;
552+
// src/Acme/TaskBundle/Controller/DefaultController.php
553+
namespace Acme\TaskBundle\Controller;
543554
544-
// ...
555+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
556+
use Symfony\Component\Form\Extension\Core\Type\FormType;
545557
546-
public function searchAction()
558+
class DefaultController extends Controller
547559
{
548-
$formBuilder = $this->createFormBuilder(null, array(
549-
'action' => '/search',
550-
'method' => 'GET',
551-
));
560+
public function searchAction()
561+
{
562+
$formBuilder = $this->createFormBuilder(null, array(
563+
'action' => '/search',
564+
'method' => 'GET',
565+
));
552566
553-
// ...
567+
// ...
568+
}
554569
}
555570
556571
.. _component-form-intro-handling-submission:
@@ -567,8 +582,8 @@ method:
567582
568583
use Symfony\Component\HttpFoundation\Request;
569584
use Symfony\Component\HttpFoundation\RedirectResponse;
570-
use Symfony\Component\Form\Extension\Core\Type\TextType;
571585
use Symfony\Component\Form\Extension\Core\Type\DateType;
586+
use Symfony\Component\Form\Extension\Core\Type\TextType;
572587
573588
// ...
574589
@@ -596,29 +611,34 @@ method:
596611
597612
.. code-block:: php-symfony
598613
599-
use Symfony\Component\Form\Extension\Core\Type\TextType;
600-
use Symfony\Component\Form\Extension\Core\Type\DateType;
614+
// src/Acme/TaskBundle/Controller/DefaultController.php
615+
namespace Acme\TaskBundle\Controller;
601616
602-
// ...
617+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
618+
use Symfony\Component\Form\Extension\Core\Type\DateType;
619+
use Symfony\Component\Form\Extension\Core\Type\TextType;
603620
604-
public function newAction(Request $request)
621+
class DefaultController extends Controller
605622
{
606-
$form = $this->createFormBuilder()
607-
->add('task', TextType::class)
608-
->add('dueDate', DateType::class)
609-
->getForm();
623+
public function newAction(Request $request)
624+
{
625+
$form = $this->createFormBuilder()
626+
->add('task', TextType::class)
627+
->add('dueDate', DateType::class)
628+
->getForm();
610629

611-
$form->handleRequest($request);
630+
$form->handleRequest($request);
612631

613-
if ($form->isSubmitted() && $form->isValid()) {
614-
$data = $form->getData();
632+
if ($form->isSubmitted() && $form->isValid()) {
633+
$data = $form->getData();
615634

616-
// ... perform some action, such as saving the data to the database
635+
// ... perform some action, such as saving the data to the database
617636

618-
return $this->redirectToRoute('task_success');
619-
}
637+
return $this->redirectToRoute('task_success');
638+
}
620639

621-
// ...
640+
// ...
641+
}
622642
}
623643

624644
This defines a common form "workflow", which contains 3 different possibilities:
@@ -667,22 +687,33 @@ option when building each field:
667687
668688
.. code-block:: php-symfony
669689
690+
// src/Acme/TaskBundle/Controller/DefaultController.php
691+
namespace Acme\TaskBundle\Controller;
692+
693+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
670694
use Symfony\Component\Validator\Constraints\NotBlank;
671695
use Symfony\Component\Validator\Constraints\Type;
672-
use Symfony\Component\Form\Extension\Core\Type\TextType;
673696
use Symfony\Component\Form\Extension\Core\Type\DateType;
697+
use Symfony\Component\Form\Extension\Core\Type\TextType;
674698
675-
$form = $this->createFormBuilder()
676-
->add('task', TextType::class, array(
677-
'constraints' => new NotBlank(),
678-
))
679-
->add('dueDate', DateType::class, array(
680-
'constraints' => array(
681-
new NotBlank(),
682-
new Type(\DateTime::class),
683-
)
684-
))
685-
->getForm();
699+
class DefaultController extends Controller
700+
{
701+
public function newAction(Request $request)
702+
{
703+
$form = $this->createFormBuilder()
704+
->add('task', TextType::class, array(
705+
'constraints' => new NotBlank(),
706+
))
707+
->add('dueDate', DateType::class, array(
708+
'constraints' => array(
709+
new NotBlank(),
710+
new Type(\DateTime::class),
711+
)
712+
))
713+
->getForm();
714+
// ...
715+
}
716+
}
686717

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

‎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

‎introduction/from_flat_php_to_symfony2.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -751,7 +751,7 @@ migrating the blog from flat PHP to Symfony has improved life:
751751

752752
And perhaps best of all, by using Symfony, you now have access to a whole
753753
set of **high-quality open source tools developed by the Symfony community**!
754-
A good selection of Symfony community tools can be found on `KnpBundles.com`_.
754+
A good selection of `Symfony community tools`_ can be found on GitHub.
755755

756756
.. _`Model-View-Controller`: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
757757
.. _`Doctrine`: http://www.doctrine-project.org
@@ -760,5 +760,5 @@ A good selection of Symfony community tools can be found on `KnpBundles.com`_.
760760
.. _`download Composer`: https://getcomposer.org/download/
761761
.. _`Validator`: https://github.com/symfony/validator
762762
.. _`Varnish`: https://www.varnish-cache.org/
763-
.. _`KnpBundles.com`: http://knpbundles.com/
764763
.. _`Twig`: http://twig.sensiolabs.org
764+
.. _`Symfony community tools`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

‎performance.rst

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,14 @@ There are a number of `byte code caches`_ available, some of which are open
2222
source. As of PHP 5.5, PHP comes with `OPcache`_ built-in. For older versions,
2323
the most widely used byte code cache is `APC`_.
2424

25-
Using a byte code cache really has no downside, and Symfony has been architected
25+
.. tip::
26+
27+
If your server still uses the legacy APC PHP extension, install the
28+
`APCu Polyfill component`_ in your application to enable compatibility with
29+
`APCu PHP functions`_ and unlock support for advanced Symfony features, such
30+
as the APCu Cache adapter.
31+
32+
Using a byte code cache really has no downside, and Symfony has been designed
2633
to perform really well in this type of environment.
2734

2835
Monitoring Source File Changes
@@ -202,5 +209,7 @@ Learn more
202209
.. _`OPcache`: http://php.net/manual/en/book.opcache.php
203210
.. _`opcache.max_accelerated_files`: http://php.net/manual/en/opcache.configuration.php#ini.opcache.max-accelerated-files
204211
.. _`APC`: http://php.net/manual/en/book.apc.php
212+
.. _`APCu Polyfill component`: https://github.com/symfony/polyfill-apcu
213+
.. _`APCu PHP functions`: http://php.net/manual/en/ref.apcu.php
205214
.. _`autoload.php`: https://github.com/symfony/symfony-standard/blob/master/app/autoload.php
206215
.. _`bootstrap file`: https://github.com/sensiolabs/SensioDistributionBundle/blob/master/Composer/ScriptHandler.php

0 commit comments

Comments
 (0)
0