4 · Track and restore

TL;DR

Objective — make every vendor patch discoverable and re-applicable: log each one as a MOD-NNN, and run one restore script so composer install and vendor updates never quietly drop your work.

User part + done-when

👤 User part — small: a person reviews the MOD-NNN log after a vendor update to confirm each patch is still needed and was re-applied. Running the restore script and verifying counts is agent-runnable.

Done when every customization has a MOD-NNN row in the log, and running the restore script after composer install reports each customized package restored.  ·  ⏱ ~10–15 min  ·  🔀 mixed (👤 review, 🤖 restore).

Background

The overlay re-applies files; the tracking log explains them. Six months from now, a ZAJ:BEGIN MOD-001 marker in a vendor file means nothing without a record of what MOD-001 is, why it exists, and what breaks if it’s missing. The _CUSTOMIZATIONS log is that record — a numbered registry of every vendor modification.

The restore script closes the loop. Because a plain composer install restores vanilla vendor files, the script must run after it to copy your overlaid files back. It is also packaged as a downloadable kit so you can drop it into any project.

flowchart LR
  L["_CUSTOMIZATIONS log<br/>MOD-NNN registry"] --> O["resources/<br/>vendor-customizations/"]
  O --> S["restore script<br/>copies overlay → vendor/"]

Steps

1. Log each customization as a MOD-NNN entry

Every vendor patch gets a numbered, documented entry so it can be re-applied confidently after any update. Treat the log as the single source of truth for “what did we change in vendor code, and why.”

1. Add a MOD-NNN row for each customization, recording the fields that make it re-applicable.

   Field	What it captures
   ID	MOD-NNN — a stable identifier matching the ZAJ:BEGIN marker in the file
   File	the vendor path that was edited (e.g. app/Http/Controllers/HomeController.php)
   Vendor	which CodeCanyon app/version the patch targets
   Problem	what breaks without the patch
   Impact	the user-visible symptom (e.g. wrong migration count → redirect to /update)
   First added	the date, so you can correlate with vendor releases

   • ✅ Each customization has one numbered row capturing file, vendor, problem, impact, and date.

2. Keep an update checklist that lists every modified file and the action to take when a vendor update lands.

   File	Modification	Action on vendor update
   app/Http/Controllers/HomeController.php	MOD-001	Re-apply the ZajModules migration-path patch, then run the verification

   • ✅ The checklist names every file that will conflict on a vendor update and how to re-apply each patch.

Why the log earns its keep

Every vendor edit is technical debt. The log makes the debt visible: if you find yourself adding MOD-004, MOD-005, MOD-006, that is a signal to refactor toward event-driven ZajModules instead. A short, stable MOD-NNN list is the goal.

2. Run the restore script after composer install

The restore script reads the overlay and copies every customized file back over its vendor counterpart. Run it after any command that rewrites vendor/.

1. Run the script after composer install (or after a vendor update).

   composer install
   php Admin-Local/.../restore-vendor-customizations.php
   # Expected: "Found N customized package(s)" then a per-package "Restored N file(s)" summary

   • ✅ The summary lists each customized package and reports the files it restored.

The script scans resources/vendor-customizations/, finds each customized package folder, and recursively copies its files onto the matching package inside vendor/. If a package isn’t present in vendor/ (removed or renamed) it is skipped with a warning rather than failing the run. It also auto-extracts resources/vendor-customizations.zip if the unpacked directory isn’t there yet.

3. Verify the patches actually landed

A restore that reports success still needs a behavioral check — confirm the patched logic produces the right result, not just that files were copied.

1. Re-run the patch’s own verification. For the MOD-001 migration-scanner example, confirm the file count now matches the database count.

   php artisan tinker --execute="
   \$files = count(File::glob(database_path('migrations/*.php')));
   \$files += count(File::glob(database_path('migrations-zaj/*.php')));
   \$files += count(File::glob(base_path('packages/ZajModules/*/src/Database/Migrations/*.php')));
   \$db = DB::table('migrations')->count();
   echo 'Files: '.\$files.' | DB: '.\$db.' | Diff: '.(\$files - \$db);
   "
   # Expected: Diff: 0 (or close to 0)

   • ✅ The diff is 0 (or near it), confirming the patched scanner now sees every migration path.

2. Commit the re-applied patch with a message that names the MOD-NNN, so git log cross-references the registry.

   • ✅ The commit message references the MOD-NNN, e.g. “Re-apply ZajModules migration patch (MOD-001) after vendor update”.

Restore is part of every install, not an afterthought

Any time vendor/ is rewritten — a fresh composer install, a deploy, a vendor update — the overlay must be re-applied before you trust the app. Wire the restore step into your deploy and update routines so a patched file can never silently revert to vanilla in production.

4. Reuse the script as a kit

The restore script is generic — it works for any customized package, not just one — which is why it ships as a reusable kit you can drop into a new project.

1. Grab the packaged restore script from the kits and place it in your project’s scripts folder, then point your install/deploy routine at it.

   • ✅ The project has its own copy of restore-vendor-customizations.php wired into the install flow.

Checklist

Do not mark this step done until every box below is checked.

• 👤 Every patch logged — each customization has a MOD-NNN row (file, vendor, problem, impact, date) and an update-checklist entry.
• 🤖 Restore runs — restore-vendor-customizations.php runs after composer install and reports each package restored.
• 🤖 Patch verified — the patch’s own check passes (e.g. migration Diff: 0), not just “files copied”.
• 🔀 Committed + wired — the re-applied patch is committed referencing its MOD-NNN, and the restore step is part of the install/deploy routine.

→Next workflow

Vendor Updates — apply a new vendor release safely, restoring your customizations as part of the update.