- {% block body %}{% endblock %}
-
- {% if self.comments()|trim %}
-
- {% block comments %}{% endblock %}
-
- {% endif%}
- 
++ + Online version + + | + + Components + + | + + Screencasts + +
+ +Contributing +------------ + +We love contributors! For more information on how you can contribute, please read +the [Symfony Docs Contributing Guide](https://symfony.com/doc/current/contributing/documentation/overview.html). + +> [!IMPORTANT] +> Use `6.4` branch as the base of your pull requests, unless you are documenting a +> feature that was introduced *after* Symfony 6.4 (e.g. in Symfony 7.2). + +Build Documentation Locally +--------------------------- + +This is not needed for contributing, but it's useful if you would like to debug some +issue in the docs or if you want to read Symfony Documentation offline. + +```bash +$ git clone git@github.com:symfony/symfony-docs.git + +$ cd symfony-docs/ +$ cd _build/ + +$ composer install + +$ php build.php +``` + +After generating docs, serve them with the internal PHP server: + +```bash +$ php -S localhost:8000 -t output/ +``` + +Browse `http://localhost:8000` to read the docs. diff --git a/_build/.requirements.txt b/_build/.requirements.txt deleted file mode 100644 index 430bce090b0..00000000000 --- a/_build/.requirements.txt +++ /dev/null @@ -1,13 +0,0 @@ -alabaster==0.7.10 -Babel==2.4.0 -docutils==0.13.1 -imagesize==0.7.1 -Jinja2==2.9.6 -MarkupSafe==1.0 -Pygments==2.2.0 -pytz==2017.2 -requests==2.20.0 -six==1.10.0 -snowballstemmer==1.2.1 -Sphinx==1.3.6 -git+https://github.com/fabpot/sphinx-php.git@7312eccce9465640752e51373a480da700e02345#egg_name=sphinx-php diff --git a/_build/Makefile b/_build/Makefile deleted file mode 100644 index 25b660056fe..00000000000 --- a/_build/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = . - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -c $(BUILDDIR) -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ../ -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.') }}
- {% endif %} - {% endif %} -{{ context|e }}
-- Displaying the {{ constant('NUMBER_OF_ITEMS', post) }} most recent results. -
- -And Doctrine entities and repositories can now easily access these values, -whereas they cannot access the container parameters:: - - namespace App\Repository; - - use App\Entity\Post; - use Doctrine\ORM\EntityRepository; - - class PostRepository extends EntityRepository - { - public function findLatest($limit = Post::NUMBER_OF_ITEMS) - { - // ... - } - } - -The only notable disadvantage of using constants for this kind of configuration -values is that you cannot redefine them easily in your tests. - -Parameter Naming ----------------- - -.. best-practice:: - - The name of your configuration parameters should be as short as possible and - should include a common prefix for the entire application. - -Using ``app.`` as the prefix of your parameters is a common practice to avoid -collisions with Symfony and third-party bundles/libraries parameters. Then, use -just one or two words to describe the purpose of the parameter: - -.. code-block:: yaml - - # config/services.yaml - parameters: - # don't do this: 'dir' is too generic and it doesn't convey any meaning - app.dir: '...' - # do this: short but easy to understand names - app.contents_dir: '...' - # it's OK to use dots, underscores, dashes or nothing, but always - # be consistent and use the same format for all the parameters - app.dir.contents: '...' - app.contents-dir: '...' - ----- - -Next: :doc:`/best_practices/business-logic` - -.. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle -.. _`constant() function`: https://twig.symfony.com/doc/2.x/functions/constant.html diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst deleted file mode 100644 index 0ef6fd1d3bc..00000000000 --- a/best_practices/controllers.rst +++ /dev/null @@ -1,236 +0,0 @@ -Controllers -=========== - -Symfony follows the philosophy of *"thin controllers and fat models"*. This -means that controllers should hold just the thin layer of *glue-code* -needed to coordinate the different parts of the application. - -Your controller methods should just call to other services, trigger some events -if needed and then return a response, but they should not contain any actual -business logic. If they do, refactor it out of the controller and into a service. - -.. best-practice:: - - Make your controller extend the ``AbstractController`` base controller - provided by Symfony and use annotations to configure routing, caching and - security whenever possible. - -Coupling the controllers to the underlying framework allows you to leverage -all of its features and increases your productivity. - -And since your controllers should be thin and contain nothing more than a -few lines of *glue-code*, spending hours trying to decouple them from your -framework doesn't benefit you in the long run. The amount of time *wasted* -isn't worth the benefit. - -In addition, using annotations for routing, caching and security simplifies -configuration. You don't need to browse tens of files created with different -formats (YAML, XML, PHP): all the configuration is just where you need it -and it only uses one format. - -Overall, this means you should aggressively decouple your business logic -from the framework while, at the same time, aggressively coupling your controllers -and routing *to* the framework in order to get the most out of it. - -Controller Action Naming ------------------------- - -.. best-practice:: - - Don't add the ``Action`` suffix to the methods of the controller actions. - -The first Symfony versions required that controller method names ended in -``Action`` (e.g. ``newAction()``, ``showAction()``). This suffix became optional -when annotations were introduced for controllers. In modern Symfony applications -this suffix is neither required nor recommended, so you can safely remove it. - -Routing Configuration ---------------------- - -To load routes defined as annotations in your controllers, add the following -configuration to the main routing configuration file: - -.. code-block:: yaml - - # config/routes.yaml - controllers: - resource: '../src/Controller/' - type: annotation - -This configuration will load annotations from any controller stored inside the -``src/Controller/`` directory and even from its subdirectories. So if your application -defines lots of controllers, it's perfectly ok to reorganize them into subdirectories: - -.. code-block:: text - -
+
This practice is no longer recommended unless the web application is extremely
simple. Hardcoding URLs can be a disadvantage because:
@@ -30,7 +26,7 @@ simple. Hardcoding URLs can be a disadvantage because:
is essential for some applications because it allows you to control how
the assets are cached. The Asset component allows you to define different
versioning strategies for each package;
-* **Moving assets location** is cumbersome and error-prone: it requires you to
+* **Moving assets' location** is cumbersome and error-prone: it requires you to
carefully update the URLs of all assets included in all templates. The Asset
component allows to move assets effortlessly just by changing the base path
value associated with the package of assets;
@@ -46,13 +42,13 @@ Installation
$ composer require symfony/asset
-Alternatively, you can clone the `Foo Bar
orBar Foo
+ // innerText() returns 'Foo' in both cases; and text() returns 'Foo Bar' and 'Bar Foo' respectively + + // if there are multiple text nodes, between other child nodes, like + //Foo Bar Baz
+ // innerText() returns only the first text node 'Foo' - The default argument of ``text()`` was introduced in Symfony 4.3. + // like text(), innerText() also trims whitespace characters by default, + // but you can get the unchanged text by passing FALSE as argument + $text = $crawler->filterXPath('//body/p')->innerText(false); Access the attribute value of the first node of the current selection:: $class = $crawler->filterXPath('//body/p')->attr('class'); +.. tip:: + + You can define the default value to use if the node or attribute is empty + by using the second argument of the ``attr()`` method:: + + $class = $crawler->filterXPath('//body/p')->attr('class', 'my-default-class'); + Extract attribute and/or node values from the list of nodes:: $attributes = $crawler @@ -227,37 +252,47 @@ Extract attribute and/or node values from the list of nodes:: Special attribute ``_text`` represents a node value, while ``_name`` represents the element name (the HTML tag name). - .. versionadded:: 4.3 - - The special attribute ``_name`` was introduced in Symfony 4.3. - Call an anonymous function on each node of the list:: use Symfony\Component\DomCrawler\Crawler; // ... - $nodeValues = $crawler->filter('p')->each(function (Crawler $node, $i) { + $nodeValues = $crawler->filter('p')->each(function (Crawler $node, $i): string { return $node->text(); }); The anonymous function receives the node (as a Crawler) and the position as arguments. The result is an array of values returned by the anonymous function calls. +When using nested crawler, beware that ``filterXPath()`` is evaluated in the +context of the crawler:: + + $crawler->filterXPath('parent')->each(function (Crawler $parentCrawler, $i): void { + // DON'T DO THIS: direct child can not be found + $subCrawler = $parentCrawler->filterXPath('sub-tag/sub-child-tag'); + + // DO THIS: specify the parent tag too + $subCrawler = $parentCrawler->filterXPath('parent/sub-tag/sub-child-tag'); + $subCrawler = $parentCrawler->filterXPath('node()/sub-tag/sub-child-tag'); + }); + Adding the Content ~~~~~~~~~~~~~~~~~~ -The crawler supports multiple ways of adding the content:: +The crawler supports multiple ways of adding the content, but they are mutually +exclusive, so you can only use one of them to add content (e.g. if you pass the +content to the ``Crawler`` constructor, you can't call ``addContent()`` later):: - $crawler = new Crawler('Made by '.$message->getUsername().'
', - 'text/html' - ) - ); - - return $envelope; - } + public function __construct( + private MailerInterface $mailer, + private string $toEmail, + ) { + } + + public function send(Envelope $envelope): Envelope + { + $message = $envelope->getMessage(); + + if (!$message instanceof ImportantAction) { + throw new \InvalidArgumentException(sprintf('This transport only supports "%s" messages.', ImportantAction::class)); + } + + $this->mailer->send( + (new Email()) + ->to($this->toEmail) + ->subject('Important action made') + ->html('Made by '.$message->getUsername().'
') + ); + + return $envelope; + } } Your own Receiver @@ -259,43 +284,63 @@ application but you can't use an API and need to use a shared CSV file with new orders. You will read this CSV file and dispatch a ``NewOrder`` message. All you need to -do is to write your custom CSV receiver and Symfony will do the rest. - -First, create your receiver:: +do is to write your own CSV receiver:: namespace App\MessageReceiver; use App\Message\NewOrder; + use Symfony\Component\Messenger\Envelope; + use Symfony\Component\Messenger\Exception\MessageDecodingFailedException; use Symfony\Component\Messenger\Transport\Receiver\ReceiverInterface; use Symfony\Component\Serializer\SerializerInterface; - use Symfony\Component\Messenger\Envelope; class NewOrdersFromCsvFileReceiver implements ReceiverInterface { - private $serializer; - private $filePath; - - public function __construct(SerializerInterface $serializer, string $filePath) - { - $this->serializer = $serializer; - $this->filePath = $filePath; - } - - public function receive(callable $handler): void - { - $ordersFromCsv = $this->serializer->deserialize(file_get_contents($this->filePath), 'csv'); - - foreach ($ordersFromCsv as $orderFromCsv) { - $order = new NewOrder($orderFromCsv['id'], $orderFromCsv['account_id'], $orderFromCsv['amount']); - - $handler(new Envelope($order)); - } - } - - public function stop(): void - { - // noop - } + private $connection; + + public function __construct( + private SerializerInterface $serializer, + private string $filePath, + ) { + // Available connection bundled with the Messenger component + // can be found in "Symfony\Component\Messenger\Bridge\*\Transport\Connection". + $this->connection = /* create your connection */; + } + + public function get(): iterable + { + // Receive the envelope according to your transport ($yourEnvelope here), + // in most cases, using a connection is the easiest solution. + $yourEnvelope = $this->connection->get(); + if (null === $yourEnvelope) { + return []; + } + + try { + $envelope = $this->serializer->decode([ + 'body' => $yourEnvelope['body'], + 'headers' => $yourEnvelope['headers'], + ]); + } catch (MessageDecodingFailedException $exception) { + $this->connection->reject($yourEnvelope['id']); + throw $exception; + } + + return [$envelope->with(new CustomStamp($yourEnvelope['id']))]; + } + + public function ack(Envelope $envelope): void + { + // Add information about the handled message + } + + public function reject(Envelope $envelope): void + { + // In the case of a custom connection + $id = /* get the message id thanks to information or stamps present in the envelope */; + + $this->connection->reject($id); + } } Receiver and Sender on the same Bus @@ -308,6 +353,7 @@ middleware will know it should not route these messages again to a transport. Learn more ---------- + .. toctree:: :maxdepth: 1 :glob: @@ -315,5 +361,5 @@ Learn more /messenger /messenger/* -.. _blog posts about command buses: https://matthiasnoback.nl/tags/command%20bus/ -.. _SimpleBus project: http://simplebus.io +.. _`blog posts about command buses`: https://matthiasnoback.nl/tags/command%20bus/ +.. _`SimpleBus project`: https://docs.simplebus.io/en/latest/ diff --git a/components/mime.rst b/components/mime.rst new file mode 100644 index 00000000000..c043b342ebc --- /dev/null +++ b/components/mime.rst @@ -0,0 +1,298 @@ +The Mime Component +================== + + The Mime component allows manipulating the MIME messages used to send emails + and provides utilities related to MIME types. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/mime + +.. include:: /components/require_autoload.rst.inc + +Introduction +------------ + +`MIME`_ (Multipurpose Internet Mail Extensions) is an Internet standard that +extends the original basic format of emails to support features like: + +* Headers and text contents using non-ASCII characters; +* Message bodies with multiple parts (e.g. HTML and plain text contents); +* Non-text attachments: audio, video, images, PDF, etc. + +The entire MIME standard is complex and huge, but Symfony abstracts all that +complexity to provide two ways of creating MIME messages: + +* A high-level API based on the :class:`Symfony\\Component\\Mime\\Email` class + to quickly create email messages with all the common features; +* A low-level API based on the :class:`Symfony\\Component\\Mime\\Message` class + to have absolute control over every single part of the email message. + +Usage +----- + +Use the :class:`Symfony\\Component\\Mime\\Email` class and their *chainable* +methods to compose the entire email message:: + + use Symfony\Component\Mime\Email; + + $email = (new Email()) + ->from('fabien@symfony.com') + ->to('foo@example.com') + ->cc('bar@example.com') + ->bcc('baz@example.com') + ->replyTo('fabien@symfony.com') + ->priority(Email::PRIORITY_HIGH) + ->subject('Important Notification') + ->text('Lorem ipsum...') + ->html('...
') + ; + +The only purpose of this component is to create the email messages. Use the +:doc:`Mailer component ` to actually send them. + +Twig Integration +---------------- + +The Mime component comes with excellent integration with Twig, allowing you to +create messages from Twig templates, embed images, inline CSS and more. Details +on how to use those features can be found in the Mailer documentation: +:ref:`Twig: HTML & CSS...
', null, 'html'); + $body = new AlternativePart($textContent, $htmlContent); + + $email = new Message($headers, $body); + +Embedding images and attaching files is possible by creating the appropriate +email multiparts:: + + // ... + use Symfony\Component\Mime\Part\DataPart; + use Symfony\Component\Mime\Part\Multipart\MixedPart; + use Symfony\Component\Mime\Part\Multipart\RelatedPart; + + // ... + $embeddedImage = new DataPart(fopen('/path/to/images/logo.png', 'r'), null, 'image/png'); + $imageCid = $embeddedImage->getContentId(); + + $attachedFile = new DataPart(fopen('/path/to/documents/terms-of-use.pdf', 'r'), null, 'application/pdf'); + + $textContent = new TextPart('Lorem ipsum...'); + $htmlContent = new TextPart(sprintf( + '...
', $imageCid + ), null, 'html'); + $bodyContent = new AlternativePart($textContent, $htmlContent); + $body = new RelatedPart($bodyContent, $embeddedImage); + + $messageParts = new MixedPart($body, $attachedFile); + + $email = new Message($headers, $messageParts); + +Serializing Email Messages +-------------------------- + +Email messages created with either the ``Email`` or ``Message`` classes can be +serialized because they are simple data objects:: + + $email = (new Email()) + ->from('fabien@symfony.com') + // ... + ; + + $serializedEmail = serialize($email); + +A common use case is to store serialized email messages, include them in a +message sent with the :doc:`Messenger component ` and +recreate them later when sending them. Use the +:class:`Symfony\\Component\\Mime\\RawMessage` class to recreate email messages +from their serialized contents:: + + use Symfony\Component\Mime\RawMessage; + + // ... + $serializedEmail = serialize($email); + + // later, recreate the original message to actually send it + $message = new RawMessage(unserialize($serializedEmail)); + +MIME Types Utilities +-------------------- + +Although MIME was designed mainly for creating emails, the content types (also +known as `MIME types`_ and "media types") defined by MIME standards are also of +importance in communication protocols outside of email, such as HTTP. That's +why this component also provides utilities to work with MIME types. + +The :class:`Symfony\\Component\\Mime\\MimeTypes` class transforms between +MIME types and file name extensions:: + + use Symfony\Component\Mime\MimeTypes; + + $mimeTypes = new MimeTypes(); + $exts = $mimeTypes->getExtensions('application/javascript'); + // $exts = ['js', 'jsm', 'mjs'] + $exts = $mimeTypes->getExtensions('image/jpeg'); + // $exts = ['jpeg', 'jpg', 'jpe'] + + $types = $mimeTypes->getMimeTypes('js'); + // $types = ['application/javascript', 'application/x-javascript', 'text/javascript'] + $types = $mimeTypes->getMimeTypes('apk'); + // $types = ['application/vnd.android.package-archive'] + +These methods return arrays with one or more elements. The element position +indicates its priority, so the first returned extension is the preferred one. + +.. _components-mime-type-guess: + +Guessing the MIME Type +~~~~~~~~~~~~~~~~~~~~~~ + +Another useful utility allows to guess the MIME type of any given file:: + + use Symfony\Component\Mime\MimeTypes; + + $mimeTypes = new MimeTypes(); + $mimeType = $mimeTypes->guessMimeType('/some/path/to/image.gif'); + // Guessing is not based on the file name, so $mimeType will be 'image/gif' + // only if the given file is truly a GIF image + +Guessing the MIME type is a time-consuming process that requires inspecting +part of the file contents. Symfony applies multiple guessing mechanisms, one +of them based on the PHP `fileinfo extension`_. It's recommended to install +that extension to improve the guessing performance. + +Adding a MIME Type Guesser +.......................... + +You can add your own MIME type guesser by creating a class that implements +:class:`Symfony\\Component\\Mime\\MimeTypeGuesserInterface`:: + + namespace App; + + use Symfony\Component\Mime\MimeTypeGuesserInterface; + + class SomeMimeTypeGuesser implements MimeTypeGuesserInterface + { + public function isGuesserSupported(): bool + { + // return true when the guesser is supported (might depend on the OS for instance) + return true; + } + + public function guessMimeType(string $path): ?string + { + // inspect the contents of the file stored in $path to guess its + // type and return a valid MIME type ... or null if unknown + + return '...'; + } + } + +MIME type guessers must be :ref:`registered as servicesThe google tracking code is:
- -.. caution:: - - The global variables cannot be called ``this`` or ``view``, since they are - already used by the PHP engine. - -.. note:: - - The global variables can be overridden by a local variable in the template - with the same name. - -Output Escaping ---------------- - -When you render variables, you should probably escape them so that HTML or -JavaScript code isn't written out to your page. This will prevent things like -XSS attacks. To do this, use the -:method:`Symfony\\Component\\Templating\\PhpEngine::escape` method:: - - escape($firstname) ?> - -By default, the ``escape()`` method assumes that the variable is outputted -within an HTML context. The second argument lets you change the context. For -example, to output something inside JavaScript, use the ``js`` context:: - - escape($var, 'js') ?> - -The component comes with an HTML and JS escaper. You can register your own -escaper using the -:method:`Symfony\\Component\\Templating\\PhpEngine::setEscaper` method:: - - $templating->setEscaper('css', function ($value) { - // ... all CSS escaping - - return $escapedValue; - }); - -Helpers -------- - -The Templating component can be extended via helpers. Helpers are PHP objects -that provide features useful in a template context. The component has one -built-in helper: - -* :doc:`/components/templating/slotshelper` - -Before you can use these helpers, you need to register them using -:method:`Symfony\\Component\\Templating\\PhpEngine::set`:: - - use Symfony\Component\Templating\Helper\SlotsHelper; - // ... - - $templating->set(new SlotsHelper()); - -Custom Helpers -~~~~~~~~~~~~~~ - -You can create your own helpers by creating a class which implements -:class:`Symfony\\Component\\Templating\\Helper\\HelperInterface`. However, -most of the time you'll extend -:class:`Symfony\\Component\\Templating\\Helper\\Helper`. - -The ``Helper`` has one required method: -:method:`Symfony\\Component\\Templating\\Helper\\HelperInterface::getName`. -This is the name that is used to get the helper from the ``$view`` object. - -Creating a Custom Engine ------------------------- - -Besides providing a PHP templating engine, you can also create your own engine -using the Templating component. To do that, create a new class which -implements the :class:`Symfony\\Component\\Templating\\EngineInterface`. This -requires 3 method: - -* :method:`render($name, array $parameters = [])