++ + 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/build.php b/_build/build.php new file mode 100755 index 00000000000..b684700a848 --- /dev/null +++ b/_build/build.php @@ -0,0 +1,91 @@ +#!/usr/bin/env php +register('build-docs') + ->addOption('generate-fjson-files', null, InputOption::VALUE_NONE, 'Use this option to generate docs both in HTML and JSON formats') + ->addOption('disable-cache', null, InputOption::VALUE_NONE, 'Use this option to force a full regeneration of all doc contents') + ->setCode(function(InputInterface $input, OutputInterface $output) { + // the doc building app doesn't work on Windows + if ('\\' === DIRECTORY_SEPARATOR) { + $output->writeln('Username: {{ app.user.username }}
- - .. code-block:: html+php - -Username: getUser()->getUsername() ?>
- - -Using Multiple User Providers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Each authentication mechanism (e.g. HTTP Authentication, form login, etc) -uses exactly one user provider, and will use the first declared user provider -by default. But what if you want to specify a few users via configuration -and the rest of your users in the database? This is possible by creating -a new provider that chains the two together: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/security.yml - security: - providers: - chain_provider: - chain: - providers: [in_memory, user_db] - in_memory: - memory: - users: - foo: { password: test } - user_db: - entity: { class: Acme\UserBundle\Entity\User, property: username } - - .. code-block:: xml - - -{{ entry.body }}
- {% endfor %} - {% endblock %} - - .. code-block:: html+php - - - extend('::base.html.php') ?> - - set('title', 'My cool blog posts') ?> - - start('body') ?> - -getBody() ?>
- - stop() ?> - -.. note:: - - The parent template is identified by a special string syntax - (``::base.html.twig``) that indicates that the template lives in the - ``app/Resources/views`` directory of the project. This naming convention is - explained fully in :ref:`template-naming-locations`. - -The key to template inheritance is the ``{% extends %}`` tag. This tells -the templating engine to first evaluate the base template, which sets up -the layout and defines several blocks. The child template is then rendered, -at which point the ``title`` and ``body`` blocks of the parent are replaced -by those from the child. Depending on the value of ``blog_entries``, the -output might look like this: - -.. code-block:: html - - - - - -The body of the first post.
- -The body of the second post.
-- {{ article.body }} -
- - .. code-block:: html+php - - -- getBody() ?> -
- -Including this template from any other template is simple: - -.. configuration-block:: - - .. code-block:: html+jinja - - {# src/Acme/ArticleBundle/Resources/views/Article/list.html.twig #} - {% extends 'AcmeArticleBundle::layout.html.twig' %} - - {% block body %} - }}){kind=logo}
-
-
-
- .. code-block:: html+php
-
-  ?>){kind=logo}
-
-
-
-The ``asset`` function's main purpose is to make your application more portable.
-If your application lives at the root of your host (e.g. http://example.com),
-then the rendered paths should be ``/images/logo.png``. But if your application
-lives in a subdirectory (e.g. http://example.com/my_app), each asset path
-should render with the subdirectory (e.g. ``/my_app/images/logo.png``). The
-``asset`` function takes care of this by determining how your application is
-being used and generating the correct paths accordingly.
-
-Additionally, if you use the ``asset`` function, Symfony can automatically
-append a query string to your asset, in order to guarantee that updated static
-assets won't be cached when deployed. For example, ``/images/logo.png`` might
-look like ``/images/logo.png?v2``. For more information, see the :ref:`ref-framework-assets-version`
-configuration option.
-
-.. index::
- single: Templating; Including stylesheets and Javascripts
- single: Stylesheets; Including stylesheets
- single: Javascript; Including Javascripts
-
-Including Stylesheets and Javascripts in Twig
----------------------------------------------
-
-No site would be complete without including Javascript files and stylesheets.
-In Symfony, the inclusion of these assets is handled elegantly by taking
-advantage of Symfony's template inheritance.
-
-.. tip::
-
- This section will teach you the philosophy behind including stylesheet
- and Javascript assets in Symfony. Symfony also packages another library,
- called Assetic, which follows this philosophy but allows you to do much
- more interesting things with those assets. For more information on
- using Assetic see :doc:`/cookbook/assetic/asset_management`.
-
-
-Start by adding two blocks to your base template that will hold your assets:
-one called ``stylesheets`` inside the ``head`` tag and another called ``javascripts``
-just above the closing ``body`` tag. These blocks will contain all of the
-stylesheets and Javascripts that you'll need throughout your site:
-
-.. code-block:: html+jinja
-
- {# app/Resources/views/base.html.twig #}
-
-
- {# ... #}
-
- {% block stylesheets %}
-
- {% endblock %}
-
-
- {# ... #}
-
- {% block javascripts %}
-
- {% endblock %}
-
-
-
-That's easy enough! But what if you need to include an extra stylesheet or
-Javascript from a child template? For example, suppose you have a contact
-page and you need to include a ``contact.css`` stylesheet *just* on that
-page. From inside that contact page's template, do the following:
-
-.. code-block:: html+jinja
-
- {# src/Acme/DemoBundle/Resources/views/Contact/contact.html.twig #}
- {% extends '::base.html.twig' %}
-
- {% block stylesheets %}
- {{ parent() }}
-
-
- {% endblock %}
-
- {# ... #}
-
-In the child template, you simply override the ``stylesheets`` block and
-put your new stylesheet tag inside of that block. Of course, since you want
-to add to the parent block's content (and not actually *replace* it), you
-should use the ``parent()`` Twig function to include everything from the ``stylesheets``
-block of the base template.
-
-You can also include assets located in your bundles' ``Resources/public`` folder.
-You will need to run the ``php app/console assets:install target [--symlink]``
-command, which moves (or symlinks) files into the correct location. (target
-is by default "web").
-
-.. code-block:: html+jinja
-
-
-
-The end result is a page that includes both the ``main.css`` and ``contact.css``
-stylesheets.
-
-Global Template Variables
--------------------------
-
-During each request, Symfony2 will set a global template variable ``app``
-in both Twig and PHP template engines by default. The ``app`` variable
-is a :class:`Symfony\\Bundle\\FrameworkBundle\\Templating\\GlobalVariables`
-instance which will give you access to some application specific variables
-automatically:
-
-* ``app.security`` - The security context.
-* ``app.user`` - The current user object.
-* ``app.request`` - The request object.
-* ``app.session`` - The session object.
-* ``app.environment`` - The current environment (dev, prod, etc).
-* ``app.debug`` - True if in debug mode. False otherwise.
-
-.. configuration-block::
-
- .. code-block:: html+jinja
-
- Username: {{ app.user.username }}
- {% if app.debug %} -Request method: {{ app.request.method }}
-Application Environment: {{ app.environment }}
- {% endif %} - - .. code-block:: html+php - -Username: getUser()->getUsername() ?>
- getDebug()): ?> -Request method: getRequest()->getMethod() ?>
-Application Environment: getEnvironment() ?>
- - -.. tip:: - - You can add your own global template variables. See the cookbook example - on :doc:`Global Variables`. - -.. index:: - single: Templating; The templating service - -Configuring and using the ``templating`` Service ------------------------------------------------- - -The heart of the template system in Symfony2 is the templating ``Engine``. -This special object is responsible for rendering templates and returning -their content. When you render a template in a controller, for example, -you're actually using the templating engine service. For example:: - - return $this->render('AcmeArticleBundle:Article:index.html.twig'); - -is equivalent to:: - - use Symfony\Component\HttpFoundation\Response; - - $engine = $this->container->get('templating'); - $content = $engine->render('AcmeArticleBundle:Article:index.html.twig'); - - return $response = new Response($content); - -.. _template-configuration: - -The templating engine (or "service") is preconfigured to work automatically -inside Symfony2. It can, of course, be configured further in the application -configuration file: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - # ... - templating: { engines: ['twig'] } - - .. code-block:: xml - - -{{ entry.body }}
- {% endfor %} - {% endblock %} - -Notice that this template extends the section template -(``AcmeBlogBundle::layout.html.twig``) -which in-turn extends the base application layout (``::base.html.twig``). -This is the common three-level inheritance model. - -When building your application, you may choose to follow this method or simply -make each page template extend the base application template directly -(e.g. ``{% extends '::base.html.twig' %}``). The three-template model is -a best-practice method used by vendor bundles so that the base template for -a bundle can be easily overridden to properly extend your application's base -layout. - -.. index:: - single: Templating; Output escaping - -Output Escaping ---------------- - -When generating HTML from a template, there is always a risk that a template -variable may output unintended HTML or dangerous client-side code. The result -is that dynamic content could break the HTML of the resulting page or allow -a malicious user to perform a `Cross Site Scripting`_ (XSS) attack. Consider -this classic example: - -.. configuration-block:: - - .. code-block:: html+jinja - - Hello {{ name }} - - .. code-block:: html+php - - Hello - -Imagine that the user enters the following code as his/her name: - -.. code-block:: text - - - -Without any output escaping, the resulting template will cause a JavaScript -alert box to pop up: - -.. code-block:: html - - Hello - -And while this seems harmless, if a user can get this far, that same user -should also be able to write JavaScript that performs malicious actions -inside the secure area of an unknowing, legitimate user. - -The answer to the problem is output escaping. With output escaping on, the -same template will render harmlessly, and literally print the ``script`` -tag to the screen: - -.. code-block:: html - - Hello <script>alert('helloe')</script> - -The Twig and PHP templating systems approach the problem in different ways. -If you're using Twig, output escaping is on by default and you're protected. -In PHP, output escaping is not automatic, meaning you'll need to manually -escape where necessary. - -Output Escaping in Twig -~~~~~~~~~~~~~~~~~~~~~~~ - -If you're using Twig templates, then output escaping is on by default. This -means that you're protected out-of-the-box from the unintentional consequences -of user-submitted code. By default, the output escaping assumes that content -is being escaped for HTML output. - -In some cases, you'll need to disable output escaping when you're rendering -a variable that is trusted and contains markup that should not be escaped. -Suppose that administrative users are able to write articles that contain -HTML code. By default, Twig will escape the article body. - -To render it normally, add the ``raw`` filter: - -.. code-block:: jinja - - {{ article.body|raw }} - -You can also disable output escaping inside a ``{% block %}`` area or -for an entire template. For more information, see `Output Escaping`_ in -the Twig documentation. - -Output Escaping in PHP -~~~~~~~~~~~~~~~~~~~~~~ - -Output escaping is not automatic when using PHP templates. This means that -unless you explicitly choose to escape a variable, you're not protected. To -use output escaping, use the special ``escape()`` view method: - -.. code-block:: html+php - - Hello escape($name) ?> - -By default, the ``escape()`` method assumes that the variable is being rendered -within an HTML context (and thus the variable is escaped to be safe for HTML). -The second argument lets you change the context. For example, to output something -in a JavaScript string, use the ``js`` context: - -.. code-block:: html+php - - var myMsg = 'Hello escape($name, 'js') ?>'; - -.. index:: - single: Templating; Formats - -.. _template-formats: - -Debugging ---------- - -.. versionadded:: 2.0.9 - This feature is available as of Twig ``1.5.x``, which was first shipped - with Symfony 2.0.9. - -When using PHP, you can use ``var_dump()`` if you need to quickly find the -value of a variable passed. This is useful, for example, inside your controller. -The same can be achieved when using Twig by using the debug extension. This -needs to be enabled in the config: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - services: - acme_hello.twig.extension.debug: - class: Twig_Extension_Debug - tags: - - { name: 'twig.extension' } - - .. code-block:: xml - - -
+
+This practice is no longer recommended unless the web application is extremely
+simple. Hardcoding URLs can be a disadvantage because:
+
+* **Templates get verbose**: you have to write the full path for each
+ asset. When using the Asset component, you can group assets in packages to
+ avoid repeating the common part of their path;
+* **Versioning is difficult**: it has to be custom managed for each
+ application. Adding a version (e.g. ``main.css?v=5``) to the asset URLs
+ 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
+ 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;
+* **It's nearly impossible to use multiple CDNs**: this technique requires
+ you to change the URL of the asset randomly for each request. The Asset component
+ provides out-of-the-box support for any number of multiple CDNs, both regular
+ (``http://``) and secure (``https://``).
+
+Installation
+------------
+
+.. code-block:: terminal
+
+ $ composer require symfony/asset
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+.. _asset-packages:
+
+Asset Packages
+~~~~~~~~~~~~~~
+
+The Asset component manages assets through packages. A package groups all the
+assets which share the same properties: versioning strategy, base path, CDN hosts,
+etc. In the following basic example, a package is created to manage assets without
+any versioning::
+
+ use Symfony\Component\Asset\Package;
+ use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy;
+
+ $package = new Package(new EmptyVersionStrategy());
+
+ // Absolute path
+ echo $package->getUrl('/image.png');
+ // result: /image.png
+
+ // Relative path
+ echo $package->getUrl('image.png');
+ // result: image.png
+
+Packages implement :class:`Symfony\\Component\\Asset\\PackageInterface`,
+which defines the following two methods:
+
+:method:`Symfony\\Component\\Asset\\PackageInterface::getVersion`
+ Returns the asset version for an asset.
+
+:method:`Symfony\\Component\\Asset\\PackageInterface::getUrl`
+ Returns an absolute or root-relative public path.
+
+With a package, you can:
+
+A) :ref:`version the assets Made by '.$message->getUsername().'
') + ); + + return $envelope; + } + } + +Your own Receiver +~~~~~~~~~~~~~~~~~ + +A receiver is responsible for getting messages from a source and dispatching +them to the application. + +Imagine you already processed some "orders" in your application using a +``NewOrder`` message. Now you want to integrate with a 3rd party or a legacy +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 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; + + class NewOrdersFromCsvFileReceiver implements ReceiverInterface + { + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To allow sending and receiving messages on the same bus and prevent an infinite +loop, the message bus will add a :class:`Symfony\\Component\\Messenger\\Stamp\\ReceivedStamp` +stamp to the message envelopes and the :class:`Symfony\\Component\\Messenger\\Middleware\\SendMessageMiddleware` +middleware will know it should not route these messages again to a transport. + +Learn more +---------- + +.. toctree:: + :maxdepth: 1 + :glob: + + /messenger + /messenger/* + +.. _`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 services- body ?> -
- -To use template inheritance, the :class:`Symfony\\Component\\Templating\\Helper\\SlotsHelper` -helper must be registered:: - - use Symfony\Component\Templating\Helper\SlotsHelper; - - $view->set(new SlotsHelper()); - - // Retrieve page object - $page = ...; - - echo $view->render('page.php', array('page' => $page)); - -.. note:: - - Multiple levels of inheritance is possible: a layout can extend an other - layout. - -Output Escaping ---------------- - -This documentation is still being written. - -The Asset Helper ----------------- - -This documentation is still being written. - -.. _Packagist: https://packagist.org/packages/symfony/templating \ No newline at end of file diff --git a/components/type_info.rst b/components/type_info.rst new file mode 100644 index 00000000000..817c7f1d61a --- /dev/null +++ b/components/type_info.rst @@ -0,0 +1,202 @@ +The TypeInfo Component +====================== + +The TypeInfo component extracts type information from PHP elements like properties, +arguments and return types. + +This component provides: + +* A powerful ``Type`` definition that can handle unions, intersections, and generics + (and can be extended to support more types in the future); +* A way to get types from PHP elements such as properties, method arguments, + return types, and raw strings. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/type-info + +.. include:: /components/require_autoload.rst.inc + +Usage +----- + +This component gives you a :class:`Symfony\\Component\\TypeInfo\\Type` object that +represents the PHP type of anything you built or asked to resolve. + +There are two ways to use this component. First one is to create a type manually thanks +to the :class:`Symfony\\Component\\TypeInfo\\Type` static methods as following:: + + use Symfony\Component\TypeInfo\Type; + + Type::int(); + Type::nullable(Type::string()); + Type::generic(Type::object(Collection::class), Type::int()); + Type::list(Type::bool()); + Type::intersection(Type::object(\Stringable::class), Type::object(\Iterator::class)); + +Many others methods are available and can be found +in :class:`Symfony\\Component\\TypeInfo\\TypeFactoryTrait`. + +You can also use a generic method that detects the type automatically:: + + Type::fromValue(1.1); // same as Type::float() + Type::fromValue('...'); // same as Type::string() + Type::fromValue(false); // same as Type::false() + +.. versionadded:: 7.3 + + The ``fromValue()`` method was introduced in Symfony 7.3. + +Resolvers +~~~~~~~~~ + +The second way to use the component is by using ``TypeInfo`` to resolve a type +based on reflection or a simple string. This approach is designed for libraries +that need a simple way to describe a class or anything with a type:: + + use Symfony\Component\TypeInfo\Type; + use Symfony\Component\TypeInfo\TypeResolver\TypeResolver; + + class Dummy + { + public function __construct( + public int $id, + ) { + } + } + + // Instantiate a new resolver + $typeResolver = TypeResolver::create(); + + // Then resolve types for any subject + $typeResolver->resolve(new \ReflectionProperty(Dummy::class, 'id')); // returns an "int" Type instance + $typeResolver->resolve('bool'); // returns a "bool" Type instance + + // Types can be instantiated thanks to static factories + $type = Type::list(Type::nullable(Type::bool())); + + // Type instances have several helper methods + + // for collections, it returns the type of the item used as the key; + // in this example, the collection is a list, so it returns an "int" Type instance + $keyType = $type->getCollectionKeyType(); + + // you can chain the utility methods (e.g. to introspect the values of the collection) + // the following code will return true + $isValueNullable = $type->getCollectionValueType()->isNullable(); + +Each of these calls will return you a ``Type`` instance that corresponds to the +static method used. You can also resolve types from a string (as shown in the +``bool`` parameter of the previous example) + +PHPDoc Parsing +~~~~~~~~~~~~~~ + +In many cases, you may not have cleanly typed properties or may need more precise +type definitions provided by advanced PHPDoc. To achieve this, you can use a string +resolver based on the PHPDoc annotations. + +First, run the command ``composer require phpstan/phpdoc-parser`` to install the +PHP package required for string resolving. Then, follow these steps:: + + use Symfony\Component\TypeInfo\TypeResolver\TypeResolver; + + class Dummy + { + public function __construct( + public int $id, + /** @var string[] $tags */ + public array $tags, + ) { + } + } + + $typeResolver = TypeResolver::create(); + $typeResolver->resolve(new \ReflectionProperty(Dummy::class, 'id')); // returns an "int" Type + $typeResolver->resolve(new \ReflectionProperty(Dummy::class, 'tags')); // returns a collection with "int" as key and "string" as values Type + +Advanced Usages +~~~~~~~~~~~~~~~ + +The TypeInfo component provides various methods to manipulate and check types, +depending on your needs. + +**Identify** a type:: + + // define a simple integer type + $type = Type::int(); + // check if the type matches a specific identifier + $type->isIdentifiedBy(TypeIdentifier::INT); // true + $type->isIdentifiedBy(TypeIdentifier::STRING); // false + + // define a union type (equivalent to PHP's int|string) + $type = Type::union(Type::string(), Type::int()); + // now the second check is true because the union type contains the string type + $type->isIdentifiedBy(TypeIdentifier::INT); // true + $type->isIdentifiedBy(TypeIdentifier::STRING); // true + + class DummyParent {} + class Dummy extends DummyParent implements DummyInterface {} + + // define an object type + $type = Type::object(Dummy::class); + + // check if the type is an object or matches a specific class + $type->isIdentifiedBy(TypeIdentifier::OBJECT); // true + $type->isIdentifiedBy(Dummy::class); // true + // check if it inherits/implements something + $type->isIdentifiedBy(DummyParent::class); // true + $type->isIdentifiedBy(DummyInterface::class); // true + +Checking if a type **accepts a value**:: + + $type = Type::int(); + // check if the type accepts a given value + $type->accepts(123); // true + $type->accepts('z'); // false + + $type = Type::union(Type::string(), Type::int()); + // now the second check is true because the union type accepts either an int or a string value + $type->accepts(123); // true + $type->accepts('z'); // true + +.. versionadded:: 7.3 + + The :method:`Symfony\\Component\\TypeInfo\\Type::accepts` + method was introduced in Symfony 7.3. + +Using callables for **complex checks**:: + + class Foo + { + private int $integer; + private string $string; + private ?float $float; + } + + $reflClass = new \ReflectionClass(Foo::class); + + $resolver = TypeResolver::create(); + $integerType = $resolver->resolve($reflClass->getProperty('integer')); + $stringType = $resolver->resolve($reflClass->getProperty('string')); + $floatType = $resolver->resolve($reflClass->getProperty('float')); + + // define a callable to validate non-nullable number types + $isNonNullableNumber = function (Type $type): bool { + if ($type->isNullable()) { + return false; + } + + if ($type->isIdentifiedBy(TypeIdentifier::INT) || $type->isIdentifiedBy(TypeIdentifier::FLOAT)) { + return true; + } + + return false; + }; + + $integerType->isSatisfiedBy($isNonNullableNumber); // true + $stringType->isSatisfiedBy($isNonNullableNumber); // false + $floatType->isSatisfiedBy($isNonNullableNumber); // false diff --git a/components/uid.rst b/components/uid.rst new file mode 100644 index 00000000000..6c92fff0af9 --- /dev/null +++ b/components/uid.rst @@ -0,0 +1,723 @@ +The UID Component +================= + + The UID component provides utilities to work with `unique identifiers`_ (UIDs) + such as UUIDs and ULIDs. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/uid + +.. include:: /components/require_autoload.rst.inc + +.. _uuid: + +UUIDs +----- + +`UUIDs`_ (*universally unique identifiers*) are one of the most popular UIDs in +the software industry. UUIDs are 128-bit numbers usually represented as five +groups of hexadecimal characters: ``xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx`` +(the ``M`` digit is the UUID version and the ``N`` digit is the UUID variant). + +Generating UUIDs +~~~~~~~~~~~~~~~~ + +Use the named constructors of the ``Uuid`` class or any of the specific classes +to create each type of UUID: + +**UUID v1** (time-based) + +Generates the UUID using a timestamp and the MAC address of your device +(`read UUIDv1 spec