go headless

src/developer/first-steps/installation.rst

@@ -71,6 +71,8 @@ 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.
+Since Roadiz v1.6, preview environment is deprecated in favor of ``?_preview=1`` query param which
+allow preview in any environment, especially for API responses (JSON).
 
 Production environment
 ^^^^^^^^^^^^^^^^^^^^^^

src/developer/first-steps/manual_config.rst

@@ -17,6 +17,42 @@ Your ``app/conf/config.yml`` file is built using YAML syntax. Each part matches
 
     *Roadiz Source edition* stores configuration files in ``conf/`` folder.
 
+DotEnv
+------
+
+``app/conf/config.yml`` can resolve ``.env`` variables if you want to add this file to your Git repository or Docker
+images. For example:
+
+.. code-block:: yaml
+
+    doctrine:
+        driver: "pdo_mysql"
+        host: '%env(string:MYSQL_HOST)%'
+        user: '%env(string:MYSQL_USER)%'
+        password: '%env(string:MYSQL_PASSWORD)%'
+        dbname: '%env(string:MYSQL_DATABASE)%'
+        server_version: '%env(string:MYSQL_VERSION)%'
+        # "utf8mb4" charset requires at least mysql 5.7
+        # due to large index requirement.
+        # otherwise change it to "utf8"
+        charset: utf8mb4
+        default_table_options:
+            charset: utf8mb4
+            collate: utf8mb4_unicode_ci
+
+This configuration will be resolved against ``.env``:
+
+.. code-block:: bash
+
+    # MySQL
+    MYSQL_ROOT_PASSWORD=root
+    MYSQL_HOST=db
+    MYSQL_DATABASE=roadiz
+    MYSQL_USER=roadiz
+    MYSQL_PASSWORD=roadiz
+    MYSQL_VERSION=8.0
+
+
 Doctrine
 --------
 

src/developer/first-steps/requirements.rst

@@ -10,7 +10,7 @@ Roadiz is a web application running with PHP. It requires an HTTP server for sta
 Here is a short summary of mandatory elements before installing Roadiz:
 
 * Nginx or Apache, with a dedicated virtual host as described below.
-* PHP 7.2+ **required**
+* PHP 7.4+ **required**
 * ``php-gd`` extension
 * ``php-intl`` extension
 * ``php-xml`` extension
@@ -73,7 +73,7 @@ This command will generate ``.htaccess`` files in each critical folder to enable
     exposed anymore.
 
 
-CMS Structure
+CMS Structure
 -------------
 
 * ``bin/``: Contains the Roadiz CLI executable

src/developer/first-steps/upgrading.rst

@@ -8,18 +8,24 @@ Upgrading
     **Always do a database backup before upgrading.** You can use the *mysqldump* or *pg_dump* tools
     to quickly export your database as a file.
 
-    * With Roadiz command (MySQL only): ``bin/roadiz database:dump -c`` will generate a SQL file in ``app/`` folder
+    * With Roadiz command (MySQL/MariaDB only): ``bin/roadiz database:dump -c`` will generate a SQL file in ``app/`` folder
     * With a MySQL server: ``mysqldump -u[user] -p[user_password] [database_name] > dumpfilename.sql``
     * With a PostgreSQL server: ``pg_dump -U [user] [database_name] -f dumpfilename.sql``
 
 
-Use *Composer* to update dependencies or Roadiz itself with *Standard edition*, make sure that
+Use *Composer* to update dependencies or Roadiz itself with *Standard* or *Headless* editions, make sure that
 your Roadiz *version constraint* is set in your project ``composer.json`` file, then:
 
 .. code-block:: bash
 
-    composer update -n --no-dev;
+    composer update -o;
 
+Run database registered migrations (some migrations will be skipped according to your database type). Doctrine
+migrations are the default method to upgrade all none-node-type related entities:
+
+.. code-block:: bash
+
+    bin/roadiz migrations:migrate;
 
 In order to avoid losing sensible node-sources data. You should
 regenerate your node-source entities classes files:
@@ -28,18 +34,18 @@ regenerate your node-source entities classes files:
 
     bin/roadiz generate:nsentities;
 
-Then run database schema update, first review migration details
-to see if no data will be removed:
+Then check if there is no pending SQL changes due to your Roadiz node-types:
 
 .. code-block:: bash
 
     bin/roadiz orm:schema-tool:update --dump-sql;
+    # Upgrade node-sources tables if necessary
+    bin/roadiz orm:schema-tool:update --dump-sql --force;
 
-Then, if migration summary is OK (no data loss), perform the following changes:
+Then, clear your app caches:
 
 .. code-block:: bash
 
-    bin/roadiz orm:schema-tool:update --force;
     # Clear cache for each environment
     bin/roadiz cache:clear -e dev
     bin/roadiz cache:clear -e prod
@@ -49,7 +55,7 @@ Then, if migration summary is OK (no data loss), perform the following changes:
     bin/roadiz cache:clear-fpm -e prod --preview
 
 .. note::
-    If you are using an OPcode cache like XCache or APC, you’ll need to purge cache manually
+    If you are using a runtime cache like OPcache or APCu, you’ll need to purge cache manually
     because it can't be done from a CLI interface as they are shared cache engines. As a last
     chance try, you can restart your ``php-fpm`` service.
 

src/developer/headless/index.rst

@@ -0,0 +1,92 @@
+Go headless
+===========
+
+Since Roadiz v1.6, you can create a 100% *headless* project using:
+
+.. code-block:: bash
+
+    # Create a new Roadiz project
+    composer create-project roadiz/headless-edition myheadless_project
+
+No more theme, just business logic
+----------------------------------
+
+**Headless edition get rid of themes** logic in favor of a simple ``src/`` folder
+to add custom business logic. All API features are handled by *AbstractApiTheme* which is
+registered as a *composer* dependency and in your ``src/AppKernel.php`` file.
+
+.. code-block:: php
+
+    # src/AppKernel.php
+    public function register(Container $container): void
+    {
+        parent::register($container);
+        // Headless edition: do not remove API services
+        $container->register(new \Themes\AbstractApiTheme\Services\AbstractApiServiceProvider());
+        $container->register(new \App\AppServiceProvider());
+
+        /*
+         * Add your own service providers.
+         */
+    }
+
+Headless structure
+------------------
+
+* ``bin/``: Contains the Roadiz CLI executable
+* ``docker/``: Tools for creating development and production *Docker* image for your project
+* ``app/``: Contains every runtime resources from configuration to app cache and nodes-sources entities
+
+    * ``cache/``: Every cache file for *Twig* templates and `Intervention Request <https://github.com/roadiz/roadiz/releases>`_ images (this folder must be writable for PHP)
+    * ``conf/``: Your setup configuration file(s) (this folder must be writable for PHP)
+    * ``gen-src/``: Generated PHP code for Doctrine and your Node-types entities (this folder must be writable for PHP)
+    * ``logs/``: *Monolog* logs folder
+
+* ``files/``: Private documents and font files root (this folder must be writable for PHP)
+* ``samples/``: This folder contains useful configuration and example files for Apache or Nginx webservers
+* ``web/``: Your website root, it contains your application entry-points and your public assets
+
+    * ``files/``: Public documents (this folder must be writable for PHP)
+    * ``themes/``: public assets mirror for each theme, this folder contains symlinks to your ``themes/YourTheme/static`` folder
+
+* ``src/``: Contains all your website logic
+* ``vendor/``: Dependencies folder managed by *Composer*
+
+Configure CORS
+--------------
+
+.. code-block:: php
+
+    # src/AppServiceProvider.php
+    /**
+     * @return array
+     */
+    $container['api.cors_options'] = [
+        'allow_credentials' => true,
+        // Allow all origin or defines some regex domains
+        'allow_origin' => ['*'],
+        'allow_headers' => true,
+        'origin_regex' => false,
+        'allow_methods' => ['GET'],
+        // Expose Link header for NuxtJS to resolve other translations
+        'expose_headers' => ['Link'],
+        'max_age' => 60*60*24
+    ];
+
+API usage and authentication
+----------------------------
+
+API endpoints are described in detail in `AbstractApiTheme <https://github.com/roadiz/AbstractApiTheme#generic-roadiz-api>`_  repository README. You'll get automatic:
+
+* Collection listing for all nodes-sources
+* Collection listing per node-type
+* Single item endpoint
+* User endpoint
+* …
+
+All with query-string parameters for searching and filtering JSON output.
+
+API can be accessed using:
+
+* Simple ``X-Api-Key`` access per application for non-user related content
+* Or **OAuth2** applications with ``client_credentials`` or ``authorization_code`` grant types.

src/developer/index.rst

@@ -13,6 +13,7 @@ skills.
    nodes-system/index.rst
    tags-system/index.rst
    attributes/index.rst
+   headless/index.rst
    themes/index.rst
    forms/index.rst
    services/index.rst