Migration Guide

Hint

This page gives migration instructions on specific Mapbender versions. For general tips on updating, see the Update Mapbender to a newer Version page instead.

Tip

For in-depth information from the Mapbender development team, also see the Upgrading Guide on GitHub.

Migration to Mapbender 4.0.0

  • Carefully check the Upgrading Guide on GitHub before you do the update.

  • You will notice that the Symfony Directory Structure changed a lot.

  • For Mapbender 4, all .yml file extensions were transformed into .yaml.

  • config.yml is omitted.

  • public files moved from web/ to public/.

  • Instead of multi parameters in parameters.yml, the database definition is replaced by an environment variable MAPBENDER_DATABASE_URL. Configure it by adding it in your .env.local file. If you have multiple connections, use one env variable per connection and configure these in the config/packages/doctrine.yaml file.

  • The Apache Vhost Definition or ALIAS has to be changed. Refer to public (instead of web). Call index.php instead of app.php). See installation instruction.

  • Environment can now be set using the environment variable APP_ENV (see .env.local), .index_dev.php (instead of app_dev.php) is still available as an alternative for accessing the dev environment.

  • Database permission can be migrated using bin/console mapbender:security:migrate-from-acl. Do that before executing the schema:update command, otherwise your old ACL tables will be gone!

Upgrade database

Warning

Execute the following commands in the specified order to upgrade (after bringing the symfony directory structure up to date). First, make a backup of your database!

  1. Replace Doctrine’s removed json_array type to json. If you are using a DBMS other than SQlite, PostgreSQL and MySQL, you need to do that manually:

bin/console mapbender:database:upgrade

  1. Migrate security definitions from the ACL system to the new permission system:

bin/console mapbender:security:migrate-from-acl

  1. Update the rest of the database. This must be executed last, since it deletes the old ACL tables:

bin/console doctrine:schema:update --complete --force``

Migration to Mapbender 3.3.4

  • Please update the database schema. Run:

bin/console doctrine:schema:update --force

  • Next, you need to configure CSRF tokens to be used during login to the csrf_token_generator form_login section in security.yaml as follows:

form_login:
    check_path: /user/login/check
    login_path: /user/login
    csrf_token_generator: security.csrf.token_manager

  • For productive environments, it is important to install an SSL certificate. After that, set the parameters.cookie_secure variable in your parameters.yaml to true. This ensures that the Login cookie is only transmitted over secure connections.

Migration to Mapbender 3.3

  • Make sure you have PHP >= 7.4 or PHP 8.x.

  • Provide a backup of your database.

  • Update your database schema to 3.3 with bin/console doctrine:schema:update --force.

  • doctrine.yaml: Please note that in the doctrine connection configuration variables must be set with quotes, for example ‘%database_driver%’

  • CAUTION: Please note that the eye at application is used from (3.2.x) onwards to make the application available for the anonymous user (public access). Before 3.2.x, the eye/checkbox at Security was used to publish an application.

To update from 3.2.x to 3.3.x should be quite easy.

Note

If you update from a version < 3.2, you have to follow the steps described at the Migration to Mapbender 3.2 section below.

Migration to Mapbender 3.2

You can migrate older Mapbender installations to Mapbender 3.2.

Check the Update Mapbender to a newer Version Guide.

  • Make sure you have PHP >= 7.1.0 and PHP < 8.

  • Provide a backup of your database.

  • Update your database schema to 3.2 with bin/console doctrine:schema:update --force.

  • CAUTION: Please note that the eye at application is from (3.2.x) used to make the application available for the anonymous user (public access). Before the eye/checkbox at Security was used to publish an application.

Some elements may not work after the update and may need a closer look.

Update map_engine_code

If it makes sense, update all applications to map_engine_code current.

Update mb_core_application set map_engine_code = 'current';

SearchRouter

In the Workshop bundle, you can find a Demo.

  1. deprecated empty: use placeholder instead

  2. For text and choice you have to define the full class-path.

You also find information at Best Practices Page.

You can update the configuration with the following SQL.

Update mb_core_element set configuration =
replace(configuration,'s:6:"choice"','s:53:"Symfony\Component\Form\Extension\Core\Type\ChoiceType"')
    where class = 'Mapbender\CoreBundle\Element\SearchRouter';

Update mb_core_element set configuration =
replace(configuration,'s:4:"text"','s:51:"Symfony\Component\Form\Extension\Core\Type\TextType"')
where class = 'Mapbender\CoreBundle\Element\SearchRouter';

Select configuration from mb_core_element where class = 'Mapbender\CoreBundle\Element\SearchRouter';

  1. For choice: Please note that key or value are passed flipped that means value and the key- see also Best Practices Page

choices:
    Bonn - this is the value not the key: Bonn
    Cologne - this is the value not the key: Cologne
    Siegburg - this is the value not the key: Siegburg

Migrating SimpleSearch

SimpleSearch element was improved. You can now define the projection of the result that comes from the Solr Service. Mapbender will then transform the result to the projection of the map.

SimpleSearch Supports Nominatim, Photon from version 3.2.5 - see workshop demo applications

  1. Define sourceSrs in your SimpleSearch definition. If not defined, the default (‘EPSG:4326’) should be chosen. You can find an example at this Configuration file

    sourceSrs: ‘EPSG:25832’

  2. query_ws_replace: From version 3.2.8 on, set query_ws_replace or modify the code as described in this issue comment

    query_ws_replace: +

Migrating BaseSourceSwitcher

Please note that on start of an application, all WMS are activated where the root layer is activated.

Before 3.2, it was possible to activate all BaseSources, where only the first WMS was visible on start.

Template / CSS

CSS change. Plus, there will be a big redesign in backend and frontend in the upcoming versions.

  • Check the workshop Bundle for the changes

  • Define your template as desktop-template

Migrating Digitizer

Digitizer is available for Mapbender >= 3.2.2. The new Digitizer Version is 1.4. Some functionality is not updated to 1.4 already (e.g. cluster).

  • See list of deprecated features

  • See also digitizer php file

  • You can find a demo in the Workshop bundle

  • maxResults - is supported again to limit the number of features that are loaded to the application (if not defined all features will be used) (digitizer >=1.4.9)

  • For font definitions, see issue 1308

    • fontSize: 38 definition without px

    • labelxOffset: 18 (not supported in 3.2.3)

    • labelYOffset: 18 (not supported in 3.2.3)

  • Types that are not supported in 3.2.4

    • upload

    • select with multiselect

    • coordinates

  • Clustering not implemented in 3.2.x

  • Style definition is limited not all OL2 styles can be defined

  • Support styling features with icons (interpret externalGraphic, graphicWidth, graphicHeight properties) (Mapbender >=3.2.7)

  • Support data placeholder syntax in externalGraphic (e.g. “/bundles/projectbundle/images/${type}.png”) (Mapbender >=3.2.7)

  • Save NULL for empty fields, works for int/float/decimal columns but not for double precision (Mapbender >= 3.2.6, see issue 1355)

  • Save NULL for empty fields for text fields does not work. Mapbender saves ‘’ instead (see issue 1385)

  • supports printable: true

There is a new style called unsaved.

unsaved:
    strokeWidth: 3
    strokeColor: "#f0f0f0"
    fillColor:   "#ffff"
    fillOpacity: 0.5
    pointRadius: 6
    label: 'Neu - bitte speichern'
    fontColor: red
    fontFamily: 'Arial, Courier New, monospace'
    fontColor: red
    fontSize: 38
    fontWeight: bold

WMS Layer visibility

Make sure that your WMS provides a proper extent for all supported EPSG-codes (this is used and saved in table mb_wms_wmslayersource columns latlonbounds and boundingboxes). Else it can happen that a layer is not requested for the given extent of your map.

Notice on the Sketch element

Redlining was renamed to Sketch (>= 3.2.3).

Update  public.mb_core_element set class = 'Mapbender\CoreBundle\Element\Sketch',
title = 'mb.core.sketch.class.title'
        where class = 'Mapbender\CoreBundle\Element\Redlining';

FeatureInfo

  • showOriginal deprecated - parameter not available anymore (from 3.2.3).

  • highlighting: true - new >= 3.2.3 highlights the geometry if you have WKT integrated in the featureinfo result - see issue 1287 and also this FeatureInfo blog post