Merge branch 'release/v0.14.1'

conf.py

@@ -90,9 +90,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.14.0'
+version = '0.14.1'
 # The full version, including alpha/beta/rc tags.
-release = 'alpha 0.14.0'
+release = 'alpha 0.14.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

developer/first-steps/contributing.rst

@@ -24,7 +24,7 @@ For this you will need to install the testing framework, this can easily be done
 
 .. code-block:: console
 
-    composer update
+    composer update --dev
 
 The unit tests can be launched by the command:
 
@@ -38,7 +38,7 @@ Coding style
 ------------
 
 The code you contributed to the project should respect the guidelines defined in PHP *PSR2* standard.
-If you install the requirements for devs by the command ``composer update-dev``, you can use *phpcs* to check your code.
+If you install the requirements for devs by the command ``composer update --dev``, you can use *phpcs* to check your code.
 You can copy and paste the following command-lines to check easily:
 
 .. code-block:: console
@@ -49,5 +49,15 @@ You can copy and paste the following command-lines to check easily:
                 --ignore=*/node_modules/*,*/.AppleDouble,*/vendor/*,*/cache/*,*/gen-src/*,*/tests/*,*/bin/* \
                 -p ./
 
+Or you can use *phpcbf* to automatically fix code style issues.
+
+.. code-block:: console
+
+    bin/phpcbf --report=full --report-file=./report.txt \
+                --extensions=php --warning-severity=0 \
+                --standard=PSR2 \
+                --ignore="*/node_modules/*,*/.AppleDouble,*/vendor/*,*/cache/*,*/gen-src/*,*/tests/*,*/bin/*" \
+                -p ./
+
 Please take those rules into account, we aim to have a clean codebase. A coherent codestyle will contribute to Roadiz stability.
 Your code will be checked when we will be considering your pull requests.

developer/first-steps/getting_started.rst

@@ -60,7 +60,13 @@ If you are using *Apache* do not forget to enable these mods:
 * ``mod_rewrite``: enabling Roadiz front-controller system.
 * ``mod_expires``: enabling http cache headers on static assets.
 
-And do not use built-in ``mod_php``, prefer *PHP-FPM* ;-)
+And do not use built-in ``mod_php``, prefer *PHP-FPM* 😉!
 
 Then use ``/samples/apache.conf`` template to create your *virtual host* configuration file. It shows how to set rewrite and
 secure private folders from being viewed from public visitors.
+
+If you do not have access to your Apache virtual host configuration, you can use the built-in *htaccess* generator:
+
+``bin/roadiz generate:htaccess``
+
+This command will generate ``.htaccess`` files in each critical folder to enable PHP scripts or deny public access to forbidden folders.

developer/first-steps/installation.rst

@@ -9,8 +9,8 @@ Get Roadiz sources
 
 Roadiz can be downloaded in two different ways:
 
-* *The Good one*: using **Git** and **Composer** (needs an SSH connnexion to your server)
-* *The Easy one*: using a bundled Zip archive with composer dependencies.
+* *The Good one* — using **Git** and **Composer** (needs an *SSH* connection to your server and *Git*)
+* *The Easy one* — using a bundled *Zip* archive with composer dependencies.
 
 Using Git (recommended)
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -45,19 +45,16 @@ When your HTTP server is ready to go, download *Roadiz* latest version using Git
 
 Use `Composer <https://getcomposer.org/doc/00-intro.md#globally>`_ to download Roadiz dependencies
 and to build PHP class autolader. We even set up some post-scripts which will copy
-a new ``config.yml``, ``dev.php`` and ``install.php`` files for you.
+a new ``config.yml``, ``dev.php``, ``clear_cache.php`` and ``install.php`` files for you.
 
 .. code-block:: bash
     # Install Roadiz dependencies, prepare a fresh config file and your
     # own dev and install entry points.
-    composer install --no-dev;
+    composer install --no-dev -o;
 
 When your virtual host is ready and every files have been downloaded you can go to the
-next part to enable the `install environment`_.
+next part to access the `install environment`_.
 
-.. note::
-    Once your website will be ready to be pushed to production you will be able to
-    optimize *Composer* autoload process: ``composer dumpautoload -o``
 
 The quick and dirty way: using a Zip archive
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -98,27 +95,43 @@ Installation environment
 Once you’ve succedded to download Roadiz sources and dependencies. You’ll have to setup its database
 and every informations needed to begin your website.
 
-As every *Symfony* application do, Roadiz works using environments. By default, there is a *production*
+As every *Symfony* applications do, Roadiz works using environments. By default, there is a *production*
 environment which is handled by ``index.php`` entry point. At this moment, if you try to connect to
 your fresh new Roadiz website, you will get an error as we did not install its database and its essential data.
 
-To be able to use Roadiz *install interface*, you’ll need to call the *install* environment entry point. A ``install.php`` file has been generated when you executed ``composer install`` command. This environment will be reachable at the Url ``http://mywebsite.com/install.php``. For security reasons, we added an IP filtering in this entry point, you can add your own IP address in the following array: ``array('127.0.0.1', 'fe80::1', '::1')``. This IP filtering is very important if you are working on a public server, no one except you should be able to access *install* entry point.
+To be able to use Roadiz *install interface*, you’ll need to call the *install* entry point. An ``install.php`` file has been generated when you executed ``composer install`` command. This environment will be reachable at the Url ``http://mywebsite.com/install.php``.
+
+For security reasons, we added an IP filtering in this entry point, you can add your own IP address in the following array: ``array('127.0.0.1', 'fe80::1', '::1')``. This IP filtering is very important if you are working on a public server, no one except you should be able to access *install* entry point.
 
 At the end of the install process, you will be invited to remove the ``install.php`` file and to connect to your
 website final URL.
 
 Development environment
 ^^^^^^^^^^^^^^^^^^^^^^^
-
 Roadiz *production* environment is not made for developing your own themes and extending back-office features.
 As the same way as *install* environment, we prepared a *dev* environment to disable resources caching and enable
 debug features. You’ll find a ``dev.php`` file at your website root which was generated at ``composer install`` command.
 As well as *install.php* entry point, you’ll need to add your own IP address to filter who can access to your *dev* environment.
 
 Preview environment
 ^^^^^^^^^^^^^^^^^^^
-
 The *preview* environment is not a real one as it only adds a flag to Roadiz’ Kernel to enable
 back-office users to see unpublished nodes. By default, it is available using ``preview.php``
 entry point, unless you decide to remove it.
 
+Production environment
+^^^^^^^^^^^^^^^^^^^^^^
+This is the default ``index.php`` entry point which will be called by all your visitors.
+There is no restriction on it and it will wake up Roadiz application using the strongest
+caching policies. So it’s not recommended for development usage (you would have to flush caches
+each time your change something in the code).
+
+Clear cache environment
+^^^^^^^^^^^^^^^^^^^^^^^
+The *clear_cache* environment is only meant to empty Roadiz cache without waking up
+the whole application. It can be useful if you are using a op-code cache like *APC* or
+native PHP *OPcache*. These special caches can’t be purged from command line utilities,
+so you need to call a PHP script from your browser or via ``curl`` to empty them.
+Like *install* and *dev* environment, ``clear_cache.php`` is IP-restricted not to
+allow everyone to flush your dear caches. You’ll need to add your own IP address to filter who can access it.
+

developer/first-steps/manual_config.rst

@@ -3,7 +3,8 @@
 Manual configuration
 ====================
 
-This section explains how main configuration file ``conf/config.yml`` works. It is way more more convenient than launching Install theme for each update.
+This section explains how main configuration file ``conf/config.yml`` works.
+It is way more more convenient than launching Install theme for each update.
 
 Your ``conf/config.yml`` file is built using YAML syntax. Each part matches a Roadiz *service* configuration.
 The most important part deals with Doctrine database credentials:
@@ -58,8 +59,8 @@ In order to make Roadiz more extensible, you can add your own paths to the ``ent
         - "gen-src/GeneratedNodeSources"
 
 
-Swift Mailer
-------------
+Configure mailer
+----------------
 
 Roadiz uses *Swift Mailer* to send emails. This awesome librairy is built to enable different
 kinds of mail transports or protocols. By default, Roadiz uses your PHP ``sendmail`` configuration
@@ -77,6 +78,25 @@ You can use *SSL*, *TLS* or no encryption at all.
         username: ""
         password: ""
 
+Images processing
+-----------------
+
+Roadiz use `Image Intervention <http://image.intervention.io/>`_ library to automatically create a lower quality
+version of your image if they are too big. You can define this threshold value
+in the `assetsProcessing` section. `driver` and `defaultQuality` will be also
+use for the on-the-fly image processing with `Intervention Request <https://github.com/ambroisemaupate/intervention-request>`_ library.
+
+.. code-block:: yaml
+
+    assetsProcessing:
+        # gd or imagick (gd does not support TIFF and PSD formats)
+        driver: gd
+        defaultQuality: 90
+        # pixel size limit () after roadiz
+        # should create a smaller copy.
+        maxPixelSize: 1280
+
+
 Console command
 ---------------
 

developer/first-steps/vagrant.rst

@@ -34,20 +34,20 @@ if you have lots of Roadiz instances.
 
     # Just LEMP stack, no Solr, no phpMyAdmin, no Mailcatcher, no Composer, no NPM, no grunt, no bower
     vagrant up --no-provision
-    vagrant provision --provision-with roadiz
+    vagrant provision --provision-with=roadiz
 
     # Just LEMP stack, no Solr, no Composer, no Mailcatcher, no NPM, no grunt, no bower
     vagrant up --no-provision
-    vagrant provision --provision-with roadiz,phpmyadmin
+    vagrant provision --provision-with=roadiz,phpmyadmin
 
     # If you need Solr
     # do not use space after comma
     vagrant up --no-provision
-    vagrant provision --provision-with roadiz,solr
+    vagrant provision --provision-with=roadiz,solr
 
     # If you need dev tools
     vagrant up --no-provision
-    vagrant provision --provision-with roadiz,devtools
+    vagrant provision --provision-with=roadiz,devtools
 
 When you use default `vagrant up` command, it’s the same as using:
 
@@ -68,7 +68,7 @@ be lost in your Vagrant box unless you ``destroy`` it.
 Developing with PHP 7
 ---------------------
 
-Roadiz Vagrant uses **PHP7** with its latest version published on *ppa:ondrej/php-7.0* repository.
+Roadiz Vagrant uses **PHP7** with its latest version published on *ppa:ondrej/php* repository.
 If you do not want to use it and you prefer using PHP 5.6, you can comment out provisioner scripts in
 ``Vagrantfile``. This changes can’t be done once you’ve provisioned your Vagrant VM. This is applicable only for
 ``roadiz`` and ``mailcatcher`` scripts, others can be provisioned with both PHP versions.

developer/index.rst

@@ -15,4 +15,5 @@ skills.
    themes/index.rst
    forms/index.rst
    services/index.rst
-   case-studies/index.rst
+   case-studies/index.rst
+   troubleshooting.rst

developer/nodes-system/node_type_fields.rst

@@ -61,3 +61,15 @@ display available default choices for “select-box” types:
 *Children node* field type is a special virtual field that will display a custom
 node-tree inside your editing page. You can add *quick-create* buttons by listing
 your node-types names in *default values* input, comma separated.
+
+Universal fields
+^^^^^^^^^^^^^^^^
+
+If you need a field to hold exactly the same data for all translations, you can
+set it as *universal*. For example for documents, numeric and boolean data that
+do not change from one language to another.
+
+It will duplicate data at each save time from default translation
+to others. It will also hide the edit field from non-default translation to avoid
+confusion.
+

developer/themes/create_theme.rst

@@ -97,46 +97,32 @@ Edit your main class informations (``MyAwesomeThemeApp.php``)
    :emphasize-lines: 11,25,30,34,38,42
 
     /*
-     * Copyright REZO ZERO 2014
+     * Copyright REZO ZERO 2016
      *
      * Description
      *
      * @file MyAwesomeThemeApp.php
      * @copyright REZO ZERO 2014
      * @author Ambroise Maupate
      */
-
     namespace Themes\MyAwesomeTheme;
 
     use RZ\Roadiz\CMS\Controllers\FrontendController;
     use RZ\Roadiz\Core\Entities\Node;
     use RZ\Roadiz\Core\Entities\Translation;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
+
     /**
      * MyAwesomeThemeApp class
      */
     class MyAwesomeThemeApp extends FrontendController
     {
-        /**
-         * {@inheritdoc}
-         */
+
         protected static $themeName =      'My awesome theme';
-        /**
-         * {@inheritdoc}
-         */
         protected static $themeAuthor =    'Ambroise Maupate';
-        /**
-         * {@inheritdoc}
-         */
         protected static $themeCopyright = 'REZO ZERO';
-        /**
-         * {@inheritdoc}
-         */
         protected static $themeDir =       'MyAwesomeTheme';
-        /**
-         * {@inheritdoc}
-         */
         protected static $backendTheme =    false;
 
         …

developer/themes/display_documents.rst

@@ -91,6 +91,10 @@ Roadiz can generate a ``srcset`` attribute to create a responsive image tag like
                 'rule': '1200w',
             }
         ],
+        'sizes': [
+            '(max-width: 780px) 200px',
+            '(max-width: 1200px) 600px',
+        ],
     }) }}
     {% endif %}
 
@@ -100,6 +104,7 @@ This will output an ``img`` tag like the following one:
 
     <img src="/assets/f600x600-q75/image.jpg"
          srcset="/assets/f600x600-q75/image.jpg 1200w, /assets/f200x200-q90/image.jpg 780w"
+         sizes="(max-width: 780px) 200px, (max-width: 1200px) 600px"
          alt="A responsive image">
 
 More document details

developer/themes/theme_firewall.rst

@@ -137,9 +137,11 @@ feedback on your login form:
      * {@inheritdoc}
      */
     public function loginAction(
-        Request $request
+        Request $request,
+        $_locale = 'en'
     ) {
-        $this->prepareThemeAssignation(null, null);
+        $translation = $this->bindLocaleFromRoute($request, $_locale);
+        $this->prepareThemeAssignation(null, $translation);
         $helper = $this->getService('securityAuthenticationUtils');
         $this->assignation['last_username'] = $helper->getLastUsername();
         $this->assignation['error'] = $helper->getLastAuthenticationError();

developer/troubleshooting.rst

@@ -0,0 +1,57 @@
+===============
+Troubleshooting
+===============
+
+Empty caches manually for an environment
+----------------------------------------
+
+If you experience errors only on a dedicated environment such as
+``prod``, ``dev`` or ``install``, it means that cache is not fresh for
+these environments. As a first try, you should always call
+``bin/roadiz cache:clear -e prod;`` (replace *prod* by your environment)
+in command line.
+
+If you still get errors from a specific env and you are using an
+*OPcode* cache or *var cache* (*APC*, *XCache*), call
+``clear_cache.php`` entry point *from your browser* or execute
+``curl http://localhost/clear_cache.php`` from your command line.
+
+Problem with entities and Doctrine cache?
+-----------------------------------------
+
+After each Roadiz **upgrade** you should always upgrade your
+node-sources entity classes and upgrade database schema.
+
+.. code:: bash
+
+    bin/roadiz generate:nsentities;
+    bin/roadiz orm:schema-tool:update --dump-sql --force;
+    bin/roadiz cache:clear -e prod;
+
+If you are using a *OPCode var cache* like *APC*, *XCache*, you should
+purge it as Roadiz stores doctrine configuration there for better
+performances, call ``clear_cache.php`` entry point from your browser or
+``curl http://localhost/clear_cache.php`` from your command line.
+
+Running Roadiz behind a reverse proxy
+-------------------------------------
+
+If you are behind a reverse-proxy like *Varnish* or *Nginx proxy* on a
+*Docker* environment, IP addresses, domain name and proto (https/http)
+could not be correctly set. So you will have to tell Roadiz to trust
+your proxy in order to use ``X_FORWARDED_*`` env vars.
+
+Add this line to your ``index.php`` and ``preview.php`` files after
+``$request = Request::createFromGlobals();`` line.
+
+.. code:: php
+
+    $request = Request::createFromGlobals(); // Existing line to get request
+    // Trust incoming request IP as your reverse proxy
+    Request::setTrustedProxies(array($request->server->get('REMOTE_ADDR')));
+
+Find help before posting an issue on Github
+-------------------------------------------
+
+Join us on Gitter: https://gitter.im/roadiz/roadiz
+