From 5ba194ec52bf1b4999cddac2e15e2b4d13f9903d Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Mon, 7 Mar 2016 11:18:03 +0100 Subject: [PATCH] [2.7] update readme files for new components --- src/Symfony/Bridge/PhpUnit/README.md | 53 +----- src/Symfony/Component/Asset/README.md | 166 +----------------- .../Component/ExpressionLanguage/README.md | 42 +---- src/Symfony/Component/Security/Acl/README.md | 17 +- src/Symfony/Component/Security/Core/README.md | 17 +- src/Symfony/Component/Security/Csrf/README.md | 17 +- src/Symfony/Component/Security/Http/README.md | 17 +- src/Symfony/Component/VarDumper/README.md | 23 +-- 8 files changed, 53 insertions(+), 299 deletions(-) diff --git a/src/Symfony/Bridge/PhpUnit/README.md b/src/Symfony/Bridge/PhpUnit/README.md index c36f9b5335..8c4e6e59cc 100644 --- a/src/Symfony/Bridge/PhpUnit/README.md +++ b/src/Symfony/Bridge/PhpUnit/README.md @@ -3,50 +3,11 @@ PHPUnit Bridge Provides utilities for PHPUnit, especially user deprecation notices management. -It comes with the following features: +Resources +--------- - * enforce a consistent `C` locale; - * auto-register `class_exists` to load Doctrine annotations; - * print a user deprecation notices summary at the end of the test suite. - -By default any non-legacy-tagged or any non-@-silenced deprecation notices will -make tests fail. -This can be changed by setting the `SYMFONY_DEPRECATIONS_HELPER` environment -variable to `weak`. This will make the bridge ignore deprecation notices and -is useful to projects that must use deprecated interfaces for backward -compatibility reasons. - -A summary of deprecation notices is displayed at the end of the test suite: - - * **Unsilenced** reports deprecation notices that were triggered without the - recommended @-silencing operator; - * **Legacy** deprecation notices denote tests that explicitly test some legacy - interfaces. There are four ways to mark a test as legacy: - - make its class start with the `Legacy` prefix; - - make its method start with `testLegacy`; - - make its data provider start with `provideLegacy` or `getLegacy`; - - add the `@group legacy` annotation to its class or method. - * **Remaining/Other** deprecation notices are all other (non-legacy) - notices, grouped by message, test class and method. - -Usage ------ - -Add this bridge to the `require-dev` section of your `composer.json` file -(not in `require`) with e.g. `composer require --dev "symfony/phpunit-bridge"`. - -When running `phpunit`, you will see a summary of deprecation notices at the end -of the test suite. - -Deprecation notices in the **Unsilenced** section should just be @-silenced: -`@trigger_error('...', E_USER_DEPRECATED);`. Without the @-silencing operator, -users would need to opt-out from deprecation notices. Silencing by default swaps -this behavior and allows users to opt-in when they are ready to cope with them -(by adding a custom error handler like the one provided by this bridge.) - -Deprecation notices in the **Remaining/Other** section need some thought. -You have to decide either to: - - * update your code to not use deprecated interfaces anymore, thus gaining better - forward compatibility; - * or move them to the **Legacy** section (by using one of the above way). + * [Documentation](https://symfony.com/doc/current/components/phpunit_bridge.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) diff --git a/src/Symfony/Component/Asset/README.md b/src/Symfony/Component/Asset/README.md index f2e66b832e..3291698493 100644 --- a/src/Symfony/Component/Asset/README.md +++ b/src/Symfony/Component/Asset/README.md @@ -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) diff --git a/src/Symfony/Component/ExpressionLanguage/README.md b/src/Symfony/Component/ExpressionLanguage/README.md index 734e889a7f..08b310d10b 100644 --- a/src/Symfony/Component/ExpressionLanguage/README.md +++ b/src/Symfony/Component/ExpressionLanguage/README.md @@ -2,42 +2,14 @@ ExpressionLanguage Component ============================ The ExpressionLanguage component provides an engine that can compile and -evaluate expressions: - - use Symfony\Component\ExpressionLanguage\ExpressionLanguage; - - $language = new ExpressionLanguage(); - - echo $language->evaluate('1 + foo', array('foo' => 2)); - // would output 3 - - echo $language->compile('1 + foo', array('foo')); - // would output (1 + $foo) - -By default, the engine implements simple math and logic functions, method -calls, property accesses, and array accesses. - -You can extend your DSL with functions: - - $compiler = function ($arg) { - return sprintf('strtoupper(%s)', $arg); - }; - $evaluator = function (array $variables, $value) { - return strtoupper($value); - }; - $language->register('upper', $compiler, $evaluator); - - echo $language->evaluate('"foo" ~ upper(foo)', array('foo' => 'bar')); - // would output fooBAR - - echo $language->compile('"foo" ~ upper(foo)'); - // would output ("foo" . strtoupper($foo)) +evaluate expressions. An expression is a one-liner that returns a value +(mostly, but not limited to, Booleans). Resources --------- -You can run the unit tests with the following command: - - $ cd path/to/Symfony/Component/ExpressionLanguage/ - $ composer.phar install --dev - $ phpunit + * [Documentation](https://symfony.com/doc/current/components/expression_language/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) diff --git a/src/Symfony/Component/Security/Acl/README.md b/src/Symfony/Component/Security/Acl/README.md index bff22093aa..a6048fdb75 100644 --- a/src/Symfony/Component/Security/Acl/README.md +++ b/src/Symfony/Component/Security/Acl/README.md @@ -9,15 +9,8 @@ the Java Spring framework. Resources --------- -Documentation: - -https://symfony.com/doc/2.7/book/security.html - -Tests ------ - -You can run the unit tests with the following command: - - $ cd path/to/Symfony/Component/Security/Acl/ - $ composer.phar install --dev - $ phpunit + * [Documentation](https://symfony.com/doc/current/components/security/index.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) diff --git a/src/Symfony/Component/Security/Core/README.md b/src/Symfony/Component/Security/Core/README.md index b0d1749497..ede185bd3b 100644 --- a/src/Symfony/Component/Security/Core/README.md +++ b/src/Symfony/Component/Security/Core/README.md @@ -9,15 +9,8 @@ the Java Spring framework. Resources --------- -Documentation: - -https://symfony.com/doc/2.7/book/security.html - -Tests ------ - -You can run the unit tests with the following command: - - $ cd path/to/Symfony/Component/Security/Core/ - $ composer.phar install --dev - $ phpunit + * [Documentation](https://symfony.com/doc/current/components/security/index.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) diff --git a/src/Symfony/Component/Security/Csrf/README.md b/src/Symfony/Component/Security/Csrf/README.md index 3ae550b4cc..aff72a0c32 100644 --- a/src/Symfony/Component/Security/Csrf/README.md +++ b/src/Symfony/Component/Security/Csrf/README.md @@ -7,15 +7,8 @@ The Security CSRF (cross-site request forgery) component provides a class Resources --------- -Documentation: - -https://symfony.com/doc/2.7/book/security.html - -Tests ------ - -You can run the unit tests with the following command: - - $ cd path/to/Symfony/Component/Security/Csrf/ - $ composer.phar install --dev - $ phpunit + * [Documentation](https://symfony.com/doc/current/components/security/index.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) diff --git a/src/Symfony/Component/Security/Http/README.md b/src/Symfony/Component/Security/Http/README.md index 7619bfcb9c..5be2111830 100644 --- a/src/Symfony/Component/Security/Http/README.md +++ b/src/Symfony/Component/Security/Http/README.md @@ -9,15 +9,8 @@ the Java Spring framework. Resources --------- -Documentation: - -https://symfony.com/doc/2.7/book/security.html - -Tests ------ - -You can run the unit tests with the following command: - - $ cd path/to/Symfony/Component/Security/Http/ - $ composer.phar install --dev - $ phpunit + * [Documentation](https://symfony.com/doc/current/components/security/index.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) diff --git a/src/Symfony/Component/VarDumper/README.md b/src/Symfony/Component/VarDumper/README.md index 71bff335a7..78ba1b29e8 100644 --- a/src/Symfony/Component/VarDumper/README.md +++ b/src/Symfony/Component/VarDumper/README.md @@ -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)