./console exp:migration:generate --skeleton news_article_subtitle --description="The attribute Subtitle (subtitle, ezstring) of the class news_article, after Title" --apply

Exponential migrations: generate
Wrote migrations/20261101120000_news_article_subtitle.php
Migration 20261101120000_news_article_subtitle, class \Site\Migrations\NewsArticleSubtitle20261101120000
Next: fill in plan() and up(), then ./console exp:migration:check and ./console exp:migration:dry-run
PASS

./console exp:migration:migrate

Exponential migrations: dry run, nothing is changed (--apply runs the migrations)
Run 20261101-120118-5ea3b4, environment development, database sqlite (transactions: full)

  done        20261101110000_news_article_class            site               The content class News article (news_article) in the class group Content
  would-apply 20261101120000_news_article_subtitle         site               The attribute Subtitle (subtitle, ezstring) of the class news_article, after Title
              would add the attribute subtitle (ezstring, 150 characters) to news_article after title
              would give each of the 3 existing objects an empty subtitle

Captions: pre would-take, post would-take
Summary: 2 migration(s): 1 done, 1 pending, 0 not needed, 0 failed, 0 unknown; 1 would-apply
PASS

./console exp:migration:migrate --apply

  applied     20261101120000_news_article_subtitle         site               The attribute Subtitle (subtitle, ezstring) of the class news_article, after Title
              added the attribute subtitle to news_article at position 2
              gave the 3 existing objects the attribute

<?php
// description: The attribute Subtitle (subtitle, ezstring) of the class news_article, after Title
// requires: 20261101110000_news_article_class
// author: Site team
namespace Site\Migrations;

final class NewsArticleSubtitle20261101120000 extends \expMigrationPhp
{
    const CLASS_IDENTIFIER = 'news_article';
    const ATTRIBUTE = 'subtitle';
    const LANGUAGE = 'eng-US';

    private static function newsClass()
    {
        $class = \eZContentClass::fetchByIdentifier( self::CLASS_IDENTIFIER );
        if ( !$class instanceof \eZContentClass )
            throw new \RuntimeException( 'there is no class ' . self::CLASS_IDENTIFIER );
        return $class;
    }

    public function plan( $context )
    {
        $class = \eZContentClass::fetchByIdentifier( self::CLASS_IDENTIFIER );
        $objects = $class instanceof \eZContentClass ? $class->objectCount() : 0;
        return array( 'add the attribute ' . self::ATTRIBUTE . ' (ezstring, 150 characters) to ' . self::CLASS_IDENTIFIER . ' after title',
                      "give each of the $objects existing objects an empty subtitle" );
    }

    public function detect( $context )
    {
        $class = \eZContentClass::fetchByIdentifier( self::CLASS_IDENTIFIER );
        return $class instanceof \eZContentClass && $class->fetchAttributeByIdentifier( self::ATTRIBUTE )
             ? \expMigration::DONE : null;
    }

    public function up( $context )
    {
        $class = self::newsClass();
        $classId = (int)$class->attribute( 'id' );
        // make room after title: every attribute behind it moves one down
        $title = $class->fetchAttributeByIdentifier( 'title' );
        $placement = $title ? (int)$title->attribute( 'placement' ) + 1 : count( $class->fetchAttributes() ) + 1;
        foreach ( $class->fetchAttributes() as $existing )
        {
            if ( (int)$existing->attribute( 'placement' ) >= $placement )
            {
                $existing->setAttribute( 'placement', (int)$existing->attribute( 'placement' ) + 1 );
                $existing->store();
            }
        }
        $attribute = \eZContentClassAttribute::create( $classId, 'ezstring', array(
            'version' => \eZContentClass::VERSION_STATUS_DEFINED,
            'identifier' => self::ATTRIBUTE,
            'name' => 'Subtitle',
            'placement' => $placement,
            'is_required' => 0,
            'is_searchable' => 1,
            'can_translate' => 1,
            'is_information_collector' => 0,
            'data_int1' => 150,
        ), self::LANGUAGE );
        $attribute->dataType()->initializeClassAttribute( $attribute );
        $attribute->store();
        // the objects that exist get the new attribute in every version and language
        $attribute->initializeObjectAttributes();
        \eZContentClassAttribute::expireCache();
        return array( 'added the attribute subtitle to news_article at position ' . $placement,
                      'gave the ' . $class->objectCount() . ' existing objects the attribute' );
    }

    public function down( $context )
    {
        $class = self::newsClass();
        $attribute = $class->fetchAttributeByIdentifier( self::ATTRIBUTE );
        if ( !$attribute )
            return array( 'the attribute ' . self::ATTRIBUTE . ' is gone already' );
        $id = (int)$attribute->attribute( 'id' );
        if ( !$attribute->removeThis( true ) )
            throw new \RuntimeException( 'the attribute ' . self::ATTRIBUTE . ' cannot be removed' );
        // the values the objects kept for it
        $context->db()->query( "DELETE FROM ezcontentobject_attribute WHERE contentclassattribute_id = $id" );
        \eZContentClassAttribute::expireCache();
        return array( 'removed the attribute subtitle and its values' );
    }
}

./console exp:migration:rollback 20261101120000_news_article_subtitle --apply

  undone      20261101120000_news_article_subtitle         site               The attribute Subtitle (subtitle, ezstring) of the class news_article, after Title
              removed the attribute subtitle and its values