Skip to content

[book] Fixed every inconsistention find in quick proofread #1798

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 2, 2012
Merged

[book] Fixed every inconsistention find in quick proofread #1798

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0aa850
[book] Fixed every inconsistention find in quick proofread
wouterj Oct 8, 2012
2e2a73a
[Book] Tweaked API class link
wouterj Oct 19, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 6 additions & 14 deletions book/controller.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,11 +202,8 @@ Route Parameters as Controller Arguments
You already know that the ``_controller`` parameter ``AcmeHelloBundle:Hello:index``
refers to a ``HelloController::indexAction()`` method that lives inside the
``AcmeHelloBundle`` bundle. What's more interesting is the arguments that are
passed to that method:
passed to that method::

.. code-block:: php

<?php
// src/Acme/HelloBundle/Controller/HelloController.php
namespace Acme\HelloBundle\Controller;

Expand Down Expand Up @@ -344,9 +341,7 @@ access to any resource it might need. By extending this ``Controller`` class,
you can take advantage of several helper methods.

Add the ``use`` statement atop the ``Controller`` class and then modify the
``HelloController`` to extend it:

.. code-block:: php
``HelloController`` to extend it::

// src/Acme/HelloBundle/Controller/HelloController.php
namespace Acme\HelloBundle\Controller;
Expand All @@ -358,7 +353,7 @@ Add the ``use`` statement atop the ``Controller`` class and then modify the
{
public function indexAction($name)
{
return new Response('<html><body>Hello '.$name.'!</body></html>');
return new Response('<html><body>Hello '.$name.'!</body></html>');
}
}

Expand All @@ -375,13 +370,12 @@ itself.

Extending the base class is *optional* in Symfony; it contains useful
shortcuts but nothing mandatory. You can also extend
``Symfony\Component\DependencyInjection\ContainerAware``. The service
:class:`Symfony\\Component\\DependencyInjection\\ContainerAware`. The service
container object will then be accessible via the ``container`` property.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

need the double \\ here - Symfony\\Component..

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, I will fix it


.. note::

You can also define your :doc:`Controllers as Services
</cookbook/controller/service>`.
You can also define your :doc:`Controllers as Services</cookbook/controller/service>`.

.. index::
single: Controller; Common tasks
Expand Down Expand Up @@ -422,9 +416,7 @@ perform a 301 (permanent) redirect, modify the second argument::
.. tip::

The ``redirect()`` method is simply a shortcut that creates a ``Response``
object that specializes in redirecting the user. It's equivalent to:

.. code-block:: php
object that specializes in redirecting the user. It's equivalent to::

use Symfony\Component\HttpFoundation\RedirectResponse;

Expand Down
34 changes: 17 additions & 17 deletions book/doctrine.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ be.

Doctrine is totally decoupled from Symfony and using it is optional.
This chapter is all about the Doctrine ORM, which aims to let you map
objects to a relational database (such as *MySQL*, *PostgreSQL* or *Microsoft SQL*).
If you prefer to use raw database queries, this is easy, and explained
in the ":doc:`/cookbook/doctrine/dbal`" cookbook entry.
objects to a relational database (such as *MySQL*, *PostgreSQL* or
*Microsoft SQL*). If you prefer to use raw database queries, this is
easy, and explained in the ":doc:`/cookbook/doctrine/dbal`" cookbook entry.

You can also persist data to `MongoDB`_ using Doctrine ODM library. For
more information, read the ":doc:`/bundles/DoctrineMongoDBBundle/index`"
Expand Down Expand Up @@ -169,12 +169,6 @@ properties should be *mapped* to the database. This metadata can be specified
in a number of different formats including YAML, XML or directly inside the
``Product`` class via annotations:

.. note::

A bundle can accept only one metadata definition format. For example, it's
not possible to mix YAML metadata definitions with annotated PHP entity
class definitions.

.. configuration-block::

.. code-block:: php-annotations
Expand Down Expand Up @@ -251,6 +245,12 @@ in a number of different formats including YAML, XML or directly inside the
</entity>
</doctrine-mapping>

.. note::

A bundle can accept only one metadata definition format. For example, it's
not possible to mix YAML metadata definitions with annotated PHP entity
class definitions.

.. tip::

The table name is optional and if omitted, will be determined automatically
Expand Down Expand Up @@ -293,6 +293,7 @@ see the :ref:`book-doctrine-field-types` section.
* @IgnoreAnnotation("fn")
*/
class Product
// ...

Generating Getters and Setters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -316,10 +317,10 @@ doesn't replace your existing methods).

With the ``doctrine:generate:entities`` command you can:

* generate getters and setters,
* generate getters and setters;

* generate repository classes configured with the
``@ORM\Entity(repositoryClass="...")`` annotation,
``@ORM\Entity(repositoryClass="...")`` annotation;

* generate the appropriate constructor for 1:n and n:m relations.

Expand Down Expand Up @@ -420,11 +421,11 @@ of the bundle:
Let's walk through this example:

* **lines 9-12** In this section, you instantiate and work with the ``$product``
object like any other, normal PHP object;
object like any other, normal PHP object.

* **line 14** This line fetches Doctrine's *entity manager* object, which is
responsible for handling the process of persisting and fetching objects
to and from the database;
to and from the database.

* **line 15** The ``persist()`` method tells Doctrine to "manage" the ``$product``
object. This does not actually cause a query to be made to the database (yet).
Expand Down Expand Up @@ -558,9 +559,9 @@ you have a route that maps a product id to an update action in a controller::

Updating an object involves just three steps:

1. fetching the object from Doctrine;
2. modifying the object;
3. calling ``flush()`` on the entity manager
#. fetching the object from Doctrine;
#. modifying the object;
#. calling ``flush()`` on the entity manager

Notice that calling ``$em->persist($product)`` isn't necessary. Recall that
this method simply tells Doctrine to manage or "watch" the ``$product`` object.
Expand Down Expand Up @@ -884,7 +885,6 @@ object, you'll want to add a ``$category`` property to the ``Product`` class:
// src/Acme/StoreBundle/Entity/Product.php

// ...

class Product
{
// ...
Expand Down
24 changes: 8 additions & 16 deletions book/forms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,7 @@ Creating a Simple Form
Suppose you're building a simple todo list application that will need to
display "tasks". Because your users will need to edit and create tasks, you're
going to need to build a form. But before you begin, first focus on the generic
``Task`` class that represents and stores the data for a single task:

.. code-block:: php
``Task`` class that represents and stores the data for a single task::

// src/Acme/TaskBundle/Entity/Task.php
namespace Acme\TaskBundle\Entity;
Expand Down Expand Up @@ -742,9 +740,7 @@ Creating Form Classes
As you've seen, a form can be created and used directly in a controller.
However, a better practice is to build the form in a separate, standalone PHP
class, which can then be reused anywhere in your application. Create a new class
that will house the logic for building the task form:

.. code-block:: php
that will house the logic for building the task form::

// src/Acme/TaskBundle/Form/Type/TaskType.php
namespace Acme\TaskBundle\Form\Type;
Expand All @@ -768,9 +764,7 @@ that will house the logic for building the task form:

This new class contains all the directions needed to create the task form
(note that the ``getName()`` method should return a unique identifier for this
form "type"). It can be used to quickly build a form object in the controller:

.. code-block:: php
form "type"). It can be used to quickly build a form object in the controller::

// src/Acme/TaskBundle/Controller/DefaultController.php

Expand Down Expand Up @@ -1068,7 +1062,7 @@ The ``field_row`` form fragment is used when rendering most fields via the
fragment defined above, add the following to the top of the template that
renders the form:

.. configuration-block:: php
.. configuration-block::

.. code-block:: html+jinja

Expand Down Expand Up @@ -1373,7 +1367,7 @@ section.
The ``intention`` option is optional but greatly enhances the security of
the generated token by making it different for each form.

.. index:
.. index::
single: Forms; With no class

Using a Form without a Class
Expand Down Expand Up @@ -1413,10 +1407,10 @@ By default, a form actually assumes that you want to work with arrays of
data, instead of an object. There are exactly two ways that you can change
this behavior and tie the form to an object instead:

1. Pass an object when creating the form (as the first argument to ``createFormBuilder``
#. Pass an object when creating the form (as the first argument to ``createFormBuilder``
or the second argument to ``createForm``);

2. Declare the ``data_class`` option on your form.
#. Declare the ``data_class`` option on your form.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some of these may not work - I won't know until I render it. The markup has to be just right with multi-line numbers for sphinx to recognize that we're continuing to (2) and not starting a new list.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't know that, I will render it tomorrow on my own computer and check them all out, please wait merging this PR as long as I didn't test it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@weaverryan I just tested it and all ordered lists are rendered the way it needs to be rendered.

(I have also fixed the other error)

If you *don't* do either of these, then the form will return the data as
an array. In this example, since ``$defaultData`` is not an object (and
Expand All @@ -1426,9 +1420,7 @@ an array.
.. tip::

You can also access POST values (in this case "name") directly through
the request object, like so:

.. code-block:: php
the request object, like so::

$this->get('request')->request->get('name');

Expand Down
40 changes: 19 additions & 21 deletions book/from_flat_php_to_symfony2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ persisted to the database. Writing in flat PHP is quick and dirty:
$result = mysql_query('SELECT id, title FROM post', $link);
?>

<!doctype html>
<!DOCTYPE html>
<html>
<head>
<title>List of Posts</title>
Expand Down Expand Up @@ -70,6 +70,7 @@ to maintain. There are several problems that need to be addressed:
way to reuse any part of the application for other "pages" of the blog.

.. note::

Another problem not mentioned here is the fact that the database is
tied to MySQL. Though not covered here, Symfony2 fully integrates `Doctrine`_,
a library dedicated to database abstraction and mapping.
Expand Down Expand Up @@ -106,7 +107,7 @@ is primarily an HTML file that uses a template-like PHP syntax:

.. code-block:: html+php

<!doctype html>
<!DOCTYPE html>
<html>
<head>
<title>List of Posts</title>
Expand Down Expand Up @@ -211,6 +212,7 @@ that by creating a new ``layout.php`` file:
.. code-block:: html+php

<!-- templates/layout.php -->
<!DOCTYPE html>
<html>
<head>
<title><?php echo $title ?></title>
Expand Down Expand Up @@ -366,9 +368,9 @@ on the requested URI:

// route the request internally
$uri = $_SERVER['REQUEST_URI'];
if ($uri == '/index.php') {
if ('/index.php' == $uri) {
list_action();
} elseif ($uri == '/index.php/show' && isset($_GET['id'])) {
} elseif ('/index.php/show' == $uri && isset($_GET['id'])) {
show_action($_GET['id']);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I don't like these changes. Is there a coding standard that we're following to do this? I know you often see things like if (false === $var), but I'm not as convinced with this part - just seems less readable/natural

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, I don't really like it too. But it is used in the Symfony core code everywhere, for instance: BrowserKit\History, HttpKernel\HttpKernel, Routing\Route and FrameworkBundle\EventListener\SessionListener, and I was mentioned on this in one of my first PRs (#1393, the outdated diff).

It seems less natural, but it is more consistent with the way assertions work in PHPunit:

$this->assertEquals('expected', 'input');
// if statements
if ('expected' == 'input')

// inconsistent
$this->assertEquals('expected', 'input');
if ('input' == 'expected')

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found the "Yoda syntax" less natural at first as well. However, the "Yoda syntax" causes a syntax error to be reported, instead of allowing improper assignment to occur, when a programmer makes a mistake and types "=" rather than "==" (or similar).

I couldn't find anything on the symfony coding standards page ( http://symfony.com/doc/2.0/contributing/code/standards.html ) listing this syntax style as a requirement, but both control structure examples on that page use this syntax style.

} else {
header('Status: 404 Not Found');
Expand Down Expand Up @@ -466,9 +468,9 @@ the HTTP response being returned. Use them to improve the blog:
$request = Request::createFromGlobals();

$uri = $request->getPathInfo();
if ($uri == '/') {
if ('/' == $uri) {
$response = list_action();
} elseif ($uri == '/show' && $request->query->has('id')) {
} elseif ('/show' == $uri && $request->query->has('id')) {
$response = show_action($request->query->get('id'));
} else {
$html = '<html><body><h1>Page Not Found</h1></body></html>';
Expand Down Expand Up @@ -537,11 +539,8 @@ from scratch, you could at least use Symfony's standalone `Routing`_ and
`Templating`_ components, which already solve these problems.

Instead of re-solving common problems, you can let Symfony2 take care of
them for you. Here's the same sample application, now built in Symfony2:

.. code-block:: html+php
them for you. Here's the same sample application, now built in Symfony2::

<?php
// src/Acme/BlogBundle/Controller/BlogController.php
namespace Acme\BlogBundle\Controller;

Expand All @@ -563,7 +562,8 @@ them for you. Here's the same sample application, now built in Symfony2:
$post = $this->get('doctrine')
->getEntityManager()
->getRepository('AcmeBlogBundle:Post')
->find($id);
->find($id)
;

if (!$post) {
// cause the 404 page not found to be displayed
Expand Down Expand Up @@ -602,7 +602,7 @@ The layout is nearly identical:
.. code-block:: html+php

<!-- app/Resources/views/layout.html.php -->
<!doctype html>
<!DOCTYPE html>
<html>
<head>
<title><?php echo $view['slots']->output('title', 'Default title') ?></title>
Expand Down Expand Up @@ -635,11 +635,8 @@ A routing configuration map provides this information in a readable format:
Now that Symfony2 is handling all the mundane tasks, the front controller
is dead simple. And since it does so little, you'll never have to touch
it once it's created (and if you use a Symfony2 distribution, you won't
even need to create it!):
even need to create it!)::

.. code-block:: html+php

<?php
// web/app.php
require_once __DIR__.'/../app/bootstrap.php';
require_once __DIR__.'/../app/AppKernel.php';
Expand Down Expand Up @@ -667,18 +664,18 @@ migrating the blog from flat PHP to Symfony2 has improved life:

* Your application now has **clear and consistently organized code** (though
Symfony doesn't force you into this). This promotes **reusability** and
allows for new developers to be productive in your project more quickly.
allows for new developers to be productive in your project more quickly;

* 100% of the code you write is for *your* application. You **don't need
to develop or maintain low-level utilities** such as :ref:`autoloading<autoloading-introduction-sidebar>`,
:doc:`routing</book/routing>`, or rendering :doc:`controllers</book/controller>`.
:doc:`routing</book/routing>`, or rendering :doc:`controllers</book/controller>`;

* Symfony2 gives you **access to open source tools** such as Doctrine and the
Templating, Security, Form, Validation and Translation components (to name
a few).
a few);

* The application now enjoys **fully-flexible URLs** thanks to the ``Routing``
component.
component;

* Symfony2's HTTP-centric architecture gives you access to powerful tools
such as **HTTP caching** powered by **Symfony2's internal HTTP cache** or
Expand All @@ -701,6 +698,7 @@ for example, the list template written in Twig:

{# src/Acme/BlogBundle/Resources/views/Blog/list.html.twig #}
{% extends "::layout.html.twig" %}

{% block title %}List of Posts{% endblock %}

{% block body %}
Expand All @@ -721,7 +719,7 @@ The corresponding ``layout.html.twig`` template is also easier to write:
.. code-block:: html+jinja

{# app/Resources/views/layout.html.twig #}
<!doctype html>
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Default title{% endblock %}</title>
Expand Down
Loading