Merge branch 'release/v0.13.0'

conf.py

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

developer/case-studies/download-to-vagrant.rst

@@ -0,0 +1,136 @@
+.. _download_to_vagrant:
+
+======================================================
+Download a website on my computer to work with Vagrant
+======================================================
+
+This case study is meant to get a fresh development environment from an **existing** Roadiz website and theme. Following code snippets are using
+some variables data, in theses examples I’ll use:
+
+- ``MYUSER`` as the MySQL database user.
+- ``MYPASSWORD`` as the MySQL database user password.
+- ``MYDATABASE`` as the MySQL database name.
+- ``~/Documents/Websites`` as the working directory on your own computer.
+- ``database-YYYY-mm-dd.sql`` is the mysql dump file name, replace ``YYYY-mm-dd`` with the current date.
+- ``mysuperwebsite`` is your website root folder.
+- ``git@github.com:johndoe/SuperTheme.git`` is an example *Github* repository for your theme.
+- ``SuperTheme`` is an example theme name and folder.
+
+On the production server:
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Generate a database dump on your production server.
+
+.. code-block:: bash
+
+    mysqldump -uMYUSER -pMYPASSWORD MYDATABASE > database-YYYY-mm-dd.sql
+
+Then download it on your computer. You can also use *phpmyadmin* web tool to export
+your database tables. Make sure to disable *foreign key verification* and add the
+*DROP IF EXISTS* directive on *phpmyadmin* export form.
+
+On your computer:
+^^^^^^^^^^^^^^^^^
+
+1. Clone Roadiz on your favorite folder, choose well between master or develop branch if you want the stable version or the latest features.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites;
+    # Here I choose the develop branch, because I’m warrior
+    git clone -b develop https://github.com/roadiz/roadiz.git mysuperwebsite;
+
+
+2. Clone your website theme in Roadiz ``themes/`` folder, choose well your branch too. If you already have a *develop* branch, clone with ``-b develop`` option.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite/themes;
+    # My theme already has a develop branch so…
+    git clone -b develop git@github.com:johndoe/SuperTheme.git SuperTheme;
+
+3. **[Optional]** Initialize *git-flow* on the theme. You should always work on *develop*. *Master* branch is only for releases. If you don’t have *git-flow* on your computer, you can find some help on the `official documentation <http://danielkummer.github.io/git-flow-cheatsheet/>`_.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite/themes/SuperTheme;
+    # You must fetch every available branches before initializing git flow
+    git checkout master;
+    git checkout develop;
+    git flow init;
+    # Follow instructions
+    # Git flow should checkout on develop branch for you
+
+4. Install Roadiz’ *Composer* dependencies (after cloning the theme to be sure that all *composer* dependencies are loaded)
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite;
+    composer install --no-dev;
+
+5. Launch your Vagrant environment. Do not to automatically provision your VM if you want to choose what tool to install.
+
+.. code-block:: bash
+
+    vagrant up --no-provision;
+    # ... lots of lines, bla bla bla
+
+Choose tools to install on your VM, ``roadiz`` provisioner is mandatory… obviously, ``devtools`` provisioner will
+install *Composer*, *Node.js*, *Grunt* and *Bower* commands. If you have lots of website on your computer, it’s better to
+install these tools directly on your host machine, they will be more effective than on the VM. And you will be able to
+take advantage of *Composer* and *NPM* cache between your dev websites.
+
+.. code-block:: bash
+
+    # Everything
+    vagrant provision --provision-with roadiz,phpmyadmin,mailcatcher,solr,devtools
+    # OR on a dev computer
+    vagrant provision --provision-with roadiz,phpmyadmin,mailcatcher,solr
+
+
+6. Import your database dump. First, you’ll need to copy it into your Roadiz website to make it available within your Vagrant VM. Then import it in your VM using the ``mysql`` tool.
+
+.. code-block:: bash
+
+    mv ~/Downloads/database-YYYY-mm-dd.sql ~/Documents/Websites/mysuperwebsite/database-YYYY-mm-dd.sql;
+    cd ~/Documents/Websites/mysuperwebsite;
+    # Enter your VM
+    vagrant ssh;
+    # Your website is located in /var/www folder
+    cd /var/www;
+    mysql -uroadiz -proadiz roadiz < database-YYYY-mm-dd.sql;
+    # Exit your VM
+    exit;
+
+7. Update your conf/config.yml file to fill in your mysql credentials.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite;
+    # composer should have create a starter config file for you
+    subl conf/config.yml; # If you work SublimeText
+
+8. Use the ``bin/roadiz generate:nsentities`` to regenerate *Doctrine* entities existing in database but not as files.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite;
+    vagrant ssh;
+    cd /var/www;
+    bin/roadiz generate:nsentities;
+    # You may have to check database schema if your production website is not up to
+    # date with latest Roadiz
+    bin/roadiz orm:schema-tool:update --dump-sql --force;
+
+9. Download your production documents to your dev VM. You don’t have to do this within your VM.
+
+.. code-block:: bash
+
+    cd ~/Documents/Websites/mysuperwebsite/files;
+    rsync -avcz -e "ssh -p 22" myuser@superwebsite.com:~/path/to/roadiz/files/ ./
+    # do not forget ending slashes in both paths.
+
+10. If you are using a Vagrant VM you have to add your IP address to the ``dev.php`` file to authorize your host computer to use the development environment.
+
+11. Connect to ``http://localhost:8080/dev.php`` to begin. Every outgoing emails should be catched
+by *Mailcatcher*. You can see them at address ``http://localhost:1080``.

developer/case-studies/index.rst

@@ -0,0 +1,11 @@
+
+============
+Case studies
+============
+
+Some step-to-step guides to work with Roadiz.
+
+.. toctree::
+   :maxdepth: 1
+
+   download-to-vagrant.rst

developer/first-steps/index.rst

@@ -7,6 +7,7 @@ First steps
 
    getting_started
    installation
+   vagrant
    manual_config
    upgrading
    moving

developer/first-steps/installation.rst

@@ -4,8 +4,8 @@
 Installation
 ============
 
-Download sources
-----------------
+Get Roadiz sources
+------------------
 
 Roadiz can be downloaded in two different ways:
 
@@ -21,17 +21,20 @@ An example virtual host is provided in source-code for each server:
 * ``samples/apache.conf``
 * ``samples/nginx.conf``
 
-You just have to customize your root path and server name. *Nginx* has built-in support for *php-fpm* whereas *Apache* must be configured with *fastcgi* to do the same.
+You just have to customize your root path and server name. *Nginx* has built-in support
+for *php-fpm* whereas *Apache* must be configured with *fastcgi* to do the same.
 
 These example files will provide basic security configuration for private access folders:
-such as ``conf`` or ``files/fonts`` folders. They will also configure your server to redirect all non static requests
-to Roadiz *front-controller*.
+such as ``conf`` or ``files/fonts`` folders. They will also configure your server
+to redirect all non static requests to Roadiz *front-controller*.
 
 .. note::
-    **For shared hosting plan owners**, if you can’t modify your virtual host definition, don’t panic, Roadiz has a built-in CLI command to generate ``.htaccess`` files for you.
-    Just execute ``bin/roadiz config --generate-htaccess`` after cloning Roadiz sources and running Composer.
-    In the other hand, if you are using *Apache* and have access to your virtual host, we strongly recommend you to use our sample configuration and disable ``.htaccess`` files: performances are at their best
-    without them.
+    **For shared hosting plan owners**, if you can’t modify your virtual host definition,
+    don’t panic, Roadiz has a built-in CLI command to generate ``.htaccess`` files for you.
+    Just execute ``bin/roadiz generate:htaccess`` after cloning Roadiz sources and running Composer.
+    In the other hand, if you are using *Apache* and have access to your virtual host,
+    we strongly recommend you to use our sample configuration and disable ``.htaccess`` files:
+    performances are at their best without them.
 
 When your HTTP server is ready to go, download *Roadiz* latest version using Git:
 
@@ -40,7 +43,9 @@ When your HTTP server is ready to go, download *Roadiz* latest version using Git
     cd your/webroot/folder;
     git clone git@github.com:roadiz/roadiz.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.
+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.
 
 .. code-block:: bash
     # Install Roadiz dependencies, prepare a fresh config file and your

developer/first-steps/manual_config.rst

@@ -40,7 +40,7 @@ Add this to your `config.yml` to link your CMS to your *Solr* server:
                 username: ""
                 password: ""
 
-Roadiz CLI command can easily handle Solr index. Just type ``./bin/roadiz solr --help`` to get
+Roadiz CLI command can easily handle Solr index. Just type ``./bin/roadiz solr:check`` to get
 more informations.
 
 

developer/first-steps/moving.rst

@@ -8,39 +8,41 @@ Before moving your website, make sure you have backed up your data:
 * Dump your database, using ``mysqldump`` or ``pg_dump`` tools.
 * Archive your ``files/`` folder, it contains all your documents and font files.
 
-Moving to a SSH+Git hosting plan
---------------------------------
+Moving to a SSH+Git hosting plan or an other development machine
+----------------------------------------------------------------
 
-From this point you can install your new webserver, as described in :ref:`Install section <getting-started>`.
+From this point you can install your new webserver, as described in :ref:`Install section <installation>`.
+Pay attention that if your theme needs some additionnal *composer* dependencies you should
+*clone/copy* it into your *themes/* folder **before** running ``composer install --no-dev``. That way
+*composer* will download theme libraries at the same time as Roadiz’ ones (:ref:`See how to use Composer in your themes <theme_composer>`).
 
 Then import your dump and files into your new server.
 
 Once you’ve imported your database, you must edit manually your `conf/config.yml`,
 you can reuse the former server’s one and adapt its database credentials.
 
 .. warning::
-    **Do not perform any schema update if no *gen-src\\GeneratedNodeSources* classes is available**,
+    **Do not perform any schema update if no gen-src\\GeneratedNodeSources classes is available**,
     it will erase your NodesSources data as their entities files haven’t been generated yet.
 
-When you have edited your ``conf/config.yml`` file, regenerate your entities source files
+When you have edited your ``conf/config.yml`` file, regenerate your *Doctrine* entities class files:
 
 .. code-block:: bash
 
-    bin/roadiz core:sources --regenerate;
+    bin/roadiz generate:nsentities;
 
-Now you can perform a schema update without losing your nodes data
+Now you can perform a schema update without losing your nodes data:
 
 .. code-block:: bash
 
     bin/roadiz orm:schema-tool:update --dump-sql;
     bin/roadiz orm:schema-tool:update --force;
-
-    bin/roadiz cache --clear-all
-    # You can use -a as a shortcut to --clear-all
+    bin/roadiz cache:clear --env=prod
 
 .. note::
     If you are using an OPcode cache like XCache or APC, you’ll need to purge cache manually
-    because it can't be done from a CLI interface as they are shared cache engines.
+    because it can't be done from a CLI interface as they are shared cache engines. The most
+    effective way is to restart your *PHP-FPM* service or *Apache* if your are using *mod_php*.
 
 Synchronize documents and fonts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -54,6 +56,14 @@ as it will upload only newer files and it is much faster.
     # Do not forget ending slash after each path!
     rsync -avcz -e "ssh -p 22" /path/to/roadiz/files/ user@my-prod-server.com:/path/to/roadiz/files/
 
+It works in the other way too. If you want to work on your local copy with up to date files and
+fonts, you can download actual files from the production website:
+
+.. code-block:: bash
+
+    # This will synchronize files on your local development server from your production server.
+    # Do not forget ending slash after each path!
+    rsync -avcz -e "ssh -p 22" user@my-prod-server.com:/path/to/roadiz/files/ /path/to/roadiz/files/
 
 
 Moving to a non-SSH hosting plan
@@ -67,21 +77,21 @@ an SFTP connection or worst, an old FTP one. Don’t panic, it will take a littl
 
 .. warning::
     Many shared-plan hosters offer you only one or two databases. When moving a Roadiz website, make sure
-    that your database is empty and do not contain orphan tables, you must respect the rule “One app = One database”.
-
-* Do not forget to generate ``.htaccess`` files for your prod server. Type ``bin/roadiz config --generate-htaccess``.
-* If you have at least SFTP, you should have to rights to zip/unzip on your distant server. So zip the whole Roadiz folder.
+    that your database is empty and do not contain orphan tables, you must respect the rule “One app = One database”.
 
 .. note::
     If you can ZIP on your production server or if you are going to push your files via FTP,
     do not forget to exclude ``.git`` and ``node_modules`` folders! These folders have **lots** of useless files
     for a production SSH-less environnement.
-    Here is a sample ZIP command to exclude them: ``zip -r mywebsite.zip mywebsite/ -x "mywebsite/.git/*" "mywebsite/themes/**/static/node_modules/*"``.
+    Here is a sample ZIP command to exclude them:
+    ``zip -r mywebsite.zip mywebsite/ -x "mywebsite/.git/*" "mywebsite/themes/**/static/node_modules/*"``.
 
+* Before transfering your website, make sure you have ``.htaccess`` file in every sensitive folders. You can use the ``bin/roadiz generate:htaccess`` on your computer.
+* If you have at least SFTP, you should have to rights to zip/unzip on your distant server. So zip the whole Roadiz folder.
 * If you only have FTP, you must be prepared to transfer your Roadiz folder, file-by-file. Just get yourself a nice cup of coffee.
 * Once everything is copied on your production server, verify than you have the same files as on your dev-server.
 * Import your database dump with phpmyadmin or pgmyadmin.
-* Edit your ``conf/config.yml`` to match your new database credentials. Enable ``devMode`` manually.
-* Verify that every sensitive folders contain an ``.htaccess`` file to deny access. Verify that root ``.htaccess`` file contains every informations to enable Apache url-rewriting.
-* Try to connect to your website, if everything works disable ``devMode`` and enjoy your hard work.
+* Edit your ``conf/config.yml`` to match your new database credentials.
+* Verify that root ``.htaccess`` file contains every informations to enable Apache url-rewriting.
+* Try to connect to your website
 * If it doesn’t work or display anything, read your PHP log file to understand where the problem comes from. It might be your database credentials or an oudated PHP version. Check that your hoster has installed every needed PHP extensions, see :ref:`requirements`.

developer/first-steps/upgrading.rst

@@ -29,7 +29,7 @@ regenerate your node-source entities classes files:
 
 .. code-block:: bash
 
-    bin/roadiz core:sources --regenerate;
+    bin/roadiz generate:nsentities;
 
 Then run database schema update, first review migration details
 to see if no data will be removed:
@@ -43,7 +43,7 @@ Then, if migration summary is OK (no data loss), perform the following changes:
 .. code-block:: bash
 
     bin/roadiz orm:schema-tool:update --force;
-    bin/roadiz cache --clear-all
+    bin/roadiz cache:clear --env=prod
 
 .. note::
     If you are using an OPcode cache like XCache or APC, you’ll need to purge cache manually