-
-
Notifications
You must be signed in to change notification settings - Fork 9.7k
[2.7] update readme files for new components #18044
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,166 +1,14 @@ | ||
| Asset Component | ||
| =============== | ||
|
|
||
| The Asset component manages asset URLs. | ||
|
|
||
| Versioned Asset URLs | ||
| -------------------- | ||
|
|
||
| The basic `Package` adds a version to generated asset URLs: | ||
|
|
||
| ```php | ||
| use Symfony\Component\Asset\Package; | ||
| use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy; | ||
|
|
||
| $package = new Package(new StaticVersionStrategy('v1')); | ||
|
|
||
| echo $package->getUrl('/me.png'); | ||
| // /me.png?v1 | ||
| ``` | ||
|
|
||
| The default format can be configured: | ||
|
|
||
| ```php | ||
| $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s')); | ||
|
|
||
| echo $package->getUrl('/me.png'); | ||
| // /me.png?version=v1 | ||
|
|
||
| // put the version before the path | ||
| $package = new Package(new StaticVersionStrategy('v1', 'version-%2$s/%1$s')); | ||
|
|
||
| echo $package->getUrl('/me.png'); | ||
| // /version-v1/me.png | ||
| ``` | ||
|
|
||
| Asset URLs Base Path | ||
| -------------------- | ||
|
|
||
| When all assets are stored in a common path, use the `PathPackage` to avoid | ||
| repeating yourself: | ||
|
|
||
| ```php | ||
| use Symfony\Component\Asset\PathPackage; | ||
|
|
||
| $package = new PathPackage('/images', new StaticVersionStrategy('v1')); | ||
|
|
||
| echo $package->getUrl('/me.png'); | ||
| // /images/me.png?v1 | ||
| ``` | ||
|
|
||
| Asset URLs Base URLs | ||
| -------------------- | ||
|
|
||
| If your assets are hosted on different domain name than the main website, use | ||
| the `UrlPackage` class: | ||
|
|
||
| ```php | ||
| use Symfony\Component\Asset\UrlPackage; | ||
|
|
||
| $package = new UrlPackage('http://assets.example.com/images/', new StaticVersionStrategy('v1')); | ||
|
|
||
| echo $package->getUrl('/me.png'); | ||
| // http://assets.example.com/images/me.png?v1 | ||
| ``` | ||
|
|
||
| One technique used to speed up page rendering in browsers is to use several | ||
| domains for assets; this is possible by passing more than one base URLs: | ||
|
|
||
| ```php | ||
| use Symfony\Component\Asset\UrlPackage; | ||
|
|
||
| $urls = array( | ||
| 'http://a1.example.com/images/', | ||
| 'http://a2.example.com/images/', | ||
| ); | ||
| $package = new UrlPackage($urls, new StaticVersionStrategy('v1')); | ||
|
|
||
| echo $package->getUrl('/me.png'); | ||
| // http://a1.example.com/images/me.png?v1 | ||
| ``` | ||
|
|
||
| Note that it's also guaranteed that any given path will always use the same | ||
| base URL to be nice with HTTP caching mechanisms. | ||
|
|
||
| HttpFoundation Integration | ||
| -------------------------- | ||
|
|
||
| If you are using HttpFoundation for your project, set the Context to get | ||
| additional features for free: | ||
|
|
||
| ```php | ||
| use Symfony\Component\Asset\PathPackage; | ||
| use Symfony\Component\Asset\Context\RequestStackContext; | ||
|
|
||
| $package = new PathPackage('images', new StaticVersionStrategy('v1')); | ||
| $package->setContext(new RequestStackContext($requestStack)); | ||
|
|
||
| echo $package->getUrl('/me.png'); | ||
| // /somewhere/images/me.png?v1 | ||
| ``` | ||
|
|
||
| In addition to the configured base path, `PathPackage` now also automatically | ||
| prepends the current request base URL to assets to allow your website to be | ||
| hosted anywhere under the web server root directory. | ||
|
|
||
| ```php | ||
| use Symfony\Component\Asset\UrlPackage; | ||
| use Symfony\Component\Asset\Context\RequestStackContext; | ||
|
|
||
| $package = new UrlPackage(array('http://example.com/', 'https://example.com/'), new StaticVersionStrategy('v1')); | ||
| $package->setContext(new RequestStackContext($requestStack)); | ||
|
|
||
| echo $package->getUrl('/me.png'); | ||
| // https://example.com/images/me.png?v1 | ||
| ``` | ||
|
|
||
| `UrlPackage` now uses the current request scheme (HTTP or HTTPs) to select an | ||
| appropriate base URL (HTTPs or protocol-relative URLs for HTTPs requests, any | ||
| base URL for HTTP requests). | ||
|
|
||
| Named Packages | ||
| -------------- | ||
|
|
||
| The `Packages` class allows to easily manages several packages in a single | ||
| project by naming packages: | ||
|
|
||
| ```php | ||
| use Symfony\Component\Asset\Package; | ||
| use Symfony\Component\Asset\PathPackage; | ||
| use Symfony\Component\Asset\UrlPackage; | ||
| use Symfony\Component\Asset\Packages; | ||
|
|
||
| // by default, just add a version to all assets | ||
| $versionStrategy = new StaticVersionStrategy('v1'); | ||
| $defaultPackage = new Asset\Package($versionStrategy); | ||
|
|
||
| $namedPackages = array( | ||
| // images are hosted on another web server | ||
| 'img' => new Asset\UrlPackage('http://img.example.com/', $versionStrategy), | ||
|
|
||
| // documents are stored deeply under the web root directory | ||
| // let's create a shortcut | ||
| 'doc' => new Asset\PathPackage('/somewhere/deep/for/documents', $versionStrategy), | ||
| ); | ||
|
|
||
| // bundle all packages to make it easy to use them | ||
| $packages = new Asset\Packages($defaultPackage, $namedPackages); | ||
|
|
||
| echo $packages->getUrl('/some.css'); | ||
| // /some.css?v1 | ||
|
|
||
| echo $packages->getUrl('/me.png', 'img'); | ||
| // http://img.example.com/me.png?v1 | ||
|
|
||
| echo $packages->getUrl('/me.pdf', 'doc'); | ||
| // /somewhere/deep/for/documents/me.pdf?v1 | ||
| ``` | ||
| The Asset component manages URL generation and versioning of web assets such as | ||
| CSS stylesheets, JavaScript files and image files. | ||
|
|
||
| Resources | ||
| --------- | ||
|
|
||
| You can run the unit tests with the following command: | ||
|
|
||
| $ cd path/to/Symfony/Component/Asset/ | ||
| $ composer update | ||
| $ phpunit | ||
| * [Documentation](https://symfony.com/doc/current/components/asset/introduction.html) | ||
| * [Contributing](https://symfony.com/doc/current/contributing/index.html) | ||
| * [Report issues](https://github.com/symfony/symfony/issues) and | ||
| [send Pull Requests](https://github.com/symfony/symfony/pulls) | ||
| in the [main Symfony repository](https://github.com/symfony/symfony) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,14 +1,15 @@ | ||
| Symfony mechanism for exploring and dumping PHP variables | ||
| ========================================================= | ||
| VarDumper Component | ||
| =================== | ||
|
|
||
| This component provides a mechanism that allows exploring then dumping | ||
| any PHP variable. | ||
| The VarDumper component provides mechanisms for walking through any arbitrary | ||
| PHP variable. Built on top, it provides a better `dump()`` function that you | ||
| can use instead of `var_dump`. | ||
|
|
||
| It handles scalars, objects and resources properly, taking hard and soft | ||
| references into account. More than being immune to infinite recursion | ||
| problems, it allows dumping where references link to each other. | ||
| It explores recursive structures using a breadth-first algorithm. | ||
| Resources | ||
| --------- | ||
|
|
||
| The component exposes all the parts involved in the different steps of | ||
| cloning then dumping a PHP variable, while applying size limits and having | ||
| specialized output formats and methods. | ||
| * [Documentation](https://symfony.com/doc/current/components/var_dumper/introduction.html) | ||
| * [Contributing](https://symfony.com/doc/current/contributing/index.html) | ||
| * [Report issues](https://github.com/symfony/symfony/issues) and | ||
| [send Pull Requests](https://github.com/symfony/symfony/pulls) | ||
| in the [main Symfony repository](https://github.com/symfony/symfony) |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Booleans and scalars?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I reused the introduction from the documentation: http://symfony.com/doc/current/components/expression_language/introduction.html
I think if we want to improve this (which doesn't seem to be the worst idea), we should make the change there first.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree with @xabbuh. Let's copy the current description to move forward fast and let's improve it in the future.