some doc tweaks

Resources/doc/annotations.rst

@@ -3,7 +3,9 @@ Annotations
 @PreAuthorize
 ~~~~~~~~~~~~~
 This annotation lets you define an expression (see the expression language
-paragraph) which is executed prior to invoking a method::
+paragraph) which is executed prior to invoking a method:
+
+.. code-block :: php
 
     <?php
     
@@ -20,7 +22,9 @@ paragraph) which is executed prior to invoking a method::
 
 @Secure
 ~~~~~~~
-This annotation lets you define who is allowed to invoke a method::
+This annotation lets you define who is allowed to invoke a method:
+
+.. code-block :: php
 
     <?php
     
@@ -40,7 +44,9 @@ This annotation lets you define who is allowed to invoke a method::
 @SecureParam
 ~~~~~~~~~~~~
 This annotation lets you define restrictions for parameters which are passed to
-the method. This is only useful if the parameters are domain objects::
+the method. This is only useful if the parameters are domain objects:
+
+.. code-block :: php
 
     <?php
     
@@ -61,7 +67,9 @@ the method. This is only useful if the parameters are domain objects::
 @SecureReturn
 ~~~~~~~~~~~~~
 This annotation lets you define restrictions for the value which is returned by
-the method. This is also only useful if the returned value is a domain object::
+the method. This is also only useful if the returned value is a domain object:
+
+.. code-block :: php
 
     <?php
     
@@ -88,7 +96,9 @@ for before, or after invocation access decisions.
 
 This is typically used to implement a two-tier service layer where you have 
 public and private services, and private services are only to be invoked 
-through a specific public service::
+through a specific public service:
+
+.. code-block :: php
 
     <?php
     

Resources/doc/configuration.rst

@@ -3,33 +3,54 @@ Configuration
 
 Below, you find the default configuration:
 
-.. code-block :: yaml
+.. configuration-block ::
 
-    # app/config/config.yml
-    jms_security_extra:
-        # Whether you want to secure all services (true), or only secure specific
-        # services (false); see also below 
-        secure_all_services: false
-        
-        # Enabling this setting will add an additional special attribute "IS_IDDQD".
-        # Anybody with this attribute will effectively bypass all security checks.
-        enable_iddqd_attribute: false        
-        
-        # Enables expression language
-        expressions: false
-
-        # Allows you to disable some, or all built-in voters
-        voters:
-            disable_authenticated: false
-            disable_role:          false
-            disable_acl:           false
+    .. code-block :: yaml
+    
+        # app/config/config.yml
+        jms_security_extra:
+            # Whether you want to secure all services (true), or only secure specific
+            # services (false); see also below 
+            secure_all_services: false
             
-        # Allows you to specify access control rules for specific methods, such
-        # as controller actions
-        method_access_control: { }
+            # Enabling this setting will add an additional special attribute "IS_IDDQD".
+            # Anybody with this attribute will effectively bypass all security checks.
+            enable_iddqd_attribute: false        
+            
+            # Enables expression language
+            expressions: false
+    
+            # Allows you to disable some, or all built-in voters
+            voters:
+                disable_authenticated: false
+                disable_role:          false
+                disable_acl:           false
+                
+            # Allows you to specify access control rules for specific methods, such
+            # as controller actions
+            method_access_control: { }
+    
+            util:
+                secure_random:
+                    connection: # the doctrine connection name
+                    table_name: seed_table
+                    seed_provider: # service id of your own seed provider implementation
 
-        util:
-            secure_random:
-                connection: # the doctrine connection name
-                table_name: seed_table
-                seed_provider: # service id of your own seed provider implementation
+    .. code-block :: xml
+    
+        <jms-security-extra 
+            secure-all-services="false"
+            enable-iddqd-attribute="false"
+            expressions="false">
+        
+            <voters disable-authenticated="false"
+                    disable-role="false"
+                    disable-acl="false" />
+                    
+            <util>
+                <secure-random
+                    connection="default"
+                    table-name="seed-table"
+                    seed-provider="some-service-id" />
+            </util>
+        </jms-security-extra>

Resources/doc/expressions.rst

@@ -15,7 +15,11 @@ Usage
 Programmatic Usage
 ~~~~~~~~~~~~~~~~~~
 You can execute expressions programmatically by using the ``isGranted`` method
-of the SecurityContext. Some examples::
+of the SecurityContext. Some examples:
+
+.. code-block :: php
+
+    <?php
 
     use JMS\SecurityExtraBundle\Security\Authorization\Expression\Expression;
     
@@ -27,18 +31,30 @@ of the SecurityContext. Some examples::
 Twig Usage
 ~~~~~~~~~~
 You can check expressions from Twig templates using the ``is_expr_granted``
-function. Some examples::
+function. Some examples:
+
+.. code-block :: jinja
 
     is_expr_granted("hasRole('FOO')")
     is_expr_granted("hasPermission(object, 'VIEW')", object)
 
 Usage in Access Control
 ~~~~~~~~~~~~~~~~~~~~~~~
-You can also use expressions in the ``access_control``::
+You can also use expressions in the ``access_control``:
+
+.. configuration-block ::
 
-    security:
-        access_control:
-            - { path: ^/foo, access: "hasRole('FOO') and hasRole('BAR')" }
+    .. code-block :: yaml
+
+        security:
+            access_control:
+                - { path: ^/foo, access: "hasRole('FOO') and hasRole('BAR')" }
+
+    .. code-block :: xml
+    
+        <security>
+            <rule path="^/foo" access="hasRole('FOO') and hasRole('BAR')" />
+        </security>
 
 Annotation-based Usage
 ~~~~~~~~~~~~~~~~~~~~~~

Resources/doc/installation.rst

@@ -1,6 +1,57 @@
 Installation
 ------------
-Add the following to your ``deps`` file:
+
+1. Using Composer (recommended)
+-------------------------------
+
+To install JMSSecurityExtraBundle with Composer just add the following to your
+`composer.json` file:
+
+.. code-block :: js
+
+    // composer.json
+    {
+        // ...
+        require: {
+            // ...
+            "jms/security-extra-bundle": "master-dev"
+        }
+    }
+    
+.. note ::
+
+    Please replace `master-dev` in the snippet above with the latest stable
+    branch, for example ``1.0.*``.
+    
+Then, you can install the new dependencies by running Composer's ``update``
+command from the directory where your ``composer.json`` file is located:
+
+.. code-block :: bash
+
+    php composer.phar update
+    
+Now, Composer will automatically download all required files, and install them
+for you. All that is left to do is to update your ``AppKernel.php`` file, and
+register the new bundle:
+
+.. code-block :: php
+
+    <?php
+
+    // in AppKernel::registerBundles()
+    $bundles = array(
+        // ...
+        new JMS\AopBundle\JMSAopBundle(),
+        new JMS\SecurityExtraBundle\JMSSecurityExtraBundle(),
+        new JMS\DiExtraBundle\JMSDiExtraBundle($this),
+        // ...
+    );
+
+2. Using the ``deps`` file (Symfony 2.0.x)
+------------------------------------------
+
+First, checkout a copy of the code. Just add the following to the ``deps`` 
+file of your Symfony Standard Distribution:
 
 .. code-block :: ini
 
@@ -27,11 +78,14 @@ Add the following to your ``deps`` file:
     [JMSDiExtraBundle]
         git=https://github.com/schmittjoh/JMSDiExtraBundle.git
         target=/bundles/JMS/DiExtraBundle
-
+        
+        
 Then register the bundle with your kernel:
 
 .. code-block :: php
 
+    <?php
+
     // in AppKernel::registerBundles()
     $bundles = array(
         // ...
@@ -45,11 +99,21 @@ Make sure that you also register the namespaces with the autoloader:
 
 .. code-block :: php
 
+    <?php
+
     // app/autoload.php
     $loader->registerNamespaces(array(
+        // ...
         // ...
         'JMS'              => __DIR__.'/../vendor/bundles',
         'Metadata'         => __DIR__.'/../vendor/metadata/src',
         'CG'               => __DIR__.'/../vendor/cg-library/src',
         // ...
     ));
+
+Now use the ``vendors`` script to clone the newly added repositories 
+into your project:
+
+.. code-block :: bash
+
+    php bin/vendors install

Resources/doc/random_number_generator.rst

@@ -1,17 +1,49 @@
 Secure Random Number Generator
 ------------------------------
+
+.. versionadded :: 1.2
+    The Secure Random Number Generator was added.
+
+Introduction
+------------
 In almost all applications, you need to generate random numbers that cannot be
 guessed by a possible attacker. Unfortunately, PHP does not provide capabilities
 to do this consistently on all platforms. 
 
 This bundle ships with several seed provider implementations, and will choose
 the best provider possible depending on your PHP setup.
 
-You can enable the "security.secure_random" service with the following config::
+Configuration
+-------------
+You can enable the "security.secure_random" service with the following config:
+
+.. configuration-block ::
+
+    .. code-block :: yaml
 
-    jms_security_extra:
-        util:
-            secure_random: ~
+        jms_security_extra:
+            util:
+                secure_random: ~
+                
+    .. code-block :: xml
+    
+        <jms-security-extra>
+            <util>
+                <secure-random />
+            </util>
+        </jms-security-extra>
 
 Also make sure to run ``php app/console doctrine:schema:update``, or create an
 equivalent migration to import the seed table.
+
+Usage
+-----
+The generator is made available with the service id ``security.secure_random``.
+
+.. code-block :: php
+
+    <?php
+    
+    $generator = $this->container->get('security.secure_random');
+    $bytes = $generator->nextBytes(16); // 128-bit random number
+