8000 minor #18044 [2.7] update readme files for new components (xabbuh) · symfony/symfony@c020938 · GitHub
[go: up one dir, main page]
Skip to content

Commit c020938

Browse files
nicolas-grekasnicolas-grekas
committed
minor #18044 [2.7] update readme files for new components (xabbuh)
This PR was merged into the 2.7 branch. Discussion ---------- [2.7] update readme files for new components | Q | A | ------------- | --- | Branch | 2.7 | Bug fix? | no | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #17997 | License | MIT | Doc PR | This completes @javiereguiluz's great work from #17997 by adapting the readme files of components added after the release of Symfony 2.3. Commits ------- 5ba194e [2.7] update readme files for new components
2 parents a89154d + 5ba194e commit c020938

File tree

8 files changed

+54
-300
lines changed

8 files changed

+54
-300
lines changed

‎src/Symfony/Bridge/PhpUnit/README.md

Lines changed: 8 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -3,50 +3,11 @@ PHPUnit Bridge
33

44
Provides utilities for PHPUnit, especially user deprecation notices management.
55

6-
It comes with the following features:
7-
8-
* enforce a consistent `C` locale;
9-
* auto-register `class_exists` to load Doctrine annotations;
10-
* print a user deprecation notices summary at the end of the test suite.
11-
12-
By default any non-legacy-tagged or any non-@-silenced deprecation notices will
13-
make tests fail.
14-
This can be changed by setting the `SYMFONY_DEPRECATIONS_HELPER` environment
15-
variable to `weak`. This will make the bridge ignore deprecation notices and
16-
is useful to projects that must use deprecated interfaces for backward
17-
compatibility reasons.
18-
19-
A summary of deprecation notices is displayed at the end of the test suite:
20-
21-
* **Unsilenced** reports deprecation notices that were triggered without the
22-
recommended @-silencing operator;
23-
* **Legacy** deprecation notices denote tests that explicitly test some legacy
24-
interfaces. There are four ways to mark a test as legacy:
25-
- make its class start with the `Legacy` prefix;
26-
- make its method start with `testLegacy`;
27-
- make its data provider start with `provideLegacy` or `getLegacy`;
28-
- add the `@group legacy` annotation to its class or method.
29-
* **Remaining/Other** deprecation notices are all other (non-legacy)
30-
notices, grouped by message, test class and method.
31-
32-
Usage
33-
-----
34-
35-
Add this bridge to the `require-dev` section of your `composer.json` file
36-
(not in `require`) with e.g. `composer require --dev "symfony/phpunit-bridge"`.
37-
38-
When running `phpunit`, you will see a summary of deprecation notices at the end
39-
of the test suite.
40-
41-
Deprecation notices in the **Unsilenced** section should just be @-silenced:
42-
`@trigger_error('...', E_USER_DEPRECATED);`. Without the @-silencing operator,
43-
users would need to opt-out from deprecation notices. Silencing by default swaps
44-
this behavior and allows users to opt-in when they are ready to cope with them
45-
(by adding a custom error handler like the one provided by this bridge.)
46-
47-
Deprecation notices in the **Remaining/Other** section need some thought.
48-
You have to decide either to:
49-
50-
* update your code to not use deprecated interfaces anymore, thus gaining better
51-
forward compatibility;
52-
* or move them to the **Legacy** section (by using one of the above way).
6+
Resources
7+
---------
8+
9+
* [Documentation](https://symfony.com/doc/current/components/phpunit_bridge.html)
10+
* [Contributing](https://symfony.com/doc/current/contributing/index.html)
11+
* [Report issues](https://github.com/symfony/symfony/issues) and
12+
[send Pull Requests](https://github.com/symfony/symfony/pulls)
13+
in the [main Symfony repository](https://github.com/symfony/symfony)

‎src/Symfony/Component/Asset/README.md

Lines changed: 7 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,14 @@
11
Asset Component
22
===============
33

4-
The Asset component manages asset URLs.
5-
6-
Versioned Asset URLs
7-
--------------------
8-
9-
The basic `Package` adds a version to generated asset URLs:
10-
11-
```php
12-
use Symfony\Component\Asset\Package;
13-
use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy;
14-
15-
$package = new Package(new StaticVersionStrategy('v1'));
16-
17-
echo $package->getUrl('/me.png');
18-
// /me.png?v1
19-
```
20-
21-
The default format can be configured:
22-
23-
```php
24-
$package = new Package(new StaticVersionStrategy('v1', '%s?version=%s'));
25-
26-
echo $package->getUrl('/me.png');
27-
// /me.png?version=v1
28-
29-
// put the version before the path
30-
$package = new Package(new StaticVersionStrategy('v1', 'version-%2$s/%1$s'));
31-
32-
echo $package->getUrl('/me.png');
33-
// /version-v1/me.png
34-
```
35-
36-
Asset URLs Base Path
37-
--------------------
38-
39-
When all assets are stored in a common path, use the `PathPackage` to avoid
40-
repeating yourself:
41-
42-
```php
43-
use Symfony\Component\Asset\PathPackage;
44-
45-
$package = new PathPackage('/images', new StaticVersionStrategy('v1'));
46-
47-
echo $package->getUrl('/me.png');
48-
// /images/me.png?v1
49-
```
50-
51-
Asset URLs Base URLs
52-
--------------------
53-
54-
If your assets are hosted on different domain name than the main website, use
55-
the `UrlPackage` class:
56-
57-
```php
58-
use Symfony\Component\Asset\UrlPackage;
59-
60-
$package = new UrlPackage('http://assets.example.com/images/', new StaticVersionStrategy('v1'));
61-
62-
echo $package->getUrl('/me.png');
63-
// http://assets.example.com/images/me.png?v1
64-
```
65-
66-
One technique used to speed up page rendering in browsers is to use several
67-
domains for assets; this is possible by passing more than one base URLs:
68-
69-
```php
70-
use Symfony\Component\Asset\UrlPackage;
71-
72-
$urls = array(
73-
'http://a1.example.com/images/',
74-
'http://a2.example.com/images/',
75-
);
76-
$package = new UrlPackage($urls, new StaticVersionStrategy('v1'));
77-
78-
echo $package->getUrl('/me.png');
79-
// http://a1.example.com/images/me.png?v1
80-
```
81-
82-
Note that it's also guaranteed that any given path will always use the same
83-
base URL to be nice with HTTP caching mechanisms.
84-
85-
HttpFoundation Integration
86-
--------------------------
87-
88-
If you are using HttpFoundation for your project, set the Context to get
89-
additional features for free:
90-
91-
```php
92-
use Symfony\Component\Asset\PathPackage;
93-
use Symfony\Component\Asset\Context\RequestStackContext;
94-
95-
$package = new PathPackage('images', new StaticVersionStrategy('v1'));
96-
$package->setContext(new RequestStackContext($requestStack));
97-
98-
echo $package->getUrl('/me.png');
99-
// /somewhere/images/me.png?v1
100-
```
101-
102-
In addition to the configured base path, `PathPackage` now also automatically
103-
prepends the current request base URL to assets to allow your website to be
104-
hosted anywhere under the web server root directory.
105-
106-
```php
107-
use Symfony\Component\Asset\UrlPackage;
108-
use Symfony\Component\Asset\Context\RequestStackContext;
109-
110-
$package = new UrlPackage(array('http://example.com/', 'https://example.com/'), new StaticVersionStrategy('v1'));
111-
$package->setContext(new RequestStackContext($requestStack));
112-
113-
echo $package->getUrl('/me.png');
114-
// https://example.com/images/me.png?v1
115-
```
116-
117-
`UrlPackage` now uses the current request scheme (HTTP or HTTPs) to select an
118-
appropriate base URL (HTTPs or protocol-relative URLs for HTTPs requests, any
119-
base URL for HTTP requests).
120-
121-
Named Packages
122-
--------------
123-
124-
The `Packages` class allows to easily manages several packages in a single
125-
project by naming packages:
126-
127-
```php
128-
use Symfony\Component\Asset\Package;
129-
use Symfony\Component\Asset\PathPackage;
130-
use Symfony\Component\Asset\UrlPackage;
131-
use Symfony\Component\Asset\Packages;
132-
133-
// by default, just add a version to all assets
134-
$versionStrategy = new StaticVersionStrategy('v1');
135-
$defaultPackage = new Asset\Package($versionStrategy);
136-
137-
$namedPackages = array(
138-
// images are hosted on another web server
139-
'img' => new Asset\UrlPackage('http://img.example.com/', $versionStrategy),
140-
141-
// documents are stored deeply under the web root directory
142-
// let's create a shortcut
143-
'doc' => new Asset\PathPackage('/somewhere/deep/for/documents', $versionStrategy),
144-
);
145-
146-
// bundle all packages to make it easy to use them
147-
$packages = new Asset\Packages($defaultPackage, $namedPackages);
148-
149-
echo $packages->getUrl('/some.css');
150-
// /some.css?v1
151-
152-
echo $packages->getUrl('/me.png', 'img');
153-
// http://img.example.com/me.png?v1
154-
155-
echo $packages->getUrl('/me.pdf', 'doc');
156-
// /somewhere/deep/for/documents/me.pdf?v1
157-
```
4+
The Asset component manages URL generation and versioning of web assets such as
5+
CSS stylesheets, JavaScript files and image files.
1586

1597
Resources
1608
---------
1619

162-
You can run the unit tests with the following command:
163-
164-
$ cd path/to/Symfony/Component/Asset/
165-
$ composer update
166-
$ phpunit
10+
* [Documentation](https://symfony.com/doc/current/components/asset/introduction.html)
11+
* [Contributing](https://symfony.com/doc/current/contributing/index.html)
12+
* [Report issues](https://github.com/symfony/symfony/issues) and
13+
[send Pull Requests](https://github.com/symfony/symfony/pulls)
14+
in the [main Symfony repository](https://github.com/symfony/symfony)

‎src/Symfony/Component/ExpressionLanguage/README.md

Lines changed: 7 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2,42 +2,14 @@ ExpressionLanguage Component
22
============================
33

44
The ExpressionLanguage component provides an engine that can compile and
5-
evaluate expressions:
6-
7-
use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
8-
9-
$language = new ExpressionLanguage();
10-
11-
echo $language->evaluate('1 + foo', array('foo' => 2));
12-
// would output 3
13-
14-
echo $language->compile('1 + foo', array('foo'));
15-
// would output (1 + $foo)
16-
17-
By default, the engine implements simple math and logic functions, method
18-
calls, property accesses, and array accesses.
19-
20-
You can extend your DSL with functions:
21-
22-
$compiler = function ($arg) {
23-
return sprintf('strtoupper(%s)', $arg);
24-
};
25-
$evaluator = function (array $variables, $value) {
26-
return strtoupper($value);
27-
};
28-
$language->register('upper', $compiler, $evaluator);
29-
30-
echo $language->evaluate('"foo" ~ upper(foo)', array('foo' => 'bar'));
31-
// would output fooBAR
32-
33-
echo $language->compile('"foo" ~ upper(foo)');
34-
// would output ("foo" . strtoupper($foo))
5+
evaluate expressions. An expression is a one-liner that returns a value
6+
(mostly, but not limited to, Booleans).
357

368
Resources
379
---------
3810

39-
You can run the unit tests with the following command:
40-
41-
$ cd path/to/Symfony/Component/ExpressionLanguage/
42-
$ composer.phar install --dev
43-
$ phpunit
11+
* [Documentation](https://symfony.com/doc/current/components/expression_language/introduction.html)
12+
* [Contributing](https://symfony.com/doc/current/contributing/index.html)
13+
* [Report issues](https://github.com/symfony/symfony/issues) and
14+
[send Pull Requests](https://github.com/symfony/symfony/pulls)
15+
in the [main Symfony repository](https://github.com/symfony/symfony)

‎src/Symfony/Component/Security/Acl/README.md

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,8 @@ the Java Spring framework.
99
Resources
1010
---------
1111

12-
Documentation:
13-
14-
https://symfony.com/doc/2.7/book/security.html
15-
16-
Tests
17-
-----
18-
19-
You can run the unit tests with the following command:
20-
21-
$ cd path/to/Symfony/Component/Security/Acl/
22-
$ composer.phar install --dev
23-
$ phpunit
12+
* [Documentation](https://symfony.com/doc/current/components/security/index.html)
13+
* [Contributing](https://symfony.com/doc/current/contributing/index.html)
14+
* [Report issues](https://github.com/symfony/symfony/issues) and
15+
[send Pull Requests](https://github.com/symfony/symfony/pulls)
16+
in the [main Symfony repository](https://github.com/symfony/symfony)

‎src/Symfony/Component/Security/Core/README.md

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,8 @@ the Java Spring framework.
99
Resources
1010
---------
1111

12-
Documentation:
13-
14-
https://symfony.com/doc/2.7/book/security.html
15-
16-
Tests
17-
-----
18-
19-
You can run the unit tests with the following command:
20-
21-
$ cd path/to/Symfony/Component/Security/Core/
22-
$ composer.phar install --dev
23-
$ phpunit
12+
* [Documentation](https://symfony.com/doc/current/components/security/index.html)
13+
* [Contributing](https://symfony.com/doc/current/contributing/index.html)
14+
* [Report issues](https://github.com/symfony/symfony/issues) and
15+
[send Pull Requests](https://github.com/symfony/symfony/pulls)
16+
in the [main Symfony repository](https://github.com/symfony/symfony)

‎src/Symfony/Component/Security/Csrf/README.md

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,8 @@ The Security CSRF (cross-site request forgery) component provides a class
77
Resources
88
---------
99

10-
Documentation:
11-
12-
https://symfony.com/doc/2.7/book/security.html
13-
14-
Tests
15-
-----
16-
17-
You can run the unit tests with the following command:
18-
19-
$ cd path/to/Symfony/Component/Security/Csrf/
20-
$ composer.phar install --dev
21-
$ phpunit
10+
* [Documentation](https://symfony.com/doc/current/components/security/index.html)
11+
* [Contributing](https://symfony.com/doc/current/contributing/index.html)
12+
* [Report issues](https://github.com/symfony/symfony/issues) and
13+
[send Pull Requests](https://github.com/symfony/symfony/pulls)
14+
in the [main Symfony repository](https://github.com/symfony/symfony)

‎src/Symfony/Component/Security/Http/README.md

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,8 @@ the Java Spring framework.
99
Resources
1010
---------
1111

12-
Documentation:
13-
14-
https://symfony.com/doc/2.7/book/security.html
15-
16-
Tests
17-
-----
18-
19-
You can run the unit tests with the following command:
20-
21-
$ cd path/to/Symfony/Component/Security/Http/
22-
$ composer.phar install --dev
23-
$ phpunit
12+
* [Documentation](https://symfony.com/doc/current/components/security/index.html)
13+
* [Contributing](https://symfony.com/doc/current/contributing/index.html)
14+
* [Report issues](https://github.com/symfony/symfony/issues) and
15+
[send Pull Requests](https://github.com/symfony/symfony/pulls)
16+
in the [main Symfony repository](https://github.com/symfony/symfony)

‎src/Symfony/Component/VarDumper/README.md

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
1-
Symfony mechanism for exploring and dumping PHP variables
2-
=========================================================
1+
VarDumper Component
2+
===================
33

4-
This component provides a mechanism that allows exploring then dumping
5-
any PHP variable.
4+
The VarDumper component provides mechanisms for walking through any arbitrary
5+
PHP variable. Built on top, it provides a better `dump()`` function that you
6+
can use instead of `var_dump`.
67

7-
It handles scalars, objects and resources properly, taking hard and soft
8-
references into account. More than being immune to infinite recursion
9-
problems, it allows dumping where references link to each other.
10-
It explores recursive structures using a breadth-first algorithm.
8+
Resources
9+
---------
1110

12-
The component exposes all the parts involved in the different steps of
13-
cloning then dumping a PHP variable, while applying size limits and having
14-
specialized output formats and methods.
11+
* [Documentation](https://symfony.com/doc/current/components/var_dumper/introduction.html)
12+
* [Contributing](https://symfony.com/doc/current/contributing/index.html)
13+
* [Report issues](https://github.com/symfony/symfony/issues) and
14+
[send Pull Requests](https://github.com/symfony/symfony/pulls)
15+
in the [main Symfony repository](https://github.com/symfony/symfony)

0 commit comments

Comments
 (0)
0