1. Preparation

To prepare the upgrade to Mayd 2 please follow these steps carefully.

Clone the repository again

The simplest way to migrate your project is starting from scratch. With this approach you can incrementally migrate your project code to Mayd 2. Therefore just clone your project again, but to another folder. We will use this new copy as our working copy.

Depending on your local setup, you have to configure your client to run the new project clone.

Create a new branch

Create a new branch for the update., for example master-mayd2. You will create all PRs that are needed for the migration against this branch.

Delete everything

We will now delete nearly all of the contents of the project. Don’t worry: you will be recreate everything for Mayd 2.

But by starting from scratch, you can be sure that only required code is included and you don’t have (now dead) Mayd 1 integration code still lying around.

Create a new branch e.g. mayd2-cleanup.
Keep the following files, delete everything else:
- .github/
- README.md
- CHANGELOG.md
- UPGRADE.md
- var/mayd/files/
Commit all your changes

Recreate basic configuration

The following examples are a good starting point for the new configuration of your project. You mayd need to change details, depending on your project’s concrete needs. This specifically applies to composer.json.

`composer.json`

The composer.json is updated to require all Mayd 2 packages and bump the most commonly used dependencies to a current version.

The example below uses the most current versions at the time of writing. Update it to use the most current versions – also see tip below.

{
    "name": "bklyn/projectName.website",
    "type": "project",
    "description": "Mayd 2: projectName",
    "license": "proprietary",
    "require": {
        "php": "^7.4",
        "ext-ctype": "*",
        "ext-dom": "*",
        "ext-iconv": "*",
        "ext-libxml": "*",
        "becklyn/assets-bundle": "^2.6.7",
        "becklyn/gluggi-bundle": "^3.2.1",
        "becklyn/hosting": "^3.0.4",
        "becklyn/icon-loader": "^2.1.1",
        "becklyn/rad-bundle": "^7.3.0",
        "doctrine/doctrine-bundle": "^2.0.7",
        "doctrine/doctrine-migrations-bundle": "^2.1.2",
        "mayd/core": "^2.5.4",
        "mayd/crud": "^1.4.4",
        "mayd/files": "^2.2.0",
        "mayd/foundation": "^2.6.7",
        "mayd/pages": "^2.6.4",
        "mayd/rich-text": "^2.0.2",
        "symfony/console": "^5.0.5",
        "symfony/dependency-injection": "5.0.4",
        "symfony/dotenv": "^5.0.5",
        "symfony/flex": "^1.6.2",
        "symfony/form": "^5.0.5",
        "symfony/framework-bundle": "^5.0.5",
        "symfony/monolog-bundle": "^3.5.0",
        "symfony/twig-bundle": "^5.0.5",
        "symfony/yaml": "^5.0.5"
    },
    "replace": {
        "paragonie/random_compat": "2.*",
        "symfony/polyfill-ctype": "*",
        "symfony/polyfill-iconv": "*",
        "symfony/polyfill-php72": "*",
        "symfony/polyfill-php73": "*",
        "symfony/polyfill-php74": "*"
    },
    "conflict": {
        "symfony/symfony": "*"
    },
    "require-dev": {
        "roave/security-advisories": "dev-master",
        "symfony/debug-pack": "^1.0.7",
        "symfony/profiler-pack": "^1.0.4"
    },
    "config": {
        "preferred-install": {
            "*": "dist"
        },
        "sort-packages": true
    },
    "extra": {
        "symfony": {
            "allow-contrib": false,
            "require": "^5.0"
        }
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "App\\Tests\\": "tests/"
        }
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://repo.packagist.com/mayd/"
        },
        {
            "packagist.org": false
        }
    ],
    "scripts": {
        "post-install-cmd": [
            "@auto-scripts"
        ],
        "post-update-cmd": [
            "@auto-scripts"
        ],
        "auto-scripts": {
            "cache:clear": "symfony-cmd",
            "assets:install %PUBLIC_DIR%": "symfony-cmd"
        }
    }
}

Always update to the very latest version and force composer to always use them by also updating your composer.json constraints.

So instead of "symfony/component": "^5.0" explicitly use the most current version and force it: "symfony/component": "^5.0.11".

`src/Kernel.php`

The kernel is just empty and extends the MaydKernel.

<?php declare(strict_types=1);

namespace App;

use Mayd\Core\Infrastructure\Kernel\MaydKernel;

final class Kernel extends MaydKernel
{
}

`config/packages/becklyn_hosting.yaml`

The hosting config is updated to the newest version. See the docs for becklyn/hosting for details about these config values.

becklyn_hosting:
    tier: '%env(HOSTING_TIER)%'
    project: projectName
    installation: projectName
    trackjs: '%env(TRACK_JS)%'

`config/packages/becklyn_assets.yaml`

By default the application uses the @app asset namespace.

becklyn_assets:
    namespaces:
        app: build

`config/packages/mayd.yaml`

By default your app should compile a mayd.css and mayd.js as main entries for the backend assets.

mayd:
    assets:
        header:
            - '@app/css/mayd.css'
        footer:
            - '@app/js/mayd.js'

`config/packages/mayd.yaml`

This file is empty for now and will later contain all mayd* config sections.

`.env`

TRACKJS_TOKEN=
HOSTING_TIER=development

`.gitignore`

# project files
/.php_cs.cache
/.stylelintcache
/node_modules
/public/assets
/studio.json
/vendor-bin/*/composer.lock
/vendor-bin/*/vendor

# Compiled Files
/build/css
/build/js

# Mimeo Path
/build/mayd

# ignore locally symlinked files
/.eslintrc.yml
/.stylelintrc.yml

###> symfony/framework-bundle ###
/.env.local
/.env.local.php
/.env.*.local
/public/bundles/
/var/
/vendor/
###< symfony/framework-bundle ###

###> symfony/phpunit-bridge ###
.phpunit
.phpunit.result.cache
###< symfony/phpunit-bridge ###

`package.json`

{
    "private": true,
    "dependencies": {
        "@mayd/app": "^1.1.1",
        "@mayd/beyond-werkstoff": "^1.9.4",
        "@mayd/crud": "^1.2.1",
        "@mayd/files": "^2.1.1",
        "@mayd/icons": "^1.5.7",
        "@mayd/minify": "^1.1.0",
        "@mayd/pages": "^2.3.2",
        "@mayd/rich-text": "^2.0.4",
        "mojave": "^5.9.4",
        "preact": "^10.3.0",
        "samos": "^3.0.0"
    },
    "devDependencies": {
        "core-js": "^3.6.4",
        "kaba": "^9.0.0",
        "kaba-scss": "^3.3.5"
    }
}

Always update to the very latest version and force npm/yarn to always use them by also updating your package.json constraints.

So instead of "@mayd/files": "^2.0" explicitly use the most current version and force it: "@mayd/files": "^2.0.11".

`assets/js/mayd.ts`

declare var DEBUG: boolean;

if (DEBUG)
{
    // eslint-disable-next-line global-require
    require("preact/debug");
}

import {init} from "@mayd/app";
import {MaydBundle} from "@mayd/app/src";
import maydBundles from "../mayd/backend";

class ProjectNameBackendBundle extends MaydBundle
{
    /**
     * @inheritDoc
     */
    public configure (): void
    {
    }
}

init(maydBundles.concat(ProjectNameBackendBundle));

`assets/scss/mayd.scss`

$mimeo-install-path: "../mayd";
@import "../mayd/backend";

`assets/js/projectName.ts`

import {init} from "@mayd/app";
import maydBundles from "../mayd/frontend";

init(maydBundles);

`assets/scss/projectName.scss`

$mimeo-install-path: "../mayd";

// Reset
@import "~samos/reset";

// Mayd
@import "../mayd/frontend";

`kaba.js`

const Kaba = require("kaba");
const {getKabaPostCssLoaderOptions} = require('@mayd/rich-text/js/build');

module.exports = (new Kaba())
    .addSassEntries({
        mayd: "assets/scss/mayd.scss",
        projectName: "assets/scss/projectName.scss",
    })
    .addJavaScriptEntries({
        mayd: "assets/js/mayd.ts",
        projectName: "assets/js/projectName.ts",
    })
    .setPostCssLoaderOptions(getKabaPostCssLoaderOptions());

`phpunit.xml`

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/8.5/phpunit.xsd"
         colors="true"
         bootstrap="vendor/autoload.php"
>
    <php>
        <ini name="error_reporting" value="-1" />
        <server name="APP_ENV" value="test" force="true" />
        <server name="SHELL_VERBOSITY" value="-1" />
        <server name="SYMFONY_PHPUNIT_REMOVE" value="" />
        <server name="SYMFONY_PHPUNIT_VERSION" value="8.5" />
        <env name="SYMFONY_DEPRECATIONS_HELPER" value="max[direct]=0"/>
    </php>

    <testsuites>
        <testsuite name="Project tests">
            <directory>tests</directory>
            <exclude>tests/fixtures</exclude>
        </testsuite>
    </testsuites>

    <filter>
        <whitelist>
            <directory suffix=".php">src/</directory>
        </whitelist>
    </filter>

    <listeners>
        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
    </listeners>
</phpunit>

Finish configuration

Run the following commands:

npm i
composer install
sf mayd:setup
./node_modules/.bin/kaba
composer bin test req becklyn/php-cs
cp .env .env.local

Afterwards, update the configuration in .env.local (and .env) to your needs. Your old configuration may help during this process.

Table of Contents

Clone the repository again
Create a new branch
Delete everything
Recreate basic configuration