Skip to content

S
Silex
Commit 919c32c7 authored by WouterJ's avatar WouterJ
Browse files
Options

Some doc fixes

parent 7ae0fd8b
Show whitespace changes
Inline Side-by-side
Showing with 82 additions and 72 deletions
doc/intro.rst
View file @ 919c32c7
......@@ -2,7 +2,7 @@ Introduction
============
Silex is a PHP microframework for PHP 5.3. It is built on the shoulders of
Symfony2 and Pimple and also inspired by sinatra.
Symfony2 and Pimple and also inspired by Sinatra_.
A microframework provides the guts for building simple single-file apps. Silex
aims to be:
......@@ -18,10 +18,12 @@ aims to be:
In a nutshell, you define controllers and map them to routes, all in one step.
**Let's go!**::
Usage
-----
// web/index.php
.. code-block:: php
// web/index.php
require_once __DIR__.'/../vendor/autoload.php';
$app = new Silex\Application();
......@@ -35,14 +37,21 @@ In a nutshell, you define controllers and map them to routes, all in one step.
All that is needed to get access to the Framework is to include the
autoloader.
Next we define a route to ``/hello/{name}`` that matches for ``GET`` requests.
Next a route for ``/hello/{name}`` that matches for ``GET`` requests is defined.
When the route matches, the function is executed and the return value is sent
back to the client.
Finally, the app is run. Visit ``/hello/world`` to see the result. It's really
that easy!
Installing Silex is as easy as it can get. `Download`_ the archive file,
extract it, and you're done!
Installation
------------
Installing Silex is as easy as it can get. The recommend method is using
Composer_ and requiring `silex/silex`_. Another way is to `download`_ the
archive file and extract it.
.. _Download: http://silex.sensiolabs.org/download
.. _Sinatra: http://www.sinatrarb.com/
.. _Composer: http://getcomposer.org/
.. _`download`: http://silex.sensiolabs.org/download
.. _`silex/silex`: https://packagist.org/packages/silex/silex
doc/usage.rst
View file @ 919c32c7
......@@ -18,8 +18,8 @@ it, you should have the following directory structure:
└── web
└── index.php
If you want more flexibility, use Composer instead. Create a
``composer.json``:
If you want more flexibility, use Composer_ instead. Create a
``composer.json`` file and put this in it:
.. code-block:: json
......@@ -60,17 +60,16 @@ file and create an instance of ``Silex\Application``. After your controller
definitions, call the ``run`` method on your application::
// web/index.php
require_once __DIR__.'/../vendor/autoload.php';
$app = new Silex\Application();
// definitions
// ... definitions
$app->run();
Then, you have to configure your web server (read the :doc:`dedicated chapter
<web_servers>` for more information).
Then, you have to configure your web server (read the
:doc:`dedicated chapter <web_servers>` for more information).
.. tip::
......@@ -81,9 +80,9 @@ Then, you have to configure your web server (read the :doc:`dedicated chapter
.. tip::
If your application is hosted behind a reverse proxy at address $ip, and you
want Silex to trust the ``X-Forwarded-For*`` headers, you will need to run
your application like this::
If your application is hosted behind a reverse proxy at address ``$ip``,
and you want Silex to trust the ``X-Forwarded-For*`` headers, you will
need to run your application like this::
use Symfony\Component\HttpFoundation\Request;
......@@ -109,7 +108,7 @@ A route pattern consists of:
The controller is defined using a closure like this::
function () {
// do something
// ... do something
}
Closures are anonymous functions that may import state from outside of their
......@@ -119,13 +118,13 @@ import local variables of that function.
.. note::
Closures that do not import scope are referred to as lambdas. Because in
PHP all anonymous functions are instances of the ``Closure`` class, we
will not make a distinction here.
Closures that do not import scope are referred to as lambdas. Because all
anonymous functions are instances of the ``Closure`` class in PHP, the
documentation will not make a distinction here.
The return value of the closure becomes the content of the page.
Example GET route
Example GET Route
~~~~~~~~~~~~~~~~~
Here is an example definition of a ``GET`` route::
......@@ -151,10 +150,10 @@ Here is an example definition of a ``GET`` route::
Visiting ``/blog`` will return a list of blog post titles. The ``use``
statement means something different in this context. It tells the closure to
import the $blogPosts variable from the outer scope. This allows you to use it
from within the closure.
import the ``$blogPosts`` variable from the outer scope. This allows you to
use it from within the closure.
Dynamic routing
Dynamic Routing
~~~~~~~~~~~~~~~
Now, you can create another controller for viewing individual blog posts::
......@@ -176,15 +175,15 @@ closure.
The current ``Application`` is automatically injected by Silex to the Closure
thanks to the type hinting.
When the post does not exist, we are using ``abort()`` to stop the request
early. It actually throws an exception, which we will see how to handle later
When the post does not exist, you are using ``abort()`` to stop the request
early. It actually throws an exception, which you will see how to handle later
on.
Example POST route
Example POST Route
~~~~~~~~~~~~~~~~~~
POST routes signify the creation of a resource. An example for this is a
feedback form. We will use the ``mail`` function to send an e-mail::
feedback form. You will use the ``mail`` function to send an e-mail::
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
......@@ -204,14 +203,12 @@ It is pretty straightforward.
included that you can use instead of ``mail()``.
The current ``request`` is automatically injected by Silex to the Closure
thanks to the type hinting. It is an instance of `Request
<http://api.symfony.com/master/Symfony/Component/HttpFoundation/Request.html>`_,
so you can fetch variables using the request ``get`` method.
thanks to the type hinting. It is an instance of
Request_, so you can fetch variables using the request ``get`` method.
Instead of returning a string we are returning an instance of `Response
<http://api.symfony.com/master/Symfony/Component/HttpFoundation/Response.html>`_.
This allows setting an HTTP status code, in this case it is set to ``201
Created``.
Instead of returning a string you are returning an instance of Response_.
This allows setting an HTTP status code, in this case it is set to
``201 Created``.
.. note::
......@@ -225,11 +222,11 @@ You can create controllers for most HTTP methods. Just call one of these
methods on your application: ``get``, ``post``, ``put``, ``delete``::
$app->put('/blog/{id}', function ($id) {
...
// ...
});
$app->delete('/blog/{id}', function ($id) {
...
// ...
});
.. tip::
......@@ -237,15 +234,17 @@ methods on your application: ``get``, ``post``, ``put``, ``delete``::
Forms in most web browsers do not directly support the use of other HTTP
methods. To use methods other than GET and POST you can utilize a special
form field with a name of ``_method``. The form's ``method`` attribute must
be set to POST when using this field::
be set to POST when using this field:
.. code-block:: html
<form action="/my/target/route/" method="post">
...
<!-- ... -->
<input type="hidden" id="_method" name="_method" value="PUT" />
</form>
If using Symfony Components 2.2+ you will need to explicitly enable this
method override::
If you are using Symfony Components 2.2+, you will need to explicitly
enable this method override::
use Symfony\Component\HttpFoundation\Request;
......@@ -256,16 +255,16 @@ You can also call ``match``, which will match all methods. This can be
restricted via the ``method`` method::
$app->match('/blog', function () {
...
// ...
});
$app->match('/blog', function () {
...
// ...
})
->method('PATCH');
$app->match('/blog', function () {
...
// ...
})
->method('PUT|POST');
......@@ -274,35 +273,34 @@ restricted via the ``method`` method::
The order in which the routes are defined is significant. The first
matching route will be used, so place more generic routes at the bottom.
Route variables
Route Variables
~~~~~~~~~~~~~~~
As it has been shown before you can define variable parts in a route like
this::
$app->get('/blog/{id}', function ($id) {
...
// ...
});
It is also possible to have more than one variable part, just make sure the
closure arguments match the names of the variable parts::
$app->get('/blog/{postId}/{commentId}', function ($postId, $commentId) {
...
// ...
});
While it's not suggested, you could also do this (note the switched
While it's not recommend, you could also do this (note the switched
arguments)::
$app->get('/blog/{postId}/{commentId}', function ($commentId, $postId) {
...
// ...
});
You can also ask for the current Request and Application objects::
$app->get('/blog/{id}', function (Application $app, Request $request, $id) {
...
// ...
});
.. note::
......@@ -311,10 +309,10 @@ You can also ask for the current Request and Application objects::
based on the type hinting and not on the variable name::
$app->get('/blog/{id}', function (Application $foo, Request $bar, $id) {
...
// ...
});
Route variables converters
Route Variables Converters
~~~~~~~~~~~~~~~~~~~~~~~~~~
Before injecting the route variables into the controller, you can apply some
......@@ -360,33 +358,33 @@ The following will make sure the ``id`` argument is numeric, since ``\d+``
matches any amount of digits::
$app->get('/blog/{id}', function ($id) {
...
// ...
})
->assert('id', '\d+');
You can also chain these calls::
$app->get('/blog/{postId}/{commentId}', function ($postId, $commentId) {
...
// ...
})
->assert('postId', '\d+')
->assert('commentId', '\d+');
Default values
Default Values
~~~~~~~~~~~~~~
You can define a default value for any route variable by calling ``value`` on
the ``Controller`` object::
$app->get('/{pageName}', function ($pageName) {
...
// ...
})
->value('pageName', 'index');
This will allow matching ``/``, in which case the ``pageName`` variable will
have the value ``index``.
Named routes
Named Routes
~~~~~~~~~~~~
Some providers (such as ``UrlGeneratorProvider``) can make use of named
......@@ -395,45 +393,44 @@ really be used. You can give a route a name by calling ``bind`` on the
``Controller`` object that is returned by the routing methods::
$app->get('/', function () {
...
// ...
})
->bind('homepage');
$app->get('/blog/{id}', function ($id) {
...
// ...
})
->bind('blog_post');
.. note::
It only makes sense to name routes if you use providers that make use of
the ``RouteCollection``.
Controllers in classes
Controllers in Classes
~~~~~~~~~~~~~~~~~~~~~~
If you don't want to use anonymous functions, you can also define your
controllers as methods. By using the ``ControllerClass::methodName`` syntax,
you can tell Silex to lazily create the controller object for you::
$app->get('/', 'Igorw\Foo::bar');
$app->get('/', 'Acme\Foo::bar');
use Silex\Application;
use Symfony\Component\HttpFoundation\Request;
namespace Igorw
namespace Acme
{
class Foo
{
public function bar(Request $request, Application $app)
{
...
// ...
}
}
}
This will load the ``Igorw\Foo`` class on demand, create an instance and call
This will load the ``Acme\Foo`` class on demand, create an instance and call
the ``bar`` method to get the response. You can use ``Request`` and
``Silex\Application`` type hints to get ``$request`` and ``$app`` injected.
......@@ -463,9 +460,9 @@ the defaults for new controllers.
The global configuration does not apply to controller providers you might
mount as they have their own global configuration (read the
:doc:`dedicated chapter<organizing_controllers>` for more information).
:doc:`dedicated chapter <organizing_controllers>` for more information).
Error handlers
Error Handlers
--------------
If some part of your code throws an exception you will want to display some
......@@ -511,7 +508,7 @@ You can restrict an error handler to only handle some Exception classes by
setting a more specific type hint for the Closure argument::
$app->error(function (\LogicException $e, $code) {
// this handler will only \LogicException exceptions
// this handler will only handle \LogicException exceptions
// and exceptions that extends \LogicException
});
......@@ -521,8 +518,7 @@ once a response is returned, the following handlers are ignored.
.. note::
Silex ships with a provider for `Monolog
<https://github.com/Seldaek/monolog>`_ which handles logging of errors.
Silex ships with a provider for Monolog_ which handles logging of errors.
Check out the *Providers* chapter for details.
.. tip::
......@@ -540,7 +536,7 @@ once a response is returned, the following handlers are ignored.
return;
}
// logic to handle the error and return a Response
// ... logic to handle the error and return a Response
});
The error handlers are also called when you use ``abort`` to abort a request
......@@ -605,6 +601,7 @@ response for you::
if (!$user) {
$error = array('message' => 'The user was not found.');
return $app->json($error, 404);
}
......@@ -744,3 +741,7 @@ to prevent Cross-Site-Scripting attacks.
});
.. _download: http://silex.sensiolabs.org/download
.. _Composer: http://getcomposer.org/
.. _Request: http://api.symfony.com/master/Symfony/Component/HttpFoundation/Request.html
.. _Response: http://api.symfony.com/master/Symfony/Component/HttpFoundation/Response.html
.. _Monolog: https://github.com/Seldaek/monolog
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment