Migrasi dan Kolom Userstamps

Paket ini tidak menerbitkan berkas migration sendiri. Sebagai gantinya, paket mendaftarkan empat macro Blueprint yang dipakai langsung di dalam migration aplikasi. UserstampsMacro::register memasang keempatnya, yaitu userstamps, softUserstamps, dropUserstamps, dan dropSoftUserstamps src/Database/Schema/Macros/UserstampsMacro.php:9-15¹. Pendaftaran dijalankan sekali dari bootingPackage pada service provider src/UserstampsServiceProvider.php:21-24², sehingga macro sudah tersedia untuk setiap migration yang dijalankan setelah paket di-boot. Berkas stub memberi anotasi @method untuk keempat macro itu beserta ringkasan efeknya stubs/Blueprint.php:5-10³.

Bentuk kolom yang dihasilkan

Nama kolom dibentuk dari opsi config ditambah akhiran _id. userstamps() membaca userstamps.created_by_column dan userstamps.updated_by_column, lalu menambahkan _id pada masing-masing sebelum memanggil addUserIdColumn src/Database/Schema/Macros/UserstampsMacro.php:52-69⁴. Dengan nilai default created_by, updated_by, dan deleted_by, kolom yang muncul adalah created_by_id, updated_by_id, dan deleted_by_id config/userstamps.php:73-110⁵. softUserstamps() memakai pola yang sama untuk satu kolom saja, yaitu deleted_by_column src/Database/Schema/Macros/UserstampsMacro.php:74-85⁶.

erDiagram
    users ||--o{ products : "created_by_id"
    users ||--o{ products : "updated_by_id"
    users ||--o{ products : "deleted_by_id"
    users {
        bigint id PK
    }
    products {
        integer id PK
        bigint created_by_id FK
        bigint updated_by_id FK
        bigint deleted_by_id FK
    }
    style users fill:#336791,color:#fff
    style products fill:#2d7d46,color:#fff
%% fig: Kolom userstamps pada tabel products
%% desc: Tiga kolom user ID di tabel products masing-masing menunjuk ke users.id lewat foreign key nullable ketika is_using_morph bernilai false.

Ketika userstamps.is_using_morph bernilai true, setiap kolom ID mendapat pasangan kolom _type bertipe string dan nullable. Urutan penulisan di dalam macro adalah <created>_id, <created>_type, <updated>_id, lalu <updated>_type src/Database/Schema/Macros/UserstampsMacro.php:52-69⁴. Perilaku morph dan tipe ID dibahas lebih rinci di Mode Morph dan Tipe Kolom ID.

Menambah kolom pada tabel baru

Pada tabel baru, macro dipanggil di dalam closure Schema::create setelah kolom primary key dibuat. Contoh dari test memakai tabel products tests/Feature/DatabaseMacrcoTest.php:64-70⁷:

Schema::create('products', function (Blueprint $table): void {
    $table->increments('id');
    $table->userstamps();
});

README menunjukkan pola yang sama untuk tabel baru, dengan userstamps() dan softUserstamps() dipanggil berurutan di dalam closure yang sama README.md:117-127⁸. Test createTableWithUserstamps hanya memanggil userstamps(), lalu kolom deleted_by_id ditambahkan terpisah lewat Schema::table tests/Feature/DatabaseMacrcoTest.php:72-77⁹.

Menambah kolom pada tabel yang sudah ada

Untuk tabel yang sudah berjalan, kedua macro dipanggil lewat closure Schema::table. Test menambahkan kolom soft delete pada tabel products yang sudah ada dengan cara ini tests/Feature/DatabaseMacrcoTest.php:72-77⁹:

Schema::table('products', function (Blueprint $table): void {
    $table->softUserstamps();
});

README memakai Schema::table yang sama untuk menambahkan userstamps() dan softUserstamps() sekaligus pada tabel lama, dan menempatkan pasangan drop* di method down() README.md:129-148¹⁰. Karena softUserstamps() berkaitan dengan soft delete, pemakaian kolom deleted_by_id saat model dihapus dibahas di Siklus Soft Delete dan Restore.

Tipe kolom ID dan foreign key

addUserIdColumn memilih builder kolom lewat match atas userstamps.users_table_id_column_type, dan hasilnya berbeda antara mode morph dan non-morph src/Database/Schema/Macros/UserstampsMacro.php:24-40¹¹.

graph TD
    M["userstamps()"] --> A["addUserIdColumn(table, column)"]
    S["softUserstamps()"] --> A
    A --> B{"is_using_morph"}
    B -->|false| C["foreignId / foreignUuid / foreignUlid nullable"]
    C --> D["foreign(column)->references(users_table_id_column_name)->on(users_table)->nullOnDelete()"]
    B -->|true| E["unsignedBigInteger / uuid / ulid nullable"]
    E --> F["kolom tambahan _type string nullable"]
    style M fill:#f59e0b,color:#000
    style S fill:#f59e0b,color:#000
    style A fill:#8b5cf6,color:#fff
    style B fill:#8b5cf6,color:#fff
    style C fill:#336791,color:#fff
    style D fill:#336791,color:#fff
    style E fill:#336791,color:#fff
    style F fill:#336791,color:#fff
%% fig: Cabang tipe kolom dan foreign key
%% desc: addUserIdColumn memilih builder kolom dan constraint berdasarkan is_using_morph serta users_table_id_column_type.

Nilai default bigIncrements dan daftar opsi yang didukung tercatat di config/userstamps.php:52-60¹². Pada mode non-morph, setelah kolom dibuat, macro menambahkan constraint foreign yang menunjuk userstamps.users_table_id_column_name pada tabel userstamps.users_table dengan nullOnDelete() src/Database/Schema/Macros/UserstampsMacro.php:42-47¹³. Kedua nilai itu default ke id dan users config/userstamps.php:20-33¹⁴. Pada mode morph, constraint foreign tidak dibuat karena relasi memakai kolom _type; karena itu users_table diabaikan, seperti dicatat pada komentar config config/userstamps.php:18-30¹⁵.

⚠️ is_using_morph memengaruhi kolom yang dihasilkan, jadi nilainya harus ditetapkan sebelum migration dijalankan. Mengubahnya setelah tabel terbentuk meninggalkan skema yang tidak sesuai dengan yang dibaca macro.

Test menjalankan alur lengkap untuk dua nilai is_using_morph, lalu mengulanginya dengan nama kolom kustom creator, editor, dan destroyer tests/Feature/DatabaseMacrcoTest.php:6-32¹⁶. Nama kustom itu menghasilkan creator_id, editor_id, dan destroyer_id karena akhiran _id selalu ditambahkan oleh macro src/Database/Schema/Macros/UserstampsMacro.php:52-69⁴.

Rollback dengan pasangan drop

Setiap macro penambah kolom punya pasangan pembuang kolom. dropUserstamps() menyusun daftar kolom created_by_id dan updated_by_id, membuang foreign key keduanya pada mode non-morph, menambahkan kolom _type pada daftar ketika morph aktif, lalu memanggil dropColumn src/Database/Schema/Macros/UserstampsMacro.php:89-105¹⁷. dropSoftUserstamps() melakukan hal yang sama untuk satu kolom, deleted_by_id src/Database/Schema/Macros/UserstampsMacro.php:110-123¹⁸.

Schema::table('products', function (Blueprint $table): void {
    $table->dropUserstamps();
    $table->dropSoftUserstamps();
});

Pola di atas adalah isi method down() pada README README.md:142-148¹⁹, dan test menjalankannya lewat dua fungsi terpisah, dropUserstamps() dan dropSoftUserstamps() tests/Feature/DatabaseMacrcoTest.php:79-91²⁰. Test kemudian memastikan kolom _id maupun _type tidak lagi ada di tabel products tests/Feature/DatabaseMacrcoTest.php:126-137²¹.

⚠️ Daftar kolom pada dropUserstamps() dan dropSoftUserstamps() dibaca dari config yang sama saat rollback. Kolom _type hanya masuk daftar ketika is_using_morph bernilai true, sehingga rollback dengan konfigurasi berbeda dari saat migrasi berisiko menyisakan kolom src/Database/Schema/Macros/UserstampsMacro.php:94-96²².