diff --git a/.vale.ini b/.vale.ini index 46d403e62c3..df52085c52c 100644 --- a/.vale.ini +++ b/.vale.ini @@ -4,6 +4,11 @@ Packages = Microsoft, write-good Vocab = Symfony [*] -BasedOnStyles = Vale, Microsoft, write-good -BlockIgnores = (?s) *(\.\. configuration-block::) +BasedOnStyles = Vale, Microsoft, write-good, Symfony +BlockIgnores = (?s) *(\.\. (configuration-block|code-block)::[^\n]+(\n\s[^\n]+)+) TokenIgnores = (:ref:`.*`) + +Microsoft.Headings = NO +Microsoft.Foreign = NO +Microsoft.Quotes = NO +Microsoft.Contractions = NO diff --git a/.vale/Symfony/Headings.yml b/.vale/Symfony/Headings.yml new file mode 100644 index 00000000000..71ede8f059e --- /dev/null +++ b/.vale/Symfony/Headings.yml @@ -0,0 +1,6 @@ +extends: capitalization +message: "'%s' should be in title case" +level: warning +scope: heading +match: $title +style: Chicago diff --git a/.vale/config/vocabularies/Symfony/accept.txt b/.vale/config/vocabularies/Symfony/accept.txt index 6f6387578d5..7179147bd31 100644 --- a/.vale/config/vocabularies/Symfony/accept.txt +++ b/.vale/config/vocabularies/Symfony/accept.txt @@ -1,7 +1,32 @@ Symfony -namespace -autowiring -autowired -boolean -stderr -config +Ctype +iconv +Tokenizer +Monolog +nginx +Laravel +ezPublish +PHPUnit +Xdebug +webpack +(?i)autocompletes +(?i)autoload(ing|ed) +(?i)autoloader +(?i)autowir(ing|ed) +(?i)autowire +(?i)auto-(installing|escaping) +(?i)boolean +(?i)charset +(?i)config +(?i)env +(?i)hardcode(d|s) +(?i)hasser +(?i)inlined +(?i)isser +(?i)namespace +(?i)profiler +(?i)reusability +(?i)stderr +(?i)uncomment +(?i)unvalidated +(?i)validator diff --git a/configuration.rst b/configuration.rst index 56bc30fcf4c..36ec78a36a8 100644 --- a/configuration.rst +++ b/configuration.rst @@ -895,9 +895,9 @@ override environment variables defined in ``.env`` files. Configuring Environment Variables in Production ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In production, the ``.env`` files are also parsed and loaded on each request. So -the easiest way to define env vars is by creating a ``.env.local`` file on your -production server(s) with your production values. +In production, the ``.env`` files are also parsed and loaded on each request. +The easiest way to define env vars is by creating a ``.env.local`` file on your +production servers with your production values. To improve performance, you can optionally run the ``dump-env`` Composer command: diff --git a/controller.rst b/controller.rst index 7866a97818b..8aa25500e5c 100644 --- a/controller.rst +++ b/controller.rst @@ -104,7 +104,7 @@ Generating URLs ~~~~~~~~~~~~~~~ The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController::generateUrl` -method is just a helper method that generates the URL for a given route:: +method is just a helper method that generates the URL of a given route:: $url = $this->generateUrl('app_lucky_number', ['max' => 10]); @@ -458,7 +458,7 @@ In Symfony, a controller is required to return a ``Response`` object:: $response->headers->set('Content-Type', 'text/css'); To facilitate this, different response objects are included to address different -response types. Some of these are mentioned below. To learn more about the +response types. Some of these are mentioned below. To learn more about the ``Request`` and ``Response`` (and different ``Response`` classes), see the :ref:`HttpFoundation component documentation `. diff --git a/create_framework/dependency_injection.rst b/create_framework/dependency_injection.rst index de3c4e11e4e..6a1d67bbf46 100644 --- a/create_framework/dependency_injection.rst +++ b/create_framework/dependency_injection.rst @@ -65,7 +65,7 @@ reporting turned on and errors displayed in the browser to ease debugging:: environment. Having two different front controllers gives you the opportunity to have a slightly different configuration for each of them. -So, moving code from the front controller to the framework class makes our +Moving code from the front controller to the framework class makes our framework more configurable, but at the same time, it introduces a lot of issues: diff --git a/create_framework/http_foundation.rst b/create_framework/http_foundation.rst index dd838e9a5e2..9a9385e2ac3 100644 --- a/create_framework/http_foundation.rst +++ b/create_framework/http_foundation.rst @@ -22,7 +22,7 @@ it suffers from a few problems:: printf('Hello %s', $name); First, if the ``name`` query parameter is not defined in the URL query string, -you will get a PHP warning; so let's fix it:: +you will get a PHP warning; let's fix it:: // framework/index.php $name = $_GET['name'] ?? 'World'; @@ -93,8 +93,8 @@ reading this book now and go back to whatever code you were working on before. Going OOP with the HttpFoundation Component ------------------------------------------- -Writing web code is about interacting with HTTP. So, the fundamental -principles of our framework should be around the `HTTP specification`_. +Writing web code is about interacting with HTTP. The fundamental principles +of our framework should be around the `HTTP specification`_. The HTTP specification describes how a client (a browser for instance) interacts with a server (our application via a web server). The dialog between @@ -261,7 +261,7 @@ explicitly trust your reverse proxies by calling ``setTrustedProxies()``:: // the client is a known one, so give it some more privilege } -So, the ``getClientIp()`` method works securely in all circumstances. You can +The ``getClientIp()`` method works securely in all circumstances. You can use it in all your projects, whatever the configuration is, it will behave correctly and safely. That's one of the goals of using a framework. If you were to write a framework from scratch, you would have to think about all these diff --git a/create_framework/http_kernel_controller_resolver.rst b/create_framework/http_kernel_controller_resolver.rst index 12d9efead6e..9cbd2ebe5ff 100644 --- a/create_framework/http_kernel_controller_resolver.rst +++ b/create_framework/http_kernel_controller_resolver.rst @@ -1,4 +1,4 @@ -The HttpKernel Component: the Controller Resolver +The HttpKernel Component: The Controller Resolver ================================================= You might think that our framework is already pretty solid and you are diff --git a/create_framework/routing.rst b/create_framework/routing.rst index f76167ec2fb..1aabc8f5433 100644 --- a/create_framework/routing.rst +++ b/create_framework/routing.rst @@ -157,7 +157,7 @@ With this knowledge in mind, let's write the new version of our framework:: $response->send(); -There are a few new things in the code: +This code has a few new things: * Route names are used for template names; diff --git a/create_framework/unit_testing.rst b/create_framework/unit_testing.rst index 916711de0ce..de64ab60478 100644 --- a/create_framework/unit_testing.rst +++ b/create_framework/unit_testing.rst @@ -196,7 +196,7 @@ controller. We check that the response status is 200 and that its content is the one we have set in the controller. To check that we have covered all possible use cases, run the PHPUnit test -coverage feature (you need to enable `XDebug`_ first): +coverage feature (you need to enable `Xdebug`_ first): .. code-block:: terminal diff --git a/page_creation.rst b/page_creation.rst index 24735ffbc85..eef63ef6b7b 100644 --- a/page_creation.rst +++ b/page_creation.rst @@ -305,7 +305,7 @@ project: Most of the time, you'll be working in ``src/``, ``templates/`` or ``config/``. As you keep reading, you'll learn what can be done inside each of these. -So what about the other directories in the project? +What about the other directories in the project? ``bin/`` The famous ``bin/console`` file lives here (and other, less important diff --git a/quick_tour/flex_recipes.rst b/quick_tour/flex_recipes.rst index a9b101016ea..81df944ac28 100644 --- a/quick_tour/flex_recipes.rst +++ b/quick_tour/flex_recipes.rst @@ -36,7 +36,7 @@ small, simple and *fast*. And you're in total control of what you add. Flex Recipes and Aliases ------------------------ -So how can we install and configure Twig? By running one single command: +How can we install and configure Twig? By running one single command: .. code-block:: terminal diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 3c3c4e41bf6..ba26c3c5372 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -40,7 +40,7 @@ Symfony application: └─ vendor/ Can we already load the project in a browser? Yes! You can setup -:doc:`Nginx or Apache ` and configure their +:doc:`nginx or Apache ` and configure their document root to be the ``public/`` directory. But, for development, it's better to :doc:`install the Symfony local web server ` and run it as follows: @@ -100,7 +100,7 @@ A controller is just a normal function with *one* rule: it must return a Symfony ``Response`` object. But that response can contain anything: simple text, JSON or a full HTML page. -But the routing system is *much* more powerful. So let's make the route more interesting: +But the routing system is *much* more powerful. Let's make the route more interesting: .. code-block:: diff @@ -135,7 +135,7 @@ Try the page out by going to ``http://localhost:8000/hello/Symfony``. You should see: Hello Symfony! The value of the ``{name}`` in the URL is available as a ``$name`` argument in your controller. -But this can be even simpler! So let's install annotations support: +But this can be even simpler! Let's install annotations support: .. code-block:: terminal diff --git a/routing.rst b/routing.rst index b557763e118..aaeec66d221 100644 --- a/routing.rst +++ b/routing.rst @@ -1098,9 +1098,9 @@ Parameter Conversion A common routing need is to convert the value stored in some parameter (e.g. an integer acting as the user ID) into another value (e.g. the object that -represents the user). This feature is called a "param converter". +represents the user). This feature is called a "parameter converter". -To add support for "param converters" we need SensioFrameworkExtraBundle: +To add support for "parameter converters" we need SensioFrameworkExtraBundle: .. code-block:: terminal @@ -1133,11 +1133,11 @@ controller action. Instead of ``string $slug``, add ``BlogPost $post``:: } If your controller arguments include type-hints for objects (``BlogPost`` in -this case), the "param converter" makes a database request to find the object +this case), the "parameter converter" makes a database request to find the object using the request parameters (``slug`` in this case). If no object is found, Symfony generates a 404 response automatically. -Read the `full param converter documentation`_ to learn about the converters +Read the `full parameter converter documentation`_ to learn about the converters provided by Symfony and how to configure them. Special Parameters @@ -2635,7 +2635,7 @@ use the ``generateUrl()`` helper:: .. caution:: While objects are converted to string when used as placeholders, they are not - converted when used as extra parameters. So, if you're passing an object (e.g. an Uuid) + converted when used as extra parameters. If you're passing an object (e.g. an UUID) as value of an extra parameter, you need to explicitly convert it to a string:: $this->generateUrl('blog', ['uuid' => (string) $entity->getUuid()]); @@ -3067,5 +3067,5 @@ Learn more about Routing .. _`PHP regular expressions`: https://www.php.net/manual/en/book.pcre.php .. _`PCRE Unicode properties`: https://www.php.net/manual/en/regexp.reference.unicode.php -.. _`full param converter documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html +.. _`full parameter converter documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html .. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle diff --git a/setup.rst b/setup.rst index 11a443f44e1..c95ee20ef33 100644 --- a/setup.rst +++ b/setup.rst @@ -114,7 +114,7 @@ to run this command which displays information about the project: Running Symfony Applications ---------------------------- -In production, you should install a web server like Nginx or Apache and +In production, you should install a web server like nginx or Apache and :doc:`configure it to run Symfony `. This method can also be used if you're not using the Symfony local web server for development. @@ -211,7 +211,7 @@ Symfony Packs Sometimes a single feature requires installing several packages and bundles. Instead of installing them individually, Symfony provides **packs**, which are -Composer metapackages that include several dependencies. +Composer meta-packages that include several dependencies. For example, to add debugging features in your application, you can run the ``composer require --dev debug`` command. This installs the ``symfony/debug-pack``, diff --git a/templates.rst b/templates.rst index 1ff0ab1d44f..36625488353 100644 --- a/templates.rst +++ b/templates.rst @@ -362,7 +362,7 @@ Build, Versioning & More Advanced CSS, JavaScript and Image Handling ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For help building, versioning and minifying your JavaScript and -CSS assets in a modern way, read about :doc:`Symfony's Webpack Encore `. +CSS assets in a modern way, read about :doc:`Symfony's webpack Encore `. .. _twig-app-variable: @@ -1034,7 +1034,7 @@ JavaScript library. First, include the `hinclude.js`_ library in your page :ref:`linking to it ` from the template or adding it -to your application JavaScript :doc:`using Webpack Encore `. +to your application JavaScript :doc:`using webpack Encore `. As the embedded content comes from another page (or controller for that matter), Symfony uses a version of the standard ``render()`` function to configure