Skip to content

Migrating from v1.0.0 to v1.1.0

Table of Contents

New Features

Access Control

ZubZet now includes significantly enhanced access control and permission capabilities. This update introduces improved developer ergonomics, support for user-based permissions, and a more flexible and extensible authorization workflow.

Migration System

The migration system has been implemented. It provides developers with a structured and consistent way to manage database migrations, seed data, and environment-specific execution.

Global Helper Functions

To simplify development and reduce boilerplate, a set of global helper functions is now available. These helpers provide more convenient access to application objects and services.

Console

ZubZet can now be managed more efficiently through console commands. This allows for improved automation, maintenance, and development workflows.

Upgrade Steps

Follow these steps to upgrade your project to version 1.1.0. These changes ensure compatibility with the new migration architecture and automated deployment workflow.

You can automate most of these steps using the ZubZet Version Migrator.

  1. Clone the tool: zubzet/version-migration
  2. Run the upgrade command in your terminal: 
    php application.php upgrade {PATH_TO_YOUR_PROJECT} {YOUR_CURRENT_VERSION} 1.1.0

2. Manual Configuration Changes

2.1 Update Database Settings (z_settings.ini)

Add two new keys to your configuration. These elevated credentials are used specifically for schema modifications.

  • dbusername_elevated
  • dbpassword_elevated

If left empty, the system falls back to the default database user.

2.2 Update package.json

  • Seed Command: Change "php app/Database/import.php" to "php zubzet db:seed" in your seed script.
  • Start Script: Remove the && npm run seed suffix from your start script.

2.3 Docker Integration (docker-compose-base.yml)

Update your Docker configuration to include the new migration service and dependency checks.

Add the migration service:

services:
  migration:
    <<: *built-application-image
    command: php zubzet db:migrate
    restart: "no"
    depends_on:
      database:
        condition: service_healthy

Update x-built-application-image dependencies: Add the following to the depends_on section of your application image:

depends_on:
  migration:
    condition: service_completed_successfully

3. File & Schema Cleanup

3.1 Filename Convention Check

Every migration file in app/Database/migrations must follow the new format: YYYY-MM-DD_{INDEX}_{NAME}.{php/sql}

Review all existing files. If they do not match this pattern, rename them accordingly, or the migration system will abort.

3.2 Remove Legacy Framework Migrations

Delete migrations that target internal z_ tables (e.g., z_user, z_role, z_file).

  • Standard files to remove: 2021-02-04_zubzet.sql, 2025-11-06_user_permissions.

Ensure no local migrations modify these tables: z_email_verify, z_file, z_interaction_log, z_interaction_log_category, z_language, z_logintoken, z_logintry, z_login_too_many_tries, z_password_reset, z_role, z_role_permission, z_uniqueref, z_user, z_user_role, z_user_permission.