diff --git a/book/controller.rst b/book/controller.rst index 0dadd3bca41..def17d79686 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -553,7 +553,7 @@ command: .. code-block:: bash - php app/console container:debug + $ php app/console container:debug For more information, see the :doc:`/book/service_container` chapter. diff --git a/book/doctrine.rst b/book/doctrine.rst index 2a027f1236d..bb65a76a0cb 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -37,7 +37,7 @@ persist it to the database and fetch it back out. .. code-block:: bash - php app/console generate:bundle --namespace=Acme/StoreBundle + $ php app/console generate:bundle --namespace=Acme/StoreBundle Configuring the Database ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -84,7 +84,7 @@ for you: .. code-block:: bash - php app/console doctrine:database:create + $ php app/console doctrine:database:create Creating an Entity Class ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -118,7 +118,7 @@ just a simple PHP class. .. code-block:: bash - php app/console doctrine:generate:entity --entity="AcmeStoreBundle:Product" --fields="name:string(255) price:float description:text" + $ php app/console doctrine:generate:entity --entity="AcmeStoreBundle:Product" --fields="name:string(255) price:float description:text" .. index:: single: Doctrine; Adding mapping metadata @@ -279,7 +279,7 @@ a regular PHP class, you need to create getter and setter methods (e.g. ``getNam .. code-block:: bash - php app/console doctrine:generate:entities Acme/StoreBundle/Entity/Product + $ php app/console doctrine:generate:entities Acme/StoreBundle/Entity/Product This command makes sure that all of the getters and setters are generated for the ``Product`` class. This is a safe command - you can run it over and @@ -313,8 +313,8 @@ mapping information) of a bundle or an entire namespace: .. code-block:: bash - php app/console doctrine:generate:entities AcmeStoreBundle - php app/console doctrine:generate:entities Acme + $ php app/console doctrine:generate:entities AcmeStoreBundle + $ php app/console doctrine:generate:entities Acme .. note:: @@ -334,7 +334,7 @@ in your application. To do this, run: .. code-block:: bash - php app/console doctrine:schema:update --force + $ php app/console doctrine:schema:update --force .. tip:: @@ -727,7 +727,7 @@ used earlier to generate the missing getter and setter methods: .. code-block:: bash - php app/console doctrine:generate:entities Acme + $ php app/console doctrine:generate:entities Acme Next, add a new method - ``findAllOrderedByName()`` - to the newly generated repository class. This method will query for all of the ``Product`` entities, @@ -779,7 +779,7 @@ you can let Doctrine create the class for you. .. code-block:: bash - php app/console doctrine:generate:entity --entity="AcmeStoreBundle:Category" --fields="name:string(255)" + $ php app/console doctrine:generate:entity --entity="AcmeStoreBundle:Category" --fields="name:string(255)" This task generates the ``Category`` entity for you, with an ``id`` field, a ``name`` field and the associated getter and setter functions. @@ -890,7 +890,7 @@ methods for you: .. code-block:: bash - php app/console doctrine:generate:entities Acme + $ php app/console doctrine:generate:entities Acme Ignore the Doctrine metadata for a moment. You now have two classes - ``Category`` and ``Product`` with a natural one-to-many relationship. The ``Category`` @@ -919,7 +919,7 @@ table, and ``product.category_id`` column, and new foreign key: .. code-block:: bash - php app/console doctrine:schema:update --force + $ php app/console doctrine:schema:update --force .. note:: @@ -1322,7 +1322,7 @@ without any arguments: .. code-block:: bash - php app/console + $ php app/console A list of available command will print out, many of which start with the ``doctrine:`` prefix. You can find out more information about any of these @@ -1331,7 +1331,7 @@ to get details about the ``doctrine:database:create`` task, run: .. code-block:: bash - php app/console help doctrine:database:create + $ php app/console help doctrine:database:create Some notable or interesting tasks include: @@ -1341,7 +1341,7 @@ Some notable or interesting tasks include: .. code-block:: bash - php app/console doctrine:ensure-production-settings --env=prod + $ php app/console doctrine:ensure-production-settings --env=prod * ``doctrine:mapping:import`` - allows Doctrine to introspect an existing database and create mapping information. For more information, see diff --git a/book/forms.rst b/book/forms.rst index 13a22c9b54c..6b24d9f1dbb 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -64,7 +64,7 @@ going to need to build a form. But before you begin, first focus on the generic .. code-block:: bash - php app/console generate:bundle --namespace=Acme/TaskBundle + $ php app/console generate:bundle --namespace=Acme/TaskBundle This class is a "plain-old-PHP-object" because, so far, it has nothing to do with Symfony or any other library. It's quite simply a normal PHP object diff --git a/book/installation.rst b/book/installation.rst index 42694d60747..8237c8994ae 100644 --- a/book/installation.rst +++ b/book/installation.rst @@ -49,10 +49,10 @@ one of the following commands (replacing ``###`` with your actual filename): .. code-block:: bash # for .tgz file - tar zxvf Symfony_Standard_Vendors_2.0.###.tgz + $ tar zxvf Symfony_Standard_Vendors_2.0.###.tgz # for a .zip file - unzip Symfony_Standard_Vendors_2.0.###.zip + $ unzip Symfony_Standard_Vendors_2.0.###.zip When you're finished, you should have a ``Symfony/`` directory that looks something like this: @@ -81,7 +81,7 @@ by running the following command from the command line: .. code-block:: bash - php bin/vendors install + $ php bin/vendors install This command downloads all of the necessary vendor libraries - including Symfony itself - into the ``vendor/`` directory. For more information on @@ -121,11 +121,11 @@ If there are any issues, correct them now before moving on. .. code-block:: bash - rm -rf app/cache/* - rm -rf app/logs/* + $ rm -rf app/cache/* + $ rm -rf app/logs/* - sudo chmod +a "www-data allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs - sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs + $ sudo chmod +a "www-data allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs + $ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs **2. Using Acl on a system that does not support chmod +a** @@ -136,8 +136,8 @@ If there are any issues, correct them now before moving on. .. code-block:: bash - sudo setfacl -R -m u:www-data:rwx -m u:`whoami`:rwx app/cache app/logs - sudo setfacl -dR -m u:www-data:rwx -m u:`whoami`:rwx app/cache app/logs + $ sudo setfacl -R -m u:www-data:rwx -m u:`whoami`:rwx app/cache app/logs + $ sudo setfacl -dR -m u:www-data:rwx -m u:`whoami`:rwx app/cache app/logs Note that not all web servers run as the user ``www-data``. You have to check which user the web server is being run as and put it in for ``www-data``. diff --git a/book/page_creation.rst b/book/page_creation.rst index ed6000ec1f2..b421bc74256 100644 --- a/book/page_creation.rst +++ b/book/page_creation.rst @@ -69,7 +69,7 @@ instructions (use all of the default options): .. code-block:: bash - php app/console generate:bundle --namespace=Acme/HelloBundle --format=yml + $ php app/console generate:bundle --namespace=Acme/HelloBundle --format=yml Behind the scenes, a directory is created for the bundle at ``src/Acme/HelloBundle``. A line is also automatically added to the ``app/AppKernel.php`` file so that @@ -261,7 +261,7 @@ application should greet you: .. code-block:: bash - php app/console cache:clear --env=prod --no-debug + $ php app/console cache:clear --env=prod --no-debug An optional, but common, third step in the process is to create a template. @@ -667,7 +667,7 @@ generating a basic bundle skeleton: .. code-block:: bash - php app/console generate:bundle --namespace=Acme/TestBundle + $ php app/console generate:bundle --namespace=Acme/TestBundle The bundle skeleton generates with a basic controller, template and routing resource that can be customized. You'll learn more about Symfony2's command-line diff --git a/book/propel.rst b/book/propel.rst index 76f33b92a51..ff71670e3e0 100644 --- a/book/propel.rst +++ b/book/propel.rst @@ -22,7 +22,7 @@ persist it to the database and fetch it back out. .. code-block:: bash - php app/console generate:bundle --namespace=Acme/StoreBundle + $ php app/console generate:bundle --namespace=Acme/StoreBundle Configuring the Database ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -33,7 +33,7 @@ information. By convention, this information is usually configured in an .. code-block:: ini - ;app/config/parameters.ini + ; app/config/parameters.ini [parameters] database_driver = mysql database_host = localhost @@ -62,7 +62,7 @@ you: .. code-block:: bash - php app/console propel:database:create + $ php app/console propel:database:create .. note:: @@ -104,7 +104,7 @@ After creating your ``schema.xml``, generate your model from it by running: .. code-block:: bash - php app/console propel:model:build + $ php app/console propel:model:build This generates each model class to quickly develop your application in the ``Model/`` directory the ``AcmeStoreBundle`` bundle. @@ -119,9 +119,8 @@ needed for every known model in your application. To do this, run: .. code-block:: bash - php app/console propel:sql:build - - php app/console propel:sql:insert --force + $ php app/console propel:sql:build + $ php app/console propel:sql:insert --force Your database now has a fully-functional ``product`` table with columns that match the schema you've specified. @@ -305,7 +304,7 @@ Create the classes: .. code-block:: bash - php app/console propel:model:build + $ php app/console propel:model:build Assuming you have products in your database, you don't want lose them. Thanks to migrations, Propel will be able to update your database without losing existing @@ -313,9 +312,8 @@ data. .. code-block:: bash - php app/console propel:migration:generate-diff - - php app/console propel:migration:migrate + $ php app/console propel:migration:generate-diff + $ php app/console propel:migration:migrate Your database has been updated, you can continue to write your application. diff --git a/book/routing.rst b/book/routing.rst index 457e4dde5d6..55311901fb7 100644 --- a/book/routing.rst +++ b/book/routing.rst @@ -1026,7 +1026,7 @@ the command by running the following from the root of your project. .. code-block:: bash - php app/console router:debug + $ php app/console router:debug The command will print a helpful list of *all* the configured routes in your application: @@ -1045,7 +1045,7 @@ the route name after the command: .. code-block:: bash - php app/console router:debug article_show + $ php app/console router:debug article_show .. index:: single: Routing; Generating URLs diff --git a/book/translation.rst b/book/translation.rst index 44965bf025d..10fbda08159 100644 --- a/book/translation.rst +++ b/book/translation.rst @@ -270,7 +270,7 @@ filesystem and discovered by Symfony, thanks to some conventions. .. code-block:: bash - php app/console cache:clear + $ php app/console cache:clear .. index:: single: Translations; Translation resource locations diff --git a/components/console.rst b/components/console.rst index 6a5b306539e..8e5cc3b91de 100755 --- a/components/console.rst +++ b/components/console.rst @@ -81,7 +81,7 @@ Test the new console command by running the following .. code-block:: bash - app/console demo:greet Fabien + $ app/console demo:greet Fabien This will print the following to the command line: @@ -93,7 +93,7 @@ You can also use the ``--yell`` option to make everything uppercase: .. code-block:: bash - app/console demo:greet Fabien --yell + $ app/console demo:greet Fabien --yell This prints:: @@ -153,8 +153,8 @@ The command can now be used in either of the following ways: .. code-block:: bash - app/console demo:greet Fabien - app/console demo:greet Fabien Potencier + $ app/console demo:greet Fabien + $ app/console demo:greet Fabien Potencier Using Command Options --------------------- @@ -192,9 +192,8 @@ flag: .. code-block:: bash - app/console demo:greet Fabien - - app/console demo:greet Fabien --iterations=5 + $ app/console demo:greet Fabien + $ app/console demo:greet Fabien --iterations=5 The first example will only print once, since ``iterations`` is empty and defaults to ``1`` (the last argument of ``addOption``). The second example @@ -205,8 +204,8 @@ will work: .. code-block:: bash - app/console demo:greet Fabien --iterations=5 --yell - app/console demo:greet Fabien --yell --iterations=5 + $ app/console demo:greet Fabien --iterations=5 --yell + $ app/console demo:greet Fabien --yell --iterations=5 There are 4 option variants you can use: diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index e7182abcb3d..539b3268112 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -68,6 +68,51 @@ GitHub covers the topic of `pull requests`_ in detail. `Documentation Build Errors`_ page (it is updated each French night at 3AM when the server rebuilds the documentation). +Standards +--------- + +In order to help the reader as much as possible and to create code examples that +looks and feels familiar, you should follow these rules: + +* The code follows the Coding Standards, the :doc:`Symfony Coding Standards` + as well as the `Twig Coding Standards`_; +* When we fold one or more lines of code, we place `...` in a comment at the point + of the fold. These comments are: `// ...` (php), `# ...` (yaml/bash), `{# ... #}` + (twig), `` (xml/html), `; ...` (ini), `...` (text); +* When we fold a part of a line, e.g. a variable value, we put `...` (without comment) + at the place of the fold; +* Description about the fold: (optional) + If we fold some lines: The description can be placed after the `...` + If we fold a part of a line: The description can be placed before the line; +* If usefull, a codeblock begins with a comment with the filename. After this comment + should not be a blank line, except if the next line is a comment too; +* You should put a `$` in front of every bash line; +* We prefer the `::` shorthand over `.. code-block:: php` to begin a PHP code block. + +An example:: + + // src/Foo/Bar/foo.php + function foo($bar) + { + // set foo with a value of bar + $foo = ...; + + // ... check if $bar has the correct value + + return $foo->baz($bar, ...); + } + +.. note:: + * In Yaml you should to put a space after `{` and before `}` (e.g. `{ _controller: ... }`), + but this should not be done in Twig (e.g. `{'hello' : 'value'}`). + * An array item is a part of a line, not a complete line. So you should not use `// ...` + but `...,` (the comma because of the Coding Standards):: + + array( + 'some value', + ..., + ) + Reporting an Issue ------------------ @@ -88,3 +133,4 @@ Read the dedicated :doc:`document `. .. _`fork`: http://help.github.com/fork-a-repo/ .. _`pull requests`: http://help.github.com/pull-requests/ .. _`Documentation Build Errors`: http://symfony.com/doc/build_errors +.. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index 4da164e5495..ed96497591d 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -300,7 +300,7 @@ each time you deploy), you should run the following task: .. code-block:: bash - php app/console assetic:dump --env=prod --no-debug + $ php app/console assetic:dump --env=prod --no-debug This will physically generate and write each file that you need (e.g. ``/js/abcd123.js``). If you update any of your assets, you'll need to run this again to regenerate @@ -342,7 +342,7 @@ need to dump them manually. To do so, run the following: .. code-block:: bash - php app/console assetic:dump + $ php app/console assetic:dump This physically writes all of the asset files you need for your ``dev`` environment. The big disadvantage is that you need to run this each time @@ -351,7 +351,7 @@ command will automatically regenerate assets *as they change*: .. code-block:: bash - php app/console assetic:dump --watch + $ php app/console assetic:dump --watch Since running this command in the ``dev`` environment may generate a bunch of files, it's usually a good idea to point your generated assets files to diff --git a/cookbook/configuration/apache_router.rst b/cookbook/configuration/apache_router.rst index 11b24838a20..23e0f6dd828 100644 --- a/cookbook/configuration/apache_router.rst +++ b/cookbook/configuration/apache_router.rst @@ -45,7 +45,7 @@ Now we generate **url_rewrite** rules: .. code-block:: bash - php app/console router:dump-apache -e=prod --no-debug + $ php app/console router:dump-apache -e=prod --no-debug Which should roughly output the following: @@ -100,4 +100,4 @@ to ``ApacheRequest`` in ``web/app.php``:: $kernel = new AppKernel('prod', false); $kernel->loadClassCache(); //$kernel = new AppCache($kernel); - $kernel->handle(ApacheRequest::createFromGlobals())->send(); \ No newline at end of file + $kernel->handle(ApacheRequest::createFromGlobals())->send(); diff --git a/cookbook/configuration/external_parameters.rst b/cookbook/configuration/external_parameters.rst index c335f751e0f..3546267ccb5 100644 --- a/cookbook/configuration/external_parameters.rst +++ b/cookbook/configuration/external_parameters.rst @@ -48,8 +48,8 @@ the following ``VirtualHost`` configuration: .. code-block:: bash - export SYMFONY__DATABASE__USER=user - export SYMFONY__DATABASE__PASSWORD=secret + $ export SYMFONY__DATABASE__USER=user + $ export SYMFONY__DATABASE__PASSWORD=secret Now that you have declared an environment variable, it will be present in the PHP ``$_SERVER`` global variable. Symfony then automatically sets all diff --git a/cookbook/console/console_command.rst b/cookbook/console/console_command.rst index 309f14f749a..8702d92df08 100644 --- a/cookbook/console/console_command.rst +++ b/cookbook/console/console_command.rst @@ -60,7 +60,7 @@ This command will now automatically be available to run: .. code-block:: bash - app/console demo:greet Fabien + $ app/console demo:greet Fabien Testing Commands ---------------- @@ -108,4 +108,4 @@ For example, you could easily extend the task to be translatable:: } else { $output->writeln($translator->trans('Hello!')); } - } \ No newline at end of file + } diff --git a/cookbook/doctrine/reverse_engineering.rst b/cookbook/doctrine/reverse_engineering.rst index 308f98a2f94..c81ecdaed08 100644 --- a/cookbook/doctrine/reverse_engineering.rst +++ b/cookbook/doctrine/reverse_engineering.rst @@ -60,7 +60,7 @@ tables fields. .. code-block:: bash - php app/console doctrine:mapping:convert xml ./src/Acme/BlogBundle/Resources/config/doctrine/metadata/orm --from-database --force + $ php app/console doctrine:mapping:convert xml ./src/Acme/BlogBundle/Resources/config/doctrine/metadata/orm --from-database --force This command line tool asks Doctrine to introspect the database and generate the XML metadata files under the ``src/Acme/BlogBundle/Resources/config/doctrine/metadata/orm`` @@ -97,8 +97,8 @@ schema and build related entity classes by executing the following two commands. .. code-block:: bash - php app/console doctrine:mapping:import AcmeBlogBundle annotation - php app/console doctrine:generate:entities AcmeBlogBundle + $ php app/console doctrine:mapping:import AcmeBlogBundle annotation + $ php app/console doctrine:generate:entities AcmeBlogBundle The first command generates entity classes with an annotations mapping, but you can of course change the ``annotation`` argument to ``xml`` or ``yml``. diff --git a/cookbook/email/spool.rst b/cookbook/email/spool.rst index a9af8d73f8f..f046637541e 100644 --- a/cookbook/email/spool.rst +++ b/cookbook/email/spool.rst @@ -70,19 +70,19 @@ There is a console command to send the messages in the spool: .. code-block:: bash - php app/console swiftmailer:spool:send --env=prod + $ php app/console swiftmailer:spool:send --env=prod It has an option to limit the number of messages to be sent: .. code-block:: bash - php app/console swiftmailer:spool:send --message-limit=10 --env=prod + $ php app/console swiftmailer:spool:send --message-limit=10 --env=prod You can also set the time limit in seconds: .. code-block:: bash - php app/console swiftmailer:spool:send --time-limit=10 --env=prod + $ php app/console swiftmailer:spool:send --time-limit=10 --env=prod Of course you will not want to run this manually in reality. Instead, the console command should be triggered by a cron job or scheduled task and run diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst index 9c55aead9d7..21db8c2520c 100644 --- a/quick_tour/the_architecture.rst +++ b/quick_tour/the_architecture.rst @@ -341,13 +341,13 @@ Run it without any arguments to learn more about its capabilities: .. code-block:: bash - php app/console + $ php app/console The ``--help`` option helps you discover the usage of a command: .. code-block:: bash - php app/console router:debug --help + $ php app/console router:debug --help Final Thoughts -------------- diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 49579c8cf8f..996d14a4716 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -29,7 +29,7 @@ Apache) with PHP 5.3.2 or higher. .. code-block:: bash - php -S localhost:80 -t /path/to/www + $ php -S localhost:80 -t /path/to/www where "/path/to/www" is the path to some directory on your machine that you'll extract Symfony into so that the eventual URL to your application @@ -76,7 +76,7 @@ have a ``Symfony/`` directory that looks like this: .. code-block:: bash - php bin/vendors install + $ php bin/vendors install Checking the Configuration --------------------------