diff --git a/best_practices/templates.rst b/best_practices/templates.rst index 01a4b80e80b..5daf929713a 100644 --- a/best_practices/templates.rst +++ b/best_practices/templates.rst @@ -9,7 +9,7 @@ languages - like `Twig`_ - were created to make templating even better. Use Twig templating format for your templates. -Generally speaking, PHP templates are much more verbose than in Twig because +Generally speaking, PHP templates are much more verbose than Twig templates because they lack native support for lots of modern features needed by templates, like inheritance, automatic escaping and named arguments for filters and functions. diff --git a/book/doctrine.rst b/book/doctrine.rst index 82e22ba1386..0f3f62086d0 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -119,7 +119,7 @@ for you: .. sidebar:: Setting up the Database to be UTF8 One mistake even seasoned developers make when starting a Symfony project - is forgetting to setup default charset and collation on their database, + is forgetting to set up default charset and collation on their database, ending up with latin type collations, which are default for most databases. They might even remember to do it the very first time, but forget that it's all gone after running a relatively common command during development: @@ -339,7 +339,7 @@ see the :ref:`book-doctrine-field-types` section. You can also check out Doctrine's `Basic Mapping Documentation`_ for all details about mapping information. If you use annotations, you'll - need to prepend all annotations with ``ORM\`` (e.g. ``ORM\Column(..)``), + need to prepend all annotations with ``ORM\`` (e.g. ``ORM\Column(...)``), which is not shown in Doctrine's documentation. You'll also need to include the ``use Doctrine\ORM\Mapping as ORM;`` statement, which *imports* the ``ORM`` annotations prefix. @@ -357,7 +357,7 @@ see the :ref:`book-doctrine-field-types` section. .. note:: - When using another library or program (ie. Doxygen) that uses annotations, + When using another library or program (e.g. Doxygen) that uses annotations, you should place the ``@IgnoreAnnotation`` annotation on the class to indicate which annotations Symfony should ignore. @@ -385,7 +385,7 @@ a regular PHP class, you need to create getter and setter methods (e.g. ``getNam $ php app/console doctrine:generate:entities AppBundle/Entity/Product -This command makes sure that all of the getters and setters are generated +This command makes sure that all the getters and setters are generated for the ``Product`` class. This is a safe command - you can run it over and over again: it only generates getters and setters that don't exist (i.e. it doesn't replace your existing methods). @@ -432,7 +432,7 @@ mapping information) of a bundle or an entire namespace: .. note:: Doctrine doesn't care whether your properties are ``protected`` or ``private``, - or whether or not you have a getter or setter function for a property. + or whether you have a getter or setter function for a property. The getters and setters are generated here only because you'll need them to interact with your PHP object. @@ -770,7 +770,7 @@ already did in the previous section). The DQL syntax is incredibly powerful, allowing you to easily join between entities (the topic of :ref:`relations ` will be -covered later), group, etc. For more information, see the official Doctrine +covered later), group, etc. For more information, see the official `Doctrine Query Language`_ documentation. Custom Repository Classes @@ -833,7 +833,7 @@ used earlier to generate the missing getter and setter methods: $ php app/console doctrine:generate:entities AppBundle Next, add a new method - ``findAllOrderedByName()`` - to the newly generated -repository class. This method will query for all of the ``Product`` entities, +repository class. This method will query for all the ``Product`` entities, ordered alphabetically. .. code-block:: php @@ -1352,7 +1352,7 @@ Doctrine's `Lifecycle Events documentation`_. transforming data in the entity (e.g. setting a created/updated field, generating a slug value). - If you need to do some heavier lifting - like perform logging or send + If you need to do some heavier lifting - like performing logging or sending an email - you should register an external class as an event listener or subscriber and give it access to whatever resources you need. For more information, see :doc:`/cookbook/doctrine/event_listeners_subscribers`. @@ -1362,7 +1362,7 @@ Doctrine's `Lifecycle Events documentation`_. Doctrine Field Types Reference ------------------------------ -Doctrine comes with a large number of field types available. Each of these +Doctrine comes with numerous field types available. Each of these maps a PHP data type to a specific column type in whatever database you're using. For each field type, the ``Column`` can be configured further, setting the ``length``, ``nullable`` behavior, ``name`` and other options. To see a diff --git a/book/forms.rst b/book/forms.rst index af87a2acb65..a126b5e70e5 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -172,7 +172,7 @@ That's it! Just three lines are needed to render the complete form: when using file uploads. ``form_widget(form)`` - Renders all of the fields, which includes the field element itself, a label + Renders all the fields, which includes the field element itself, a label and any validation error messages for the field. ``form_end()`` diff --git a/book/from_flat_php_to_symfony2.rst b/book/from_flat_php_to_symfony2.rst index a8e10eb6f04..e84ae383264 100644 --- a/book/from_flat_php_to_symfony2.rst +++ b/book/from_flat_php_to_symfony2.rst @@ -126,7 +126,7 @@ is primarily an HTML file that uses a template-like PHP syntax: -By convention, the file that contains all of the application logic - ``index.php`` - +By convention, the file that contains all the application logic - ``index.php`` - is known as a "controller". The term :term:`controller` is a word you'll hear a lot, regardless of the language or framework you use. It refers simply to the area of *your* code that processes user input and prepares the response. @@ -244,8 +244,8 @@ the layout: -You've now introduced a methodology that allows for the reuse of the -layout. Unfortunately, to accomplish this, you're forced to use a few ugly +You now have a setup that will allow you to reuse the layout. +Unfortunately, to accomplish this, you're forced to use a few ugly PHP functions (``ob_start()``, ``ob_get_clean()``) in the template. Symfony uses a Templating component that allows this to be accomplished cleanly and easily. You'll see it in action shortly. @@ -447,7 +447,7 @@ into a vendor/ directory: .. code-block:: bash - $ php composer.phar install + $ composer install Beside downloading your dependencies, Composer generates a ``vendor/autoload.php`` file, which takes care of autoloading for all the files in the Symfony Framework as well as diff --git a/book/http_cache.rst b/book/http_cache.rst index e71b3babb0f..febe7400f78 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -236,7 +236,7 @@ Here is a list of the main options: (default: ``60``). This setting is overridden by the ``stale-if-error`` HTTP ``Cache-Control`` extension (see RFC 5861). -If ``debug`` is ``true``, Symfony automatically adds a ``X-Symfony-Cache`` +If ``debug`` is ``true``, Symfony automatically adds an ``X-Symfony-Cache`` header to the response containing useful information about cache hits and misses. @@ -427,7 +427,7 @@ on a cache to store and return "fresh" responses. model of the specification dominates your work. Unfortunately, the actual specification document - `RFC 2616`_ - can be difficult to read. - There is an on-going effort (`HTTP Bis`_) to rewrite the RFC 2616. It does + There is an ongoing effort (`HTTP Bis`_) to rewrite the RFC 2616. It does not describe a new version of HTTP, but mostly clarifies the original HTTP specification. The organization is also improved as the specification is split into seven parts; everything related to HTTP caching can be @@ -482,7 +482,7 @@ The resulting HTTP header will look like this: timezone as required by the specification. Note that in HTTP versions before 1.1 the origin server wasn't required to -send the ``Date`` header. Consequently the cache (e.g. the browser) might +send the ``Date`` header. Consequently, the cache (e.g. the browser) might need to rely on the local clock to evaluate the ``Expires`` header making the lifetime calculation vulnerable to clock skew. Another limitation of the ``Expires`` header is that the specification states that "HTTP/1.1 @@ -528,9 +528,9 @@ won't be asked to return the updated response until the cache finally becomes stale. The validation model addresses this issue. Under this model, the cache continues -to store responses. The difference is that, for each request, the cache asks -the application whether or not the cached response is still valid. If the -cache *is* still valid, your application should return a 304 status code +to store responses. The difference is that, for each request, the cache asks the +application if the cached response is still valid or if it needs to be regenerated. +If the cache *is* still valid, your application should return a 304 status code and no content. This tells the cache that it's ok to return the cached response. Under this model, you only save CPU if you're able to determine that the diff --git a/book/http_fundamentals.rst b/book/http_fundamentals.rst index 53f30470e9c..dcb0f8a2145 100644 --- a/book/http_fundamentals.rst +++ b/book/http_fundamentals.rst @@ -38,7 +38,7 @@ how you develop on the web, the goal of your server is *always* to understand simple text requests, and return simple text responses. Symfony is built from the ground up around that reality. Whether you realize -it or not, HTTP is something you use everyday. With Symfony, you'll learn +it or not, HTTP is something you use every day. With Symfony, you'll learn how to master it. .. index:: @@ -545,7 +545,7 @@ regardless of how your project is developed. To name a few: :doc:`Translation ` A framework for translating strings in your application. -Each and every one of these components is decoupled and can be used in *any* +Each one of these components is decoupled and can be used in *any* PHP project, regardless of whether or not you use the Symfony framework. Every part is made to be used if needed and replaced when necessary. diff --git a/book/installation.rst b/book/installation.rst index f065473ec3f..4b3fa4b2f69 100644 --- a/book/installation.rst +++ b/book/installation.rst @@ -117,16 +117,7 @@ don't have installed it globally, start by reading the next section. Installing Composer Globally ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -On Linux and Mac OS X, execute the following two commands to install Composer -globally: - -.. code-block:: bash - - $ curl -sS https://getcomposer.org/installer | php - $ sudo mv composer.phar /usr/local/bin/composer - -On Windows Systems, download the executable Composer installer that you can find -on the `Composer download page`_ and follow the steps. +Start with :doc:`installing Composer globally `. Creating a Symfony Application with Composer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -279,7 +270,7 @@ If there are any issues, correct them now before moving on. Updating Symfony Applications ----------------------------- -At this point, you've create a fully-functional Symfony application in which +At this point, you've created a fully-functional Symfony application in which you'll start to develop your own project. A Symfony application depends on a number of external libraries. These are downloaded into the ``vendor/`` directory and they are managed exclusively by Composer. @@ -326,10 +317,10 @@ If you're using a version control system like `Git`_, you can safely commit all your project's code. The reason is that Symfony applications already contain a ``.gitignore`` file specially prepared for Symfony. -For specific instructions on how best to setup your project to be stored +For specific instructions on how best to set up your project to be stored in Git, see :doc:`/cookbook/workflow/new_project_git`. -Checking out a Versioned Symfony Application +Checking out a versioned Symfony Application ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When using Composer to manage application's dependencies, it's recommended to diff --git a/book/page_creation.rst b/book/page_creation.rst index cf8ca140e58..32fd6cf5154 100644 --- a/book/page_creation.rst +++ b/book/page_creation.rst @@ -93,7 +93,7 @@ Before you begin: Create the Bundle ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before you begin, you'll need to create a *bundle*. In Symfony, a :term:`bundle` -is like a plugin, except that all of the code in your application will live +is like a plugin, except that all the code in your application will live inside a bundle. A bundle is nothing more than a directory that houses everything related @@ -108,7 +108,7 @@ create the route. To create a bundle called ``AcmeDemoBundle`` (a play bundle that you'll build in this chapter), run the following command and follow the on-screen -instructions (use all of the default options): +instructions (use all the default options): .. code-block:: bash @@ -327,7 +327,7 @@ An optional, but common, third step in the process is to create a template. Optional Step 3: Create the Template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Templates allow you to move all of the presentation (e.g. HTML code) into +Templates allow you to move all the presentation code (e.g. HTML) into a separate file and reuse different portions of the page layout. Instead of writing the HTML inside the controller, render a template instead: @@ -607,7 +607,7 @@ You'll learn more about each of these directories in later chapters. The Source (``src``) Directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Put simply, the ``src/`` directory contains all of the actual code (PHP code, +Put simply, the ``src/`` directory contains all the actual code (PHP code, templates, configuration files, stylesheets, etc) that drives *your* application. When developing, the vast majority of your work will be done inside one or more bundles that you create in this directory. @@ -788,7 +788,7 @@ bundle. Application Configuration ------------------------- -An application consists of a collection of bundles representing all of the +An application consists of a collection of bundles representing all the features and capabilities of your application. Each bundle can be customized via configuration files written in YAML, XML or PHP. By default, the main configuration file lives in the ``app/config/`` directory and is called diff --git a/book/performance.rst b/book/performance.rst index b2e21a42610..e3f296484ad 100644 --- a/book/performance.rst +++ b/book/performance.rst @@ -60,7 +60,7 @@ command line, and might become part of your deploy process: .. code-block:: bash - $ php composer.phar dump-autoload --optimize + $ composer dump-autoload --optimize Internally, this builds the big class map array in ``vendor/composer/autoload_classmap.php``. @@ -128,8 +128,7 @@ Note that there are two disadvantages when using a bootstrap file: * when debugging, one will need to place break points inside the bootstrap file. If you're using the Symfony Standard Edition, the bootstrap file is automatically -rebuilt after updating the vendor libraries via the ``php composer.phar install`` -command. +rebuilt after updating the vendor libraries via the ``composer install`` command. Bootstrap Files and Byte Code Caches ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/book/security.rst b/book/security.rst index 995fcfa69d8..0856aad1f05 100644 --- a/book/security.rst +++ b/book/security.rst @@ -171,7 +171,7 @@ Firewalls (Authentication) When a user makes a request to a URL that's protected by a firewall, the security system is activated. The job of the firewall is to determine whether -or not the user needs to be authenticated, and if they do, to send a response +the user needs to be authenticated, and if they do, to send a response back to the user initiating the authentication process. A firewall is activated when the URL of an incoming request matches the configured @@ -710,7 +710,7 @@ see :doc:`/cookbook/security/form_login`. Next, make sure that your ``check_path`` URL (e.g. ``/login_check``) is behind the firewall you're using for your form login (in this example, the single firewall matches *all* URLs, including ``/login_check``). If - ``/login_check`` doesn't match any firewall, you'll receive a ``Unable + ``/login_check`` doesn't match any firewall, you'll receive an ``Unable to find the controller for path "/login_check"`` exception. **4. Multiple firewalls don't share the same security context** @@ -827,7 +827,7 @@ things: ................... Symfony creates an instance of :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher` -for each ``access_control`` entry, which determines whether or not a given +for each ``access_control`` entry, which determines whether a given access control should be used on this request. The following ``access_control`` options are used for matching: @@ -1601,7 +1601,7 @@ key in ``app/config/security.yml``. When you allow a user to submit a plaintext password (e.g. registration form, change password form), you *must* have validation that guarantees - that the password is 4096 characters or less. Read more details in + that the password is 4096 characters or fewer. Read more details in :ref:`How to implement a simple Registration Form `. Validating a Plaintext Password @@ -1820,7 +1820,7 @@ Roles The idea of a "role" is key to the authorization process. Each user is assigned a set of roles and then each resource requires one or more roles. If the user -has any one of the required roles, access is granted. Otherwise access is denied. +has any one of the required roles, access is granted. Otherwise, access is denied. Roles are pretty simple, and are basically strings that you can invent and use as needed (though roles are objects internally). For example, if you @@ -2326,7 +2326,7 @@ Security can be a deep and complex issue to solve correctly in your application. Fortunately, Symfony's Security component follows a well-proven security model based around *authentication* and *authorization*. Authentication, which always happens first, is handled by a firewall whose job is to determine -the identity of the user through several different methods (e.g. HTTP authentication, +the identity of the user through several methods (e.g. HTTP authentication, login form, etc). In the cookbook, you'll find examples of other methods for handling authentication, including how to implement a "remember me" cookie functionality. diff --git a/book/service_container.rst b/book/service_container.rst index 869119cb773..6e97d4831c1 100644 --- a/book/service_container.rst +++ b/book/service_container.rst @@ -141,7 +141,7 @@ is never created. This saves memory and increases the speed of your application. This also means that there's very little or no performance hit for defining lots of services. Services that are never used are never constructed. -As an added bonus, the ``Mailer`` service is only created once and the same +As a bonus, the ``Mailer`` service is only created once and the same instance is returned each time you ask for the service. This is almost always the behavior you'll need (it's more flexible and powerful), but you'll learn later how you can configure a service that has multiple instances in the @@ -484,7 +484,7 @@ In this case, the extension allows you to customize the ``error_handler``, the FrameworkBundle uses the options specified here to define and configure the services specific to it. The bundle takes care of creating all the necessary ``parameters`` and ``services`` for the service container, while still allowing -much of the configuration to be easily customized. As an added bonus, most +much of the configuration to be easily customized. As a bonus, most service container extensions are also smart enough to perform validation - notifying you of options that are missing or the wrong data type. @@ -1135,7 +1135,7 @@ console. To show all services and the class for each service, run: .. versionadded:: 2.6 Prior to Symfony 2.6, this command was called ``container:debug``. -By default only public services are shown, but you can also view private services: +By default, only public services are shown, but you can also view private services: .. code-block:: bash diff --git a/book/templating.rst b/book/templating.rst index d2c7c55a537..35d477c0ed3 100644 --- a/book/templating.rst +++ b/book/templating.rst @@ -403,7 +403,7 @@ Referencing Templates in a Bundle ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Symfony uses a **bundle**:**directory**:**filename** string syntax for -templates that live inside a bundle. This allows for several different types of +templates that live inside a bundle. This allows for several types of templates, each which lives in a specific location: * ``AcmeBlogBundle:Blog:index.html.twig``: This syntax is used to specify a @@ -499,7 +499,7 @@ Including other Templates ~~~~~~~~~~~~~~~~~~~~~~~~~ You'll often want to include the same template or code fragment on several -different pages. For example, in an application with "news articles", the +pages. For example, in an application with "news articles", the template code displaying an article might be used on the article detail page, on a page displaying the most popular articles, or in a list of the latest articles. @@ -1571,7 +1571,7 @@ Templates are a generic way to render content in *any* format. And while in most cases you'll use templates to render HTML content, a template can just as easily generate JavaScript, CSS, XML or any other format you can dream of. -For example, the same "resource" is often rendered in several different formats. +For example, the same "resource" is often rendered in several formats. To render an article index page in XML, simply include the format in the template name: diff --git a/book/testing.rst b/book/testing.rst index 559be27151a..bf69da90f0a 100644 --- a/book/testing.rst +++ b/book/testing.rst @@ -47,7 +47,7 @@ Unit Tests A unit test is usually a test against a specific PHP class. If you want to test the overall behavior of your application, see the section about `Functional Tests`_. -Writing Symfony unit tests is no different than writing standard PHPUnit +Writing Symfony unit tests is no different from writing standard PHPUnit unit tests. Suppose, for example, that you have an *incredibly* simple class called ``Calculator`` in the ``Utility/`` directory of your bundle:: @@ -632,7 +632,7 @@ Just like links, you select forms with the ``selectButton()`` method:: button. The ``selectButton()`` method can select ``button`` tags and submit ``input`` -tags. It uses several different parts of the buttons to find them: +tags. It uses several parts of the buttons to find them: * The ``value`` attribute value; @@ -790,7 +790,7 @@ PHPUnit Configuration Each application has its own PHPUnit configuration, stored in the ``app/phpunit.xml.dist`` file. You can edit this file to change the defaults or -create an ``app/phpunit.xml`` file to setup a configuration for your local +create an ``app/phpunit.xml`` file to set up a configuration for your local machine only. .. tip:: diff --git a/book/translation.rst b/book/translation.rst index 4eb99eba412..a847344b90d 100644 --- a/book/translation.rst +++ b/book/translation.rst @@ -389,7 +389,7 @@ Fallback Translation Locales Imagine that the user's locale is ``fr_FR`` and that you're translating the key ``Symfony is great``. To find the French translation, Symfony actually -checks translation resources for several different locales: +checks translation resources for several locales: #. First, Symfony looks for the translation in a ``fr_FR`` translation resource (e.g. ``messages.fr_FR.xliff``); @@ -443,7 +443,7 @@ The Locale and the URL ~~~~~~~~~~~~~~~~~~~~~~ Since you can store the locale of the user in the session, it may be tempting -to use the same URL to display a resource in many different languages based +to use the same URL to display a resource in different languages based on the user's locale. For example, ``http://www.example.com/contact`` could show content in English for one user and French for another user. Unfortunately, this violates a fundamental rule of the Web: that a particular URL returns diff --git a/book/validation.rst b/book/validation.rst index 72ceebe4d66..08726dc89ed 100644 --- a/book/validation.rst +++ b/book/validation.rst @@ -31,7 +31,7 @@ your application:: } So far, this is just an ordinary class that serves some purpose inside your -application. The goal of validation is to tell you whether or not the data +application. The goal of validation is to tell you if the data of an object is valid. For this to work, you'll configure a list of rules (called :ref:`constraints `) that the object must follow in order to be valid. These rules can be specified via a number of @@ -112,7 +112,7 @@ Using the ``validator`` Service Next, to actually validate an ``Author`` object, use the ``validate`` method on the ``validator`` service (class :class:`Symfony\\Component\\Validator\\Validator`). The job of the ``validator`` is easy: to read the constraints (i.e. rules) -of a class and verify whether or not the data on the object satisfies those +of a class and verify if the data on the object satisfies those constraints. If validation fails, a non-empty list of errors (class :class:`Symfony\\Component\\Validator\\ConstraintViolationList`) is returned. Take this simple example from inside a controller:: @@ -303,13 +303,13 @@ to its class and then pass it to the ``validator`` service. Behind the scenes, a constraint is simply a PHP object that makes an assertive statement. In real life, a constraint could be: "The cake must not be burned". In Symfony, constraints are similar: they are assertions that a condition -is true. Given a value, a constraint will tell you whether or not that value +is true. Given a value, a constraint will tell you if that value adheres to the rules of the constraint. Supported Constraints ~~~~~~~~~~~~~~~~~~~~~ -Symfony packages a large number of the most commonly-needed constraints: +Symfony packages many of the most commonly-needed constraints: .. include:: /reference/constraints/map.rst.inc @@ -689,8 +689,8 @@ Validation Groups ----------------- So far, you've been able to add constraints to a class and ask whether or -not that class passes all of the defined constraints. In some cases, however, -you'll need to validate an object against only *some* of the constraints +not that class passes all the defined constraints. In some cases, however, +you'll need to validate an object against only *some* constraints on that class. To do this, you can organize each constraint into one or more "validation groups", and then apply validation against just one group of constraints. diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst index 53a946583cd..94ff99d942b 100644 --- a/components/console/helpers/dialoghelper.rst +++ b/components/console/helpers/dialoghelper.rst @@ -247,13 +247,18 @@ Testing a Command which Expects Input If you want to write a unit test for a command which expects some kind of input from the command line, you need to overwrite the HelperSet used by the command:: + use Symfony\Component\Console\Application; use Symfony\Component\Console\Helper\DialogHelper; use Symfony\Component\Console\Helper\HelperSet; + use Symfony\Component\Console\Tester\CommandTester; // ... public function testExecute() { // ... + $application = new Application(); + $application->add(new MyCommand()); + $command = $application->find('my:command:name'); $commandTester = new CommandTester($command); $dialog = $command->getHelper('dialog'); @@ -279,3 +284,8 @@ By setting the input stream of the ``DialogHelper``, you imitate what the console would do internally with all user input through the cli. This way you can test any user interaction (even complex ones) by passing an appropriate input stream. + +.. seealso:: + + You find more information about testing commands in the console component + docs about :ref:`testing console commands `. diff --git a/components/console/introduction.rst b/components/console/introduction.rst index ecf5128cfc5..46c728b07da 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -413,6 +413,8 @@ tools capable of helping you with different tasks: * :doc:`/components/console/helpers/tablehelper`: displays tabular data as a table * :doc:`/components/console/helpers/dialoghelper`: (deprecated) interactively ask the user for information +.. _component-console-testing-commands: + Testing Commands ---------------- diff --git a/components/dependency_injection/lazy_services.rst b/components/dependency_injection/lazy_services.rst index 2d3eafc1785..2af8471b054 100644 --- a/components/dependency_injection/lazy_services.rst +++ b/components/dependency_injection/lazy_services.rst @@ -30,7 +30,7 @@ the `ProxyManager bridge`_: .. code-block:: bash - $ php composer.phar require symfony/proxy-manager-bridge:~2.3 + $ composer require symfony/proxy-manager-bridge:~2.3 .. note:: diff --git a/components/intl.rst b/components/intl.rst index bed02fc2b55..1c1dcc65a59 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -85,13 +85,13 @@ code:: the server. For example, consider that your development machines ship ICU 4.8 and the server - ICU 4.2. When you run ``php composer.phar update`` on the development machine, version + ICU 4.2. When you run ``composer update`` on the development machine, version 1.2.* of the Icu component will be installed. But after deploying the - application, ``php composer.phar install`` will fail with the following error: + application, ``composer install`` will fail with the following error: .. code-block:: bash - $ php composer.phar install + $ composer install Loading composer repositories with package information Installing dependencies from lock file Your requirements could not be resolved to an installable set of packages. @@ -104,8 +104,8 @@ code:: The error tells you that the requested version of the Icu component, version 1.2, is not compatible with PHP's ICU version 4.2. - One solution to this problem is to run ``php composer.phar update`` instead of - ``php composer.phar install``. It is highly recommended **not** to do this. The + One solution to this problem is to run ``composer update`` instead of + ``composer install``. It is highly recommended **not** to do this. The ``update`` command will install the latest versions of each Composer dependency to your production server and potentially break the application. @@ -130,7 +130,7 @@ code:: * "1.0.*" if the server does not have the intl extension installed; * "1.1.*" if the server is compiled with ICU 4.2 or lower. - Finally, run ``php composer.phar update symfony/icu`` on your development machine, test + Finally, run ``composer update symfony/icu`` on your development machine, test extensively and deploy again. The installation of the dependencies will now succeed. diff --git a/components/using_components.rst b/components/using_components.rst index 37db031de39..4103b956afc 100644 --- a/components/using_components.rst +++ b/components/using_components.rst @@ -31,16 +31,16 @@ whatever component you want. .. tip:: - If you get a command not found for ``composer``, you'll need to - `Install composer`_. Depending on how you install, you may end up with - a ``composer.phar`` file in your directory. In that case, no worries! - Just run ``php composer.phar require symfony/finder``. + `Install composer`_ if you don't have it already present on your system. + Depending on how you install, you may end up with a ``composer.phar`` + file in your directory. In that case, no worries! Just run + ``php composer.phar require symfony/finder``. If you know you need a specific version of the library, add that to the command: .. code-block:: bash - $ composer require symfony/finder:~2.3 + $ composer require symfony/finder **3.** Write your code! diff --git a/contributing/code/tests.rst b/contributing/code/tests.rst index ebec01f3d3e..ead51268289 100644 --- a/contributing/code/tests.rst +++ b/contributing/code/tests.rst @@ -28,42 +28,24 @@ The test suite needs the following third-party libraries: To install them all, use `Composer`_: -Step 1: Get `Composer`_ +Step 1: :doc:`Install Composer globally ` -.. code-block:: bash - - $ curl -s http://getcomposer.org/installer | php - -Make sure you download ``composer.phar`` in the same folder where -the ``composer.json`` file is located. - -Step 2: Install vendors +Step 2: Install vendors. .. code-block:: bash - $ php composer.phar install + $ composer install .. note:: Note that the script takes some time to finish. -.. note:: - - If you don't have ``curl`` installed, you can also just download the ``installer`` - file manually at http://getcomposer.org/installer. Place this file into your - project and then run: - - .. code-block:: bash - - $ php installer - $ php composer.phar install - After installation, you can update the vendors to their latest version with the follow command: .. code-block:: bash - $ php composer.phar update + $ composer --dev update Running ------- diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst index d6124026554..bd29a2c6226 100644 --- a/cookbook/bundles/installation.rst +++ b/cookbook/bundles/installation.rst @@ -36,7 +36,7 @@ Now that you know the package name, you can install it via Composer: .. code-block:: bash - $ php composer.phar require friendsofsymfony/user-bundle + $ composer require friendsofsymfony/user-bundle This will choose the best version for your project, add it to ``composer.json`` and download the library into the ``vendor/`` directory. If you need a specific diff --git a/cookbook/composer.rst b/cookbook/composer.rst new file mode 100644 index 00000000000..6444c8167e2 --- /dev/null +++ b/cookbook/composer.rst @@ -0,0 +1,44 @@ +.. index:: + double: Composer; Installation + +Installing Composer +=================== + +`Composer`_ is the package manager used by modern PHP applications and the +recommended way to install Symfony2. + +Install Composer on Linux and Mac OS X +-------------------------------------- + +To install Composer on Linux or Mac OS X, execute the following two commands: + +.. code-block:: bash + + $ curl -sS https://getcomposer.org/installer | php + $ sudo mv composer.phar /usr/local/bin/composer + +-.. note:: + + If you don't have ``curl`` installed, you can also just download the + ``installer`` file manually at http://getcomposer.org/installer and + then run: + + .. code-block:: bash + + $ php installer + $ sudo mv composer.phar /usr/local/bin/composer + +Install Composer on Windows +--------------------------- + +Download the installer from `getcomposer.org/download`_, execute it and follow +the instructions. + +Learn more +---------- + +You can read more about Composer in `its documentation`_. + +.. _`Composer`: https://getcomposer.org/ +.. _`getcomposer.org/download`: https://getcomposer.org/download +.. _`its documentation`: https://getcomposer.org/doc/00-intro.md diff --git a/cookbook/configuration/pdo_session_storage.rst b/cookbook/configuration/pdo_session_storage.rst index 25aa7ab7051..774ebe0478e 100644 --- a/cookbook/configuration/pdo_session_storage.rst +++ b/cookbook/configuration/pdo_session_storage.rst @@ -4,6 +4,12 @@ How to Use PdoSessionHandler to Store Sessions in the Database ============================================================== +.. caution:: + + There was a backwards-compatibility break in Symfony 2.6: the database + schema changed slightly. See :ref:`Symfony 2.6 Changes ` + for details. + The default Symfony session storage writes the session information to file(s). Most medium to large websites use a database to store the session values instead of files, because databases are easier to use and scale in a @@ -24,18 +30,11 @@ configuration format of your choice): # ... handler_id: session.handler.pdo - parameters: - pdo.db_options: - db_table: session - db_id_col: session_id - db_data_col: session_data - db_time_col: session_time - db_lifetime_col: session_lifetime - services: pdo: class: PDO arguments: + # see below for how to use your existing DB config dsn: "mysql:dbname=mydatabase" user: myuser password: mypassword @@ -44,7 +43,7 @@ configuration format of your choice): session.handler.pdo: class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler - arguments: ["@pdo", "%pdo.db_options%"] + arguments: ["@pdo"] .. code-block:: xml @@ -53,16 +52,6 @@ configuration format of your choice): - - - session - session_id - session_data - session_time - session_lifetime - - - mysql:dbname=mydatabase @@ -76,7 +65,6 @@ configuration format of your choice): - %pdo.db_options% @@ -94,14 +82,6 @@ configuration format of your choice): ), )); - $container->setParameter('pdo.db_options', array( - 'db_table' => 'session', - 'db_id_col' => 'session_id', - 'db_data_col' => 'session_data', - 'db_time_col' => 'session_time', - 'db_lifetime_col' => 'session_lifetime', - )); - $pdoDefinition = new Definition('PDO', array( 'mysql:dbname=mydatabase', 'myuser', @@ -112,15 +92,74 @@ configuration format of your choice): $storageDefinition = new Definition('Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler', array( new Reference('pdo'), - '%pdo.db_options%', )); $container->setDefinition('session.handler.pdo', $storageDefinition); -* ``db_table``: The name of the session table in your database -* ``db_id_col``: The name of the id column in your session table (VARCHAR(128)) -* ``db_data_col``: The name of the value column in your session table (BLOB) -* ``db_time_col``: The name of the time column in your session table (INTEGER) -* ``db_lifetime_col``: The name of the lifetime column in your session table (INTEGER) +Configuring the Table and Column Names +-------------------------------------- + +This will expect a ``sessions`` table with a number of different columns. +The table name, and all of the column names, can be configured by passing +a second array argument to ``PdoSessionHandler``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + services: + # ... + session.handler.pdo: + class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler + arguments: + - "@pdo" + - { 'db_table': 'sessions'} + + .. code-block:: xml + + + + + + + sessions + + + + + .. code-block:: php + + // app/config/config.php + + use Symfony\Component\DependencyInjection\Definition; + // ... + + $storageDefinition = new Definition( + 'Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler', + array( + new Reference('pdo'), + array('db_table' => 'session') + ) + ); + $container->setDefinition('session.handler.pdo', $storageDefinition); + +.. versionadded:: 2.6 + The ``db_lifetime_col`` was introduced in Symfony 2.6. Prior to 2.6, + this column did not exist. + +The following things can be configured: + +* ``db_table``: (default ``session``) The name of the session table in your + database; +* ``db_id_col``: (default ``sess_id``) The name of the id column in your + session table (VARCHAR(128)); +* ``db_data_col``: (default ``sess_data``) The name of the value column in + your session table (BLOB); +* ``db_time_col``: (default ``sess_time``) The name of the time column in + your session table (INTEGER); +* ``db_lifetime_col``: (default ``sess_lifetime``) The name of the lifetime + column in your session table (INTEGER). Sharing your Database Connection Information -------------------------------------------- @@ -164,6 +203,24 @@ of your project's data, you can use the connection settings from the Example SQL Statements ---------------------- +.. _pdo-session-handle-26-changes: + +.. sidebar:: Schema Changes needed when Upgrading to Symfony 2.6 + + If you use the ``PdoSessionHandler`` prior to Symfony 2.6 and upgrade, you'll + need to make a few changes to your session table: + + * A new session lifetime (``sess_lifetime`` by default) integer column + needs to be added; + * The data column (``sess_data`` by default) needs to be changed to a + BLOG type. + + Check the SQL statements below for more details. + + To keep the old (2.5 and earlier) functionality, change your class name + to use ``LegacyPdoSessionHandler`` instead of ``PdoSessionHandler`` (the + legacy class was added in Symfony 2.6.2). + MySQL ~~~~~ @@ -173,10 +230,10 @@ following (MySQL): .. code-block:: sql CREATE TABLE `session` ( - `session_id` VARBINARY(128) NOT NULL PRIMARY KEY, - `session_data` BLOB NOT NULL, - `session_time` INTEGER UNSIGNED NOT NULL, - `session_lifetime` MEDIUMINT NOT NULL + `sess_id` VARBINARY(128) NOT NULL PRIMARY KEY, + `sess_data` BLOB NOT NULL, + `sess_time` INTEGER UNSIGNED NOT NULL, + `sess_lifetime` MEDIUMINT NOT NULL ) COLLATE utf8_bin, ENGINE = InnoDB; PostgreSQL @@ -187,10 +244,10 @@ For PostgreSQL, the statement should look like this: .. code-block:: sql CREATE TABLE session ( - session_id VARCHAR(128) NOT NULL PRIMARY KEY, - session_data BYTEA NOT NULL, - session_time INTEGER NOT NULL, - session_lifetime INTEGER NOT NULL + sess_id VARCHAR(128) NOT NULL PRIMARY KEY, + sess_data BYTEA NOT NULL, + sess_time INTEGER NOT NULL, + sess_lifetime INTEGER NOT NULL ); Microsoft SQL Server @@ -201,12 +258,12 @@ For MSSQL, the statement might look like the following: .. code-block:: sql CREATE TABLE [dbo].[session]( - [session_id] [nvarchar](255) NOT NULL, - [session_data] [ntext] NOT NULL, - [session_time] [int] NOT NULL, - [session_lifetime] [int] NOT NULL, + [sess_id] [nvarchar](255) NOT NULL, + [sess_data] [ntext] NOT NULL, + [sess_time] [int] NOT NULL, + [sess_lifetime] [int] NOT NULL, PRIMARY KEY CLUSTERED( - [session_id] ASC + [sess_id] ASC ) WITH ( PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, diff --git a/cookbook/deployment/tools.rst b/cookbook/deployment/tools.rst index 76992a17c59..4004c06aeb8 100644 --- a/cookbook/deployment/tools.rst +++ b/cookbook/deployment/tools.rst @@ -101,7 +101,7 @@ as you normally do: .. code-block:: bash - $ php composer.phar install --no-dev --optimize-autoloader + $ composer install --no-dev --optimize-autoloader .. tip:: @@ -142,7 +142,7 @@ setup: * Running any database migrations * Clearing your APC cache -* Running ``assets:install`` (taken care of already in ``composer.phar install``) +* Running ``assets:install`` (already taken care of in ``composer install``) * Add/edit CRON jobs * Pushing assets to a CDN * ... diff --git a/cookbook/index.rst b/cookbook/index.rst index 1a088c672dd..c5aa2aae316 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -7,6 +7,7 @@ The Cookbook assetic/index bundles/index cache/index + composer configuration/index console/index controller/index diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 8ff3536577d..3d3cd12c2f7 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -21,6 +21,10 @@ * :doc:`/cookbook/cache/varnish` +* **Composer** + + * :doc:`/cookbook/composer` + * :doc:`/cookbook/configuration/index` * :doc:`/cookbook/configuration/environments` diff --git a/cookbook/symfony1.rst b/cookbook/symfony1.rst index a393534e8ec..10ba32149ff 100644 --- a/cookbook/symfony1.rst +++ b/cookbook/symfony1.rst @@ -165,7 +165,7 @@ defined in the ``composer.json`` file. If you look at the ``HelloController`` from the Symfony2 Standard Edition you can see that it lives in the ``Acme\DemoBundle\Controller`` namespace. Yet, the AcmeDemoBundle is not defined in your ``composer.json`` file. Nonetheless are -the files autoloaded. This is because you can tell composer to autoload files +the files autoloaded. This is because you can tell Composer to autoload files from specific directories without defining a dependency: .. code-block:: json diff --git a/cookbook/workflow/_vendor_deps.rst.inc b/cookbook/workflow/_vendor_deps.rst.inc index 93d009550b4..322336627ca 100644 --- a/cookbook/workflow/_vendor_deps.rst.inc +++ b/cookbook/workflow/_vendor_deps.rst.inc @@ -9,18 +9,18 @@ way or another the goal is to download these files into your ``vendor/`` directory and, ideally, to give you some sane way to manage the exact version you need for each. -By default, these libraries are downloaded by running a ``php composer.phar install`` -"downloader" binary. This ``composer.phar`` file is from a library called -`Composer`_ and you can read more about installing it in the :ref:`Installation ` +By default, these libraries are downloaded by running a ``composer install`` +"downloader" binary. This ``composer`` file is from a library called `Composer`_ +and you can read more about installing it in the :ref:`Installation ` chapter. -The ``composer.phar`` file reads from the ``composer.json`` file at the root +The ``composer`` command reads from the ``composer.json`` file at the root of your project. This is an JSON-formatted file, which holds a list of each of the external packages you need, the version to be downloaded and more. -The ``composer.phar`` file also reads from a ``composer.lock`` file, which -allows you to pin each library to an **exact** version. In fact, if a ``composer.lock`` +``composer`` also reads from a ``composer.lock`` file, which allows you to +pin each library to an **exact** version. In fact, if a ``composer.lock`` file exists, the versions inside will override those in ``composer.json``. -To upgrade your libraries to new versions, run ``php composer.phar update``. +To upgrade your libraries to new versions, run ``composer update``. .. tip:: @@ -29,7 +29,7 @@ To upgrade your libraries to new versions, run ``php composer.phar update``. .. code-block:: bash - $ php composer.phar require doctrine/doctrine-fixtures-bundle + $ composer require doctrine/doctrine-fixtures-bundle To learn more about Composer, see `GetComposer.org`_: @@ -37,12 +37,12 @@ It's important to realize that these vendor libraries are *not* actually part of *your* repository. Instead, they're simply un-tracked files that are downloaded into the ``vendor/``. But since all the information needed to download these files is saved in ``composer.json`` and ``composer.lock`` (which *are* stored -in the repository), any other developer can use the project, run ``php composer.phar install``, +in the repository), any other developer can use the project, run ``composer install``, and download the exact same set of vendor libraries. This means that you're controlling exactly what each vendor library looks like, without needing to actually commit them to *your* repository. -So, whenever a developer uses your project, they should run the ``php composer.phar install`` +So, whenever a developer uses your project, they should run the ``composer install`` script to ensure that all of the needed vendor libraries are downloaded. .. sidebar:: Upgrading Symfony diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 2b97ff51210..bed99808f45 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -55,6 +55,10 @@ Configuration * `property_accessor`_ * `magic_call`_ * `throw_exception_on_invalid_index`_ +* `validation`_ + * `cache`_ + * `enable_annotations`_ + * `translation_domain`_ secret ~~~~~~ @@ -558,6 +562,35 @@ throw_exception_on_invalid_index When enabled, the ``property_accessor`` service throws an exception when you try to access an invalid index of an array. +validation +~~~~~~~~~~ + +cache +..... + +**type**: ``string`` + +This value is used to determine the service that is used to persist class +metadata in a cache. The actual service name is built by prefix the configured +value with ``validator.mapping.cache.`` (e.g. if the value is ``apc``, the +``validator.mapping.cache.apc`` service will be injected). The service has +to implement the :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInterface`. + +enable_annotations +.................. + +**type**: ``Boolean`` **default**: ``false`` + +If this option is enabled, validation constraints can be defined using annotations. + +translation_domain +.................. + +**type**: ``string`` **default**: ``validators`` + +The translation domain that is used when translating validation constraint +error messages. + Full default Configuration -------------------------- @@ -692,3 +725,4 @@ Full default Configuration .. _`protocol-relative`: http://tools.ietf.org/html/rfc3986#section-4.2 .. _`PhpStormOpener`: https://github.com/pinepain/PhpStormOpener +.. _`egulias/email-validator`: https://github.com/egulias/EmailValidator