Skip to content

[WIP] re-read of http-foundation component docs #2435

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 12 commits into from
Jun 12, 2013
Merged

[WIP] re-read of http-foundation component docs #2435

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
a3ce775
fix typo - missing word
joelclermont Mar 30, 2013
2d25c5e
typo - change to
joelclermont Mar 30, 2013
59f8e5b
change headers example to use a request header (not a response header)
joelclermont Mar 30, 2013
adc045b
decorate php function with link to manual
joelclermont Mar 30, 2013
8290eb9
add more descriptive text for book link
joelclermont Mar 30, 2013
78ece84
Shorten line under 80 chars
joelclermont Mar 30, 2013
0338f96
lower case request since it's not talking about the class
joelclermont Mar 30, 2013
6f9c74e
change to URI to be more consistent. fix typo. lower case Session
joelclermont Mar 30, 2013
66aad4a
change query to request to be more accurate
joelclermont Mar 30, 2013
868815c
lower case request
joelclermont Mar 30, 2013
6a5e3d9
change final bullet to end with period
joelclermont Mar 30, 2013
20a75cb
backtick Request. link to Request API
joelclermont Mar 31, 2013
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
35 changes: 19 additions & 16 deletions components/http_foundation/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ You can install the component in many different ways:
Request
-------

The most common way to create request is to base it on the current PHP global
The most common way to create a request is to base it on the current PHP global
variables with
:method:`Symfony\\Component\\HttpFoundation\\Request::createFromGlobals`::

Expand Down Expand Up @@ -61,12 +61,12 @@ can be accessed via several public properties:

* ``attributes``: no equivalent - used by your app to store other data (see :ref:`below<component-foundation-attributes>`)

* ``files``: equivalent of ``$_FILE``;
* ``files``: equivalent of ``$_FILES``;

* ``server``: equivalent of ``$_SERVER``;

* ``headers``: mostly equivalent to a sub-set of ``$_SERVER``
(``$request->headers->get('Content-Type')``).
(``$request->headers->get('user-agent')``).
Copy link
Member

Choose a reason for hiding this comment

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

Both are correct IMO

Copy link
Contributor Author

Choose a reason for hiding this comment

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

You're right. Content-type could be used on a POST or PUT. Might I suggest that user-agent still could be a better choice since all requests are likely to have this. If someone is trying out code samples, they might be confused why content-type is coming up null. What do you think?

Copy link
Member

Choose a reason for hiding this comment

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

Both are good, so I'm cool with user agent. But I think we should have it be User-Agent - it's true that case doesn't matter when getting the headers, but User-Agent may be a little more recognizable as a header.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok, I will make the change. I'm also planning on picking this back up over the weekend to finish the WIP. Thanks for the feedback.


Each property is a :class:`Symfony\\Component\\HttpFoundation\\ParameterBag`
instance (or a sub-class of), which is a data holder class:
Expand Down Expand Up @@ -128,7 +128,7 @@ has some methods to filter the input values:
parameter value converted to integer;

* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::filter`: Filters the
parameter by using the PHP ``filter_var()`` function.
parameter by using the PHP :phpfunction:`filter_var` function.

All getters takes up to three arguments: the first one is the parameter name
and the second one is the default value to return if the parameter does not
Expand All @@ -150,7 +150,7 @@ When PHP imports the request query, it handles request parameters like
``foo[bar]=bar`` in a special way as it creates an array. So you can get the
``foo`` parameter and you will get back an array with a ``bar`` element. But
sometimes, you might want to get the value for the "original" parameter name:
``foo[bar]``. This is possible with all the `ParameterBag` getters like
``foo[bar]``. This is possible with all the ``ParameterBag`` getters like
:method:`Symfony\\Component\\HttpFoundation\\Request::get` via the third
argument::

Expand All @@ -172,7 +172,8 @@ thanks to the public ``attributes`` property, which is also an instance of
:class:`Symfony\\Component\\HttpFoundation\\ParameterBag`. This is mostly used
to attach information that belongs to the Request and that needs to be
accessed from many different points in your application. For information
on how this is used in the Symfony2 framework, see :ref:`read more<book-fundamentals-attributes>`.
on how this is used in the Symfony2 framework, see
:ref:`the Symfony2 book<book-fundamentals-attributes>`.

Identifying a Request
~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -188,8 +189,8 @@ this is done via the "path info" of the request, which can be accessed via the
Simulating a Request
~~~~~~~~~~~~~~~~~~~~

Instead of creating a Request based on the PHP globals, you can also simulate
a Request::
Instead of creating a request based on the PHP globals, you can also simulate
a request::

$request = Request::create(
'/hello-world',
Expand All @@ -198,9 +199,9 @@ a Request::
);

The :method:`Symfony\\Component\\HttpFoundation\\Request::create` method
creates a request based on a path info, a method and some parameters (the
creates a request based on a URI, a method and some parameters (the
query parameters or the request ones depending on the HTTP method); and of
course, you an also override all other variables as well (by default, Symfony
course, you can also override all other variables as well (by default, Symfony
creates sensible defaults for all the PHP global variables).

Based on such a request, you can override the PHP global variables via
Expand All @@ -210,19 +211,19 @@ Based on such a request, you can override the PHP global variables via

.. tip::

You can also duplicate an existing query via
You can also duplicate an existing request via
:method:`Symfony\\Component\\HttpFoundation\\Request::duplicate` or
change a bunch of parameters with a single call to
:method:`Symfony\\Component\\HttpFoundation\\Request::initialize`.

Accessing the Session
~~~~~~~~~~~~~~~~~~~~~

If you have a session attached to the Request, you can access it via the
If you have a session attached to the request, you can access it via the
:method:`Symfony\\Component\\HttpFoundation\\Request::getSession` method;
the
:method:`Symfony\\Component\\HttpFoundation\\Request::hasPreviousSession`
method tells you if the request contains a Session which was started in one of
method tells you if the request contains a session which was started in one of
the previous requests.

Accessing `Accept-*` Headers Data
Expand All @@ -238,13 +239,15 @@ by using the following methods:
returns the list of accepted languages ordered by descending quality;

* :method:`Symfony\\Component\\HttpFoundation\\Request::getCharsets`:
returns the list of accepted charsets ordered by descending quality;
returns the list of accepted charsets ordered by descending quality.

Accessing other Data
~~~~~~~~~~~~~~~~~~~~

The Request class has many other methods that you can use to access the
request information. Have a look at the API for more information about them.
The ``Request`` class has many other methods that you can use to access the
request information. Have a look at
:class:`the Request API<Symfony\\Component\\HttpFoundation\\Request>`
for more information about them.

Response
--------
Expand Down