Skip to content

S
Silex
Commit a7894570 authored by Fabien Potencier's avatar Fabien Potencier
Browse files
Options

updated documentation

parent 5a20c1cc
Show whitespace changes
Inline Side-by-side
Showing with 142 additions and 141 deletions
doc/contributing.rst
View file @ a7894570
......@@ -2,7 +2,7 @@ Contributing
============
We are open to contributions to the Silex code. If you find
a bug or want to contribute an extension, just follow these
a bug or want to contribute a provider, just follow these
steps.
* Fork `the Silex repository <https://github.com/fabpot/Silex>`_
......
doc/index.rst
View file @ a7894570
......@@ -7,7 +7,7 @@ Silex
intro
usage
services
extensions
providers
testing
internals
contributing
......
doc/internals.rst
View file @ a7894570
......@@ -49,7 +49,7 @@ ControllerCollection
One of the goals of exposing the `RouteCollection
<http://api.symfony.com/2.0/Symfony/Component/Routing/RouteCollection.html>`_
was to make it mutable, so extensions could add stuff to it.
was to make it mutable, so providers could add stuff to it.
The challenge here is the fact that routes know nothing
about their name. The name only has meaning in context
of the ``RouteCollection`` and cannot be changed.
......
doc/extensions.rst → doc/providers.rst
View file @ a7894570
Extensions
==========
Providers
=========
Extensions allow the developer to reuse parts of an application into another
one. Silex provides two interfaces for extensions: `ExtensionInterface` for
services and `ControllersExtensionInterface` for controllers.
Providers allow the developer to reuse parts of an application into another
one. Silex provides two types of providers defined by two interfaces:
`ServiceProviderInterface` for services and `ControllerProviderInterface` for
controllers.
Service Extensions
------------------
Service Providers
-----------------
Loading extensions
~~~~~~~~~~~~~~~~~~
Loading providers
~~~~~~~~~~~~~~~~~
In order to load and use a service extension, you must register it on the
In order to load and use a service provider, you must register it on the
application::
$app = new Silex\Application();
$app->register(new Acme\DatabaseExtension());
$app->register(new Acme\DatabaseProvider());
You can also provide some parameters as a second argument. These
will be set **before** the extension is registered::
will be set **before** the provider is registered::
$app->register(new Acme\DatabaseExtension(), array(
$app->register(new Acme\DatabaseProvider(), array(
'database.dsn' => 'mysql:host=localhost;dbname=myapp',
'database.user' => 'root',
'database.password' => 'secret_root_password',
......@@ -31,52 +32,52 @@ Conventions
~~~~~~~~~~~
You need to watch out in what order you do certain things when
interacting with extensions. Just keep to these rules:
interacting with providers. Just keep to these rules:
* Class paths (for the autoloader) must be defined **before**
the extension is registered. Passing it as a second argument
the provider is registered. Passing it as a second argument
to ``Application::register`` qualifies too, because it sets
the passed parameters first.
*Reason: The extension will set up the autoloader at
extension register time. If the class path is not set
*Reason: The provider will set up the autoloader at
provider register time. If the class path is not set
at that point, no autoloader can be registered.*
* Overriding existing services must occur **after** the
extension is registered.
provider is registered.
*Reason: If the services already exist, the extension
*Reason: If the services already exist, the provider
will overwrite it.*
* You can set parameters any time before the service is
accessed.
Make sure to stick to this behavior when creating your
own extensions.
Included extensions
~~~~~~~~~~~~~~~~~~~
There are a few extensions that you get out of the box.
All of these are within the ``Silex\Extension`` namespace.
own providers.
* :doc:`DoctrineExtension <extensions/doctrine>`
* :doc:`MonologExtension <extensions/monolog>`
* :doc:`SessionExtension <extensions/session>`
* :doc:`SwiftmailerExtension <extensions/swiftmailer>`
* :doc:`SymfonyBridgesExtension <extensions/symfony_bridges>`
* :doc:`TwigExtension <extensions/twig>`
* :doc:`TranslationExtension <extensions/translation>`
* :doc:`UrlGeneratorExtension <extensions/url_generator>`
* :doc:`ValidatorExtension <extensions/validator>`
* :doc:`HttpCacheExtension <extensions/http_cache>`
Included providers
~~~~~~~~~~~~~~~~~~
Creating an extension
~~~~~~~~~~~~~~~~~~~~~
There are a few provider that you get out of the box.
All of these are within the ``Silex\Provider`` namespace.
* :doc:`DoctrineProvider <providers/doctrine>`
* :doc:`MonologProvider <providers/monolog>`
* :doc:`SessionProvider <providers/session>`
* :doc:`SwiftmailerServiceProvider <providers/swiftmailer>`
* :doc:`SymfonyBridgesServiceProvider <providers/symfony_bridges>`
* :doc:`TwigProvider <providers/twig>`
* :doc:`TranslationProvider <providers/translation>`
* :doc:`UrlGeneratorProvider <providers/url_generator>`
* :doc:`ValidatorProvider <providers/validator>`
* :doc:`HttpCacheProvider <providers/http_cache>`
Creating a provider
~~~~~~~~~~~~~~~~~~~
Extensions must implement the ``Silex\ExtensionInterface``::
Providers must implement the ``Silex\ServiceProviderInterface``::
interface ExtensionInterface
interface ServiceProviderInterface
{
function register(Application $app);
}
......@@ -86,14 +87,14 @@ implements the ``register`` method. In this method you must
define services on the application which then may make use
of other services and parameters.
Here is an example of such an extension::
Here is an example of such a provider::
namespace Acme;
use Silex\Application;
use Silex\ExtensionInterface;
use Silex\ServiceProviderInterface;
class HelloExtension implements ExtensionInterface
class HelloProvider implements ServiceProviderInterface
{
public function register(Application $app)
{
......@@ -111,11 +112,11 @@ closure. It takes a name argument and will return
``hello.default_name`` if no name is given. If the default
is also missing, it will use an empty string.
You can now use this extension as follows::
You can now use this provider as follows::
$app = new Silex\Application();
$app->register(new Acme\HelloExtension(), array(
$app->register(new Acme\HelloProvider(), array(
'hello.default_name' => 'Igor',
));
......@@ -131,9 +132,9 @@ query string, so the request path would have to be ``/hello?name=Fabien``.
Class loading
~~~~~~~~~~~~~
Extensions are great for tying in external libraries as you
can see by looking at the ``MonologExtension`` and
``TwigExtension``. If the library is decent and follows the
Providers are great for tying in external libraries as you
can see by looking at the ``MonologProvider`` and
``TwigProvider``. If the library is decent and follows the
`PSR-0 Naming Standard <http://groups.google.com/group/php-standards/web/psr-0-final-proposal>`_
or the PEAR Naming Convention, it is possible to autoload
classes using the ``UniversalClassLoader``.
......@@ -146,9 +147,9 @@ Here is an example of how to use it (based on `Buzz <https://github.com/kriswall
namespace Acme;
use Silex\Application;
use Silex\ExtensionInterface;
use Silex\ServiceProviderInterface;
class BuzzExtension implements ExtensionInterface
class BuzzProvider implements ServiceProviderInterface
{
public function register(Application $app)
{
......@@ -161,9 +162,9 @@ Here is an example of how to use it (based on `Buzz <https://github.com/kriswall
}
This allows you to simply provide the class path as an
option when registering the extension::
option when registering the provider::
$app->register(new BuzzExtension(), array(
$app->register(new BuzzProvider(), array(
'buzz.class_path' => __DIR__.'/vendor/buzz/lib',
));
......@@ -173,40 +174,40 @@ option when registering the extension::
instead of ``registerNamespace``, which will use an underscore as directory
delimiter.
Controllers Extensions
----------------------
Controllers providers
---------------------
Loading extensions
~~~~~~~~~~~~~~~~~~
Loading providers
~~~~~~~~~~~~~~~~~
In order to load and use a controller extension, you must "mount" its
In order to load and use a controller provider, you must "mount" its
controllers under a path::
$app = new Silex\Application();
$app->mount('/blog', new Acme\BlogExtension());
$app->mount('/blog', new Acme\BlogProvider());
All controllers defined by the extension will now be available under the
All controllers defined by the provider will now be available under the
`/blog` path.
Creating an extension
~~~~~~~~~~~~~~~~~~~~~
Creating a provider
~~~~~~~~~~~~~~~~~~~
Extensions must implement the ``Silex\ControllersExtensionInterface``::
Providers must implement the ``Silex\ControllerProviderInterface``::
interface ControllersExtensionInterface
interface ControllerProviderInterface
{
function connect(Application $app);
}
Here is an example of such an extension::
Here is an example of such a provider::
namespace Acme;
use Silex\Application;
use Silex\ControllersExtensionInterface;
use Silex\ControllerProviderInterface;
class HelloExtension implements ControllersExtensionInterface
class HelloProvider implements ControllerProviderInterface
{
public function connect(Application $app)
{
......@@ -228,17 +229,17 @@ defined (like ``get``, ``post``, ``match``, ...).
The ``Application`` class acts in fact as a proxy for these methods.
You can now use this extension as follows::
You can now use this provider as follows::
$app = new Silex\Application();
$app->connect('/blog', new Acme\HelloExtension());
$app->connect('/blog', new Acme\HelloProvider());
In this example, the ``/blog/`` path now references the controller defined in
the extension.
the provider.
.. tip::
You can also define an extension that implements both the service and the
controller extension interface and package in the same class the services
You can also define an provider that implements both the service and the
controller provider interface and package in the same class the services
needed to make your controllers work.
doc/extensions/doctrine.rst → doc/providers/doctrine.rst
View file @ a7894570
DoctrineExtension
=================
DoctrineProvider
================
The *DoctrineExtension* provides integration with the `Doctrine DBAL
The *DoctrineProvider* provides integration with the `Doctrine DBAL
<http://www.doctrine-project.org/projects/dbal>`_ for easy database acccess.
.. note::
......@@ -58,7 +58,7 @@ Registering
Make sure you place a copy of *Doctrine DBAL* in ``vendor/doctrine-dbal``
and *Doctrine Common* in ``vendor/doctrine-common``::
$app->register(new Silex\Extension\DoctrineExtension(), array(
$app->register(new Silex\Provider\DoctrineProvider(), array(
'db.options' => array(
'driver' => 'pdo_sqlite',
'path' => __DIR__.'/app.db',
......@@ -70,7 +70,7 @@ and *Doctrine Common* in ``vendor/doctrine-common``::
Usage
-----
The Doctrine extension provides a ``db`` service. Here is a usage
The Doctrine provider provides a ``db`` service. Here is a usage
example::
$app->get('/blog/show/{id}', function ($id) use ($app) {
......@@ -84,12 +84,12 @@ example::
Using multiple databases
------------------------
The Doctrine extension can allow access to multiple databases. In order to
The Doctrine provider can allow access to multiple databases. In order to
configure the data sources, replace the **db.options** with **dbs.options**.
**dbs.options** is an array of configurations where keys are connection names
and values are options::
$app->register(new Silex\Extension\DoctrineExtension(), array(
$app->register(new Silex\Provider\DoctrineProvider(), array(
'dbs.options' => array (
'mysql_read' => array(
'driver' => 'pdo_mysql',
......
doc/extensions/http_cache.rst → doc/providers/http_cache.rst
View file @ a7894570
HttpCacheExtension
==================
HttpCacheProvider
=================
The *HttpCacheExtension* provides support for the Symfony2 Reverse Proxy.
The *HttpCacheProvider* provides support for the Symfony2 Reverse Proxy.
Parameters
----------
......@@ -23,7 +23,7 @@ Registering
::
$app->register(new Silex\Extension\HttpCacheExtension(), array(
$app->register(new Silex\Provider\HttpCacheProvider(), array(
'http_cache.cache_dir' => __DIR__.'/cache/',
));
......@@ -39,12 +39,12 @@ setting Response HTTP cache headers::
));
});
This extension allows you to use the Symfony2 reverse proxy natively with
This provider allows you to use the Symfony2 reverse proxy natively with
Silex applications by using the `http_cache` service::
$app['http_cache']->run();
The extension also provide ESI support::
The provider also provide ESI support::
$app->get('/', function() {
return new Response(<<<EOF
......
doc/extensions/monolog.rst → doc/providers/monolog.rst
View file @ a7894570
MonologExtension
================
MonologProvider
===============
The *MonologExtension* provides a default logging mechanism
The *MonologProvider* provides a default logging mechanism
through Jordi Boggiano's `Monolog <https://github.com/Seldaek/monolog>`_
library.
......@@ -46,7 +46,7 @@ Registering
Make sure you place a copy of *Monolog* in the ``vendor/monolog``
directory::
$app->register(new Silex\Extension\MonologExtension(), array(
$app->register(new Silex\Provider\MonologProvider(), array(
'monolog.logfile' => __DIR__.'/development.log',
'monolog.class_path' => __DIR__.'/vendor/monolog/src',
));
......@@ -59,7 +59,7 @@ directory::
Usage
-----
The MonologExtension provides a ``monolog`` service. You can use
The MonologProvider provides a ``monolog`` service. You can use
it to add log entries for any logging level through ``addDebug()``,
``addInfo()``, ``addWarning()`` and ``addError()``.
......
doc/extensions/session.rst → doc/providers/session.rst
View file @ a7894570
SessionExtension
================
SessionProvider
===============
The *SessionExtension* provides a service for storing data persistently
The *SessionProvider* provides a service for storing data persistently
between requests.
Parameters
......@@ -40,12 +40,12 @@ Registering
::
$app->register(new Silex\Extension\SessionExtension());
$app->register(new Silex\Provider\SessionProvider());
Usage
-----
The Session extension provides a ``session`` service. Here is an
The Session provider provides a ``session`` service. Here is an
example that authenticates a user and creates a session for him::
use Symfony\Component\HttpFoundation\Response;
......
doc/extensions/swiftmailer.rst → doc/providers/swiftmailer.rst
View file @ a7894570
SwiftmailerExtension
====================
SwiftmailerServiceProvider
==========================
The *SwiftmailerExtension* provides a service for sending
The *SwiftmailerServiceProvider* provides a service for sending
email through the `Swift Mailer <http://swiftmailer.org>`_
library.
......@@ -60,7 +60,7 @@ directory. Make sure you point the class path to ``/lib/classes``.
::
$app->register(new Silex\Extension\SwiftmailerExtension(), array(
$app->register(new Silex\Provider\SwiftmailerServiceProvider(), array(
'swiftmailer.class_path' => __DIR__.'/vendor/swiftmailer/lib/classes',
));
......@@ -72,7 +72,7 @@ directory. Make sure you point the class path to ``/lib/classes``.
Usage
-----
The Swiftmailer extension provides a ``mailer`` service.
The Swiftmailer provider provides a ``mailer`` service.
::
......
doc/extensions/symfony_bridges.rst → doc/providers/symfony_bridges.rst
View file @ a7894570
SymfonyBridgesExtension
=======================
SymfonyBridgesServiceProvider
=============================
The *SymfonyBridgesExtension* provides additional integration between
The *SymfonyBridgesServiceProvider* provides additional integration between
Symfony2 components and libraries.
Parameters
......@@ -13,20 +13,20 @@ Parameters
Twig
----
When the ``SymfonyBridgesExtension`` is enabled, the ``TwigExtension`` will
When the ``SymfonyBridgesServiceProvider`` is enabled, the ``TwigServiceProvider`` will
provide you with the following additional capabilities:
* **UrlGeneratorExtension**: If you are using the ``UrlGeneratorExtension``,
* **UrlGeneratorServiceProvider**: If you are using the ``UrlGeneratorServiceProvider``,
you will get ``path`` and ``url`` helpers for Twig. You can find more
information in the
`Symfony2 Routing documentation <http://symfony.com/doc/current/book/routing.html#generating-urls-from-a-template>`_.
* **TranslationExtension**: If you are using the ``TranslationExtension``,
* **TranslationServiceProvider**: If you are using the ``TranslationServiceProvider``,
you will get ``trans`` and ``transchoice`` helpers for translation in
Twig templates. You can find more information in the
`Symfony2 Translation documentation <http://symfony.com/doc/current/book/translation.html#twig-templates>`_.
* **FormExtension**: If you are using the ``FormExtension``,
* **FormServiceProvider**: If you are using the ``FormServiceProvider``,
you will get a set of helpers for working with forms in templates.
You can find more information in the
`Symfony2 Forms reference <http://symfony.com/doc/current/reference/forms/twig_reference.html>`_.
......@@ -37,6 +37,6 @@ Registering
Make sure you place a copy of the Symfony2 Bridges in
``vendor/symfony/src``. You can simply clone the whole Symfony2 into vendor::
$app->register(new Silex\Extension\SymfonyBridgesExtension(), array(
$app->register(new Silex\Provider\SymfonyBridgesServiceProvider(), array(
'symfony_bridges.class_path' => __DIR__.'/vendor/symfony/src',
));
doc/extensions/translation.rst → doc/providers/translation.rst
View file @ a7894570
TranslationExtension
=====================
TranslationProvider
===================
The *TranslationExtension* provides a service for translating your application
The *TranslationProvider* provides a service for translating your application
into different languages.
Parameters
......@@ -40,7 +40,7 @@ Registering
Make sure you place a copy of the Symfony2 Translation component in
``vendor/symfony/src``. You can simply clone the whole Symfony2 into vendor::
$app->register(new Silex\Extension\TranslationExtension(), array(
$app->register(new Silex\Provider\TranslationProvider(), array(
'locale_fallback' => 'en',
'translation.class_path' => __DIR__.'/vendor/symfony/src',
));
......@@ -48,7 +48,7 @@ Make sure you place a copy of the Symfony2 Translation component in
Usage
-----
The Translation extension provides a ``translator`` service and makes use of
The Translation provider provides a ``translator`` service and makes use of
the ``translator.messages`` parameter::
$app['translator.messages'] = array(
......
doc/extensions/twig.rst → doc/providers/twig.rst
View file @ a7894570
TwigExtension
=============
TwigProvider
============
The *TwigExtension* provides integration with the `Twig
The *TwigProvider* provides integration with the `Twig
<http://twig.sensiolabs.org/>`_ template engine.
Parameters
......@@ -39,7 +39,7 @@ Registering
Make sure you place a copy of *Twig* in the ``vendor/twig``
directory::
$app->register(new Silex\Extension\TwigExtension(), array(
$app->register(new Silex\Provider\TwigProvider(), array(
'twig.path' => __DIR__.'/views',
'twig.class_path' => __DIR__.'/vendor/twig/lib',
));
......@@ -52,7 +52,7 @@ directory::
Usage
-----
The Twig extension provides a ``twig`` service::
The Twig provider provides a ``twig`` service::
$app->get('/hello/{name}', function ($name) use ($app) {
return $app['twig']->render('hello.twig', array(
......
doc/extensions/url_generator.rst → doc/providers/url_generator.rst
View file @ a7894570
UrlGeneratorExtension
=====================
UrlGeneratorProvider
====================
The *UrlGeneratorExtension* provides a service for generating
The *UrlGeneratorProvider* provides a service for generating
URLs for named routes.
Parameters
......@@ -25,12 +25,12 @@ Registering
::
$app->register(new Silex\Extension\UrlGeneratorExtension());
$app->register(new Silex\Provider\UrlGeneratorProvider());
Usage
-----
The UrlGenerator extension provides a ``url_generator`` service::
The UrlGenerator provider provides a ``url_generator`` service::
$app->get('/', function () {
return 'welcome to the homepage';
......
doc/extensions/validator.rst → doc/providers/validator.rst
View file @ a7894570
ValidatorExtension
=====================
ValidatorProvider
=================
The *ValidatorExtension* provides a service for validating data. It is
most useful when used with the *FormExtension*, but can also be used
The *ValidatorProvider* provides a service for validating data. It is
most useful when used with the *FormProvider*, but can also be used
standalone.
Parameters
......@@ -35,14 +35,14 @@ Registering
Make sure you place a copy of the Symfony2 Validator component in
``vendor/symfony/src``. You can simply clone the whole Symfony2 into vendor::
$app->register(new Silex\Extension\ValidatorExtension(), array(
$app->register(new Silex\Provider\ValidatorProvider(), array(
'validator.class_path' => __DIR__.'/vendor/symfony/src',
));
Usage
-----
The Validator extension provides a ``validator`` service.
The Validator provider provides a ``validator`` service.
Validating values
~~~~~~~~~~~~~~~~~
......@@ -93,7 +93,7 @@ getters::
});
You will have to handle the display of these violations yourself. You can
however use the *FormExtension* which can make use of the *ValidatorExtension*.
however use the *FormProvider* which can make use of the *ValidatorProvider*.
For more information, consult the `Symfony2 Validation documentation
<http://symfony.com/doc/2.0/book/validation.html>`_.
doc/services.rst
View file @ a7894570
......@@ -254,7 +254,7 @@ Core parameters
Defaults to 80.
This parameter can be used by the ``UrlGeneratorExtension``.
This parameter can be used by the ``UrlGeneratorProvider``.
* **request.https_port** (optional): Allows you to override the default port
for HTTPS URLs. If the current request is HTTPS, it will always use the
......@@ -262,7 +262,7 @@ Core parameters
Defaults to 443.
This parameter can be used by the ``UrlGeneratorExtension``.
This parameter can be used by the ``UrlGeneratorProvider``.
* **debug** (optional): Returns whether or not the application is running in
debug mode.
......
doc/usage.rst
View file @ a7894570
......@@ -312,10 +312,10 @@ have the value ``index``.
Named routes
~~~~~~~~~~~~
Certain extensions (such as ``UrlGenerator``) can make use of named routes.
Silex generates a default route name for each controller but you can override
it by calling ``bind`` on the ``Controller`` object that is returned by the
routing methods::
Some providers (such as ``UrlGeneratorProvider``) can make use of named routes.
By default Silex will generate a route name for you, that cannot 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 () {
...
......@@ -330,7 +330,7 @@ routing methods::
.. note::
It only makes sense to name routes if you use extensions that make use
It only makes sense to name routes if you use providers that make use
of the ``RouteCollection``.
Before and after filters
......@@ -405,8 +405,8 @@ once a response is returned, the following handlers are ignored.
.. note::
Silex ships with an extension for `Monolog <https://github.com/Seldaek/monolog>`_
which handles logging of errors. Check out the *Extensions* chapter
Silex ships with a provider for `Monolog <https://github.com/Seldaek/monolog>`_
which handles logging of errors. Check out the *Providers* chapter
for details.
.. tip::
......
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