- {% 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 53c6c3ddff0..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.10.1 -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 }}
-
+
This practice is no longer recommended unless the web application is extremely
simple. Hardcoding URLs can be a disadvantage because:
@@ -51,6 +47,8 @@ Installation
Usage
-----
+.. _asset-packages:
+
Asset Packages
~~~~~~~~~~~~~~
@@ -147,7 +145,6 @@ corresponding output file:
.. code-block:: json
- // rev-manifest.json
{
"css/app.css": "build/css/app.b916426ea1d10021f3f17ce8031f93c2.css",
"js/app.js": "build/js/app.13630905267b809161e71d0f8a0c017b.js",
@@ -160,11 +157,40 @@ In those cases, use the
use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;
+ // assumes the JSON file above is called "rev-manifest.json"
$package = new Package(new JsonManifestVersionStrategy(__DIR__.'/rev-manifest.json'));
echo $package->getUrl('css/app.css');
// result: build/css/app.b916426ea1d10021f3f17ce8031f93c2.css
+If you request an asset that is *not found* in the ``rev-manifest.json`` file,
+the original - *unmodified* - asset path will be returned. The ``$strictMode``
+argument helps debug issues because it throws an exception when the asset is not
+listed in the manifest::
+
+ use Symfony\Component\Asset\Package;
+ use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;
+
+ // The value of $strictMode can be specific per environment "true" for debugging and "false" for stability.
+ $strictMode = true;
+ // assumes the JSON file above is called "rev-manifest.json"
+ $package = new Package(new JsonManifestVersionStrategy(__DIR__.'/rev-manifest.json', null, $strictMode));
+
+ echo $package->getUrl('not-found.css');
+ // error:
+
+If your JSON file is not on your local filesystem but is accessible over HTTP,
+use the :class:`Symfony\\Component\\Asset\\VersionStrategy\\JsonManifestVersionStrategy`
+with the :doc:`HttpClient component `::
+
+ use Symfony\Component\Asset\Package;
+ use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;
+ use Symfony\Component\HttpClient\HttpClient;
+
+ $httpClient = HttpClient::create();
+ $manifestUrl = 'https://cdn.example.com/rev-manifest.json';
+ $package = new Package(new JsonManifestVersionStrategy($manifestUrl, $httpClient));
+
Custom Version Strategies
.........................
@@ -177,19 +203,19 @@ every day::
class DateVersionStrategy implements VersionStrategyInterface
{
- private $version;
+ private string $version;
public function __construct()
{
$this->version = date('Ymd');
}
- public function getVersion($path)
+ public function getVersion(string $path): string
{
return $this->version;
}
- public function applyVersion($path)
+ public function applyVersion(string $path): string
{
return sprintf('%s?v=%s', $path, $this->getVersion($path));
}
@@ -260,12 +286,12 @@ class to generate absolute URLs for their assets::
// ...
$urlPackage = new UrlPackage(
- 'http://static.example.com/images/',
+ 'https://static.example.com/images/',
new StaticVersionStrategy('v1')
);
echo $urlPackage->getUrl('/logo.png');
- // result: http://static.example.com/images/logo.png?v1
+ // result: https://static.example.com/images/logo.png?v1
You can also pass a schema-agnostic URL::
@@ -292,15 +318,15 @@ constructor::
// ...
$urls = [
- '//static1.example.com/images/',
- '//static2.example.com/images/',
+ 'https://static1.example.com/images/',
+ 'https://static2.example.com/images/',
];
$urlPackage = new UrlPackage($urls, new StaticVersionStrategy('v1'));
echo $urlPackage->getUrl('/logo.png');
- // result: http://static1.example.com/images/logo.png?v1
+ // result: https://static1.example.com/images/logo.png?v1
echo $urlPackage->getUrl('/icon.png');
- // result: http://static2.example.com/images/icon.png?v1
+ // result: https://static2.example.com/images/icon.png?v1
For each asset, one of the URLs will be randomly used. But, the selection
is deterministic, meaning that each asset will always be served by the same
@@ -350,14 +376,14 @@ they all have different base paths::
$defaultPackage = new Package($versionStrategy);
$namedPackages = [
- 'img' => new UrlPackage('http://img.example.com/', $versionStrategy),
+ 'img' => new UrlPackage('https://img.example.com/', $versionStrategy),
'doc' => new PathPackage('/somewhere/deep/for/documents', $versionStrategy),
];
$packages = new Packages($defaultPackage, $namedPackages);
The ``Packages`` class allows to define a default package, which will be applied
-to assets that don't define the name of package to use. In addition, this
+to assets that don't define the name of the package to use. In addition, this
application defines a package named ``img`` to serve images from an external
domain and a ``doc`` package to avoid repeating long paths when linking to a
document inside a template::
@@ -366,7 +392,7 @@ document inside a template::
// result: /main.css?v1
echo $packages->getUrl('/logo.png', 'img');
- // result: http://img.example.com/logo.png?v1
+ // result: https://img.example.com/logo.png?v1
echo $packages->getUrl('resume.pdf', 'doc');
// result: /somewhere/deep/for/documents/resume.pdf?v1
@@ -401,6 +427,6 @@ Learn more
----------
* :doc:`How to manage CSS and JavaScript assets in Symfony applications `
-* :doc:`WebLink component ` to preload assets using HTTP/2.
+* :doc:`WebLink component ` to preload assets using HTTP/2.
.. _`Webpack`: https://webpack.js.org/
diff --git a/components/browser_kit.rst b/components/browser_kit.rst
index 33b5a10ea4b..8cf0772298c 100644
--- a/components/browser_kit.rst
+++ b/components/browser_kit.rst
@@ -1,20 +1,9 @@
-.. index::
- single: BrowserKit
- single: Components; BrowserKit
-
The BrowserKit Component
========================
The BrowserKit component simulates the behavior of a web browser, allowing
you to make requests, click on links and submit forms programmatically.
-.. note::
-
- In Symfony versions prior to 4.3, the BrowserKit component could only make
- internal requests to your application. Starting from Symfony 4.3, this
- component can also :ref:`make HTTP requests to any public site